From 6183f2448d2de79f48413d2a280ea61e8330b5a6 Mon Sep 17 00:00:00 2001
From: natinew77-creator <nati.new77@gmail.com>
Date: Tue, 11 Aug 2026 09:26:12 -0400
Subject: [PATCH 1/3] ENH: add the JupyterLite notebook setup cell

Installs MNE into the browser kernel with piplite and patches what Pyodide does
not provide: HTTP data fetching, the readers that expect a file on disk, and a
few things that need OS threads.
---
 doc/sphinxext/jupyterlite_setup_cell.py | 896 ++++++++++++++++++++++++
 1 file changed, 896 insertions(+)
 create mode 100644 doc/sphinxext/jupyterlite_setup_cell.py

diff --git a/doc/sphinxext/jupyterlite_setup_cell.py b/doc/sphinxext/jupyterlite_setup_cell.py
new file mode 100644
index 00000000000..10729a27cb8
--- /dev/null
+++ b/doc/sphinxext/jupyterlite_setup_cell.py
@@ -0,0 +1,896 @@
+"""The setup cell prepended to every JupyterLite notebook.
+
+This installs MNE into the browser kernel and patches the bits of the
+environment Pyodide does not provide: data fetching over HTTP, the readers
+that expect files already on disk, and the 3D renderer.
+
+The docs build prepends it only to the notebooks copied into the JupyterLite
+contents. It deliberately does NOT go through ``first_notebook_cell``: that is
+applied when the notebook is generated, so it would also land in the ``.ipynb``
+offered for download, where ``piplite`` does not exist and the notebook would
+fail on its first cell.
+"""
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+from jupyterlite_lite_renderer import LITE_RENDERER_CELL
+
+LITE_SETUP_CELL = (
+    "# 💡 This cell is automatically added to the start of each notebook.\n"
+    "# It installs MNE and patches the browser environment for Pyodide.\n"
+    "import piplite\n"
+    "# Use piplite (not micropip) so the locally-built development MNE wheel\n"
+    "# bundled into the JupyterLite build is preferred over the older PyPI\n"
+    "# release;\n"
+    "# piplite checks the local index first and falls back to PyPI for deps.\n"
+    "# keep_going=True lets it install even if Pyodide's bundled\n"
+    "# matplotlib/scipy/numpy are older than MNE's declared minimums.\n"
+    "await piplite.install(\n"
+    "    ['mne', 'scikit-learn', 'joblib', 'pandas', 'seaborn', "
+    "'mne-connectivity', 'nibabel', 'pyvista-js', 'pyxdf', 'mffpy', "
+    "'python-picard'],\n"
+    "    keep_going=True,\n"
+    ")\n"
+    "\n"
+    "import sys\n"
+    "import os\n"
+    "import io\n"
+    "\n"
+    "# lzma: try real stdlib first (Pyodide ships it); only mock if absent\n"
+    "try:\n"
+    "    import lzma\n"
+    "except ImportError:\n"
+    "    class _LZMAFile:\n"
+    "        def __init__(self, *a, **kw): pass\n"
+    "        def __enter__(self): return self\n"
+    "        def __exit__(self, *a): pass\n"
+    "        def write(self, d): pass\n"
+    "        def read(self, n=-1): return b''\n"
+    "        def close(self): pass\n"
+    "    class _MockLZMA:\n"
+    "        LZMAError = Exception\n"
+    "        LZMAFile = _LZMAFile\n"
+    "        FORMAT_XZ = 1\n"
+    "        FORMAT_ALONE = 2\n"
+    "        def __getattr__(self, name): return object\n"
+    "    import sys as _sys\n"
+    "    _sys.modules['lzma'] = _MockLZMA()\n"
+    "\n"
+    "# Mock multiprocessing — missing in Pyodide but imported by joblib\n"
+    "from unittest.mock import MagicMock\n"
+    "if 'multiprocessing' not in sys.modules:\n"
+    "    m = MagicMock()\n"
+    "    m.cpu_count.return_value = 1\n"
+    "    sys.modules['multiprocessing'] = m\n"
+    "    sys.modules['multiprocessing.util'] = m.util\n"
+    "    sys.modules['multiprocessing.pool'] = m.pool\n"
+    "\n"
+    "# Patch requests so pooch can fetch files already on /drive/mne_data.\n"
+    "# open_url works for both text and binary in Pyodide >= 0.21.\n"
+    "import requests\n"
+    "import pyodide\n"
+    "orig_send = requests.Session.send\n"
+    "def pyodide_send(self, request, **kwargs):\n"
+    "    try:\n"
+    "        buf = pyodide.http.open_url(request.url)\n"
+    "        content = buf.getvalue() if hasattr(buf, 'getvalue') else buf.read()\n"
+    "        if isinstance(content, str):\n"
+    "            content = content.encode('utf-8')\n"
+    "    except Exception as e:\n"
+    "        print(f'open_url failed for {request.url}: {e}')\n"
+    "        return orig_send(self, request, **kwargs)\n"
+    "    response = requests.Response()\n"
+    "    response.status_code = 200\n"
+    "    response.url = request.url\n"
+    "    response.raw = io.BytesIO(content)\n"
+    "    return response\n"
+    "requests.Session.send = pyodide_send\n"
+    "\n"
+    "# /drive/ in Pyodide requires Cross-Origin-Isolation headers\n"
+    "# (COOP/COEP) which many static servers (e.g. CircleCI artifacts)\n"
+    "# do not send. Fetch the data over HTTP into /tmp/mne_data instead\n"
+    "# — same-origin, no CORS. The data is served at the docs root\n"
+    "# (/mne_data/...) via Sphinx html_extra_path.\n"
+    "# Pyodide may run in a web worker (no `window`); `location` exists\n"
+    "# in both the main thread and workers, so use it to find the docs\n"
+    "# root by splitting on '/lite/'.\n"
+    "import pyodide.http as _phttp\n"
+    "import js as _js\n"
+    "try:\n"
+    "    _page = str(_js.location.href)\n"
+    "except Exception:\n"
+    "    _page = str(_js.window.location.href)\n"
+    "_base = _page.split('/lite/')[0] + '/mne_data/'\n"
+    "mne_data_path = '/tmp/mne_data'\n"
+    "_sample_dir = mne_data_path + '/MNE-sample-data'\n"
+    "# Eager 'core': small, commonly-used sample files fetched once at\n"
+    "# notebook start. The heavy files (raw / filt raw / ernoise / fwd /\n"
+    "# inv / src, ~360 MB total) are intentionally omitted here -- they are\n"
+    "# fetched lazily on first read via the reader shims below, so each\n"
+    "# notebook only downloads the sample files it actually uses.\n"
+    "_sample_files = [\n"
+    "    'version.txt',\n"
+    "    'MEG/sample/sample_audvis_raw-eve.fif',\n"
+    "    'MEG/sample/sample_audvis_filt-0-40_raw-eve.fif',\n"
+    "    'MEG/sample/sample_audvis_ecg-proj.fif',\n"
+    "    'MEG/sample/sample_audvis-cov.fif',\n"
+    "    'MEG/sample/sample_audvis-ave.fif',\n"
+    "    'MEG/sample/sample_audvis-no-filter-ave.fif',\n"
+    "    'MEG/sample/sample_audvis_raw-trans.fif',\n"
+    "    'MEG/sample/sample_audvis-shrunk-cov.fif',\n"
+    "    'MEG/sample/sample_audvis-meg-lh.stc',\n"
+    "    'MEG/sample/sample_audvis-meg-rh.stc',\n"
+    "    'subjects/sample/mri/T1.mgz',\n"
+    "    'subjects/sample/surf/rh.pial',\n"
+    "    'subjects/sample/surf/lh.pial',\n"
+    "    'subjects/sample/surf/rh.white',\n"
+    "    'subjects/sample/surf/lh.white',\n"
+    "    'subjects/sample/label/lh.aparc.annot',\n"
+    "    'subjects/sample/label/rh.aparc.annot',\n"
+    "    'SSS/sss_cal_mgh.dat',\n"
+    "    'SSS/ct_sparse_mgh.fif',\n"
+    "]\n"
+    "print('Fetching MNE sample data (once per session)...')\n"
+    "for _f in _sample_files:\n"
+    "    _dst = _sample_dir + '/' + _f\n"
+    "    if os.path.exists(_dst):\n"
+    "        continue\n"
+    "    _url = _base + 'MNE-sample-data/' + _f\n"
+    "    try:\n"
+    "        _r = await _phttp.pyfetch(_url)\n"
+    "        if _r.status != 200:\n"
+    "            print(f'  HTTP {_r.status} for {_url}')\n"
+    "            continue\n"
+    "        _d = await _r.bytes()\n"
+    "        if _d[:4] == b'<!DO' or _d[:5] == b'<html':\n"
+    "            print(f'  skipped {_f} (server returned HTML)')\n"
+    "            continue\n"
+    "        os.makedirs(os.path.dirname(_dst), exist_ok=True)\n"
+    "        with open(_dst, 'wb') as _fh:\n"
+    "            _fh.write(_d)\n"
+    "    except Exception as _e:\n"
+    "        print(f'  failed to fetch {_f}: {_e}')\n"
+    "os.makedirs(mne_data_path, exist_ok=True)\n"
+    "os.environ['MNE_DATA'] = mne_data_path\n"
+    "os.environ['MNE_DATASETS_SAMPLE_PATH'] = mne_data_path\n"
+    "\n"
+    "# Block pooch from attempting large OSF downloads in the browser.\n"
+    "# The required files are either pre-injected or unavailable.\n"
+    "import pooch\n"
+    "orig_pooch_fetch = pooch.Pooch.fetch\n"
+    "def pyodide_pooch_fetch(self, fname, processor=None, downloader=None):\n"
+    "    url = self.get_url(fname)\n"
+    "    if 'osf.io' in url or 'files.osf.io' in url:\n"
+    "        raise RuntimeError(\n"
+    "            f'Cannot download {fname!r} from OSF in JupyterLite: '\n"
+    "            'browser CORS policy and memory limits prevent large '\n"
+    "            'dataset downloads. Open this notebook from mne.tools '\n"
+    "            'where sample data is pre-bundled, or run it locally.'\n"
+    "        )\n"
+    "    return orig_pooch_fetch(\n"
+    "        self, fname, processor=processor, downloader=downloader\n"
+    "    )\n"
+    "pooch.Pooch.fetch = pyodide_pooch_fetch\n"
+    "\n"
+    "# Import MNE and finalize setup.\n"
+    "import mne\n"
+    "# Pre-create a valid empty config file so MNE never hits a corrupt read.\n"
+    "_cfg = mne.get_config_path()\n"
+    "os.makedirs(os.path.dirname(_cfg), exist_ok=True)\n"
+    "if not os.path.exists(_cfg):\n"
+    "    with open(_cfg, 'w') as _f:\n"
+    "        _f.write('{}')\n"
+    "mne.set_config('MNE_DATA', mne_data_path)\n"
+    "for ds in ['SAMPLE', 'TESTING', 'SSVEP', 'EEGBCI', 'SOMATO',\n"
+    "           'BRAINSTORM']:\n"
+    "    mne.set_config(f'MNE_DATASETS_{ds}_PATH', mne_data_path)\n"
+    "\n"
+    "# Bypass pooch's archive check: data_path() normally looks for the\n"
+    "# .tar.gz archive, not just the extracted folder. Return the folder\n"
+    "# directly so pooch never tries to download from OSF. Return a Path\n"
+    "# (not a str) since tutorials use the / operator on the result.\n"
+    "from pathlib import Path as _Path\n"
+    "_sample_path = _Path(_sample_dir)\n"
+    "def _lite_sample_data_path(*_a, **_kw):\n"
+    "    return _sample_path\n"
+    "mne.datasets.sample.data_path = _lite_sample_data_path\n"
+    "# Several non-sample datasets are each used by only a couple of\n"
+    "# notebooks (kiloword/erp_core for Epochs 30 & 40; mtrf/eegbci for the\n"
+    "# decoding examples), so fetch them LAZILY — only when their\n"
+    "# data_path()/load_data() is called — to avoid taxing every other\n"
+    "# notebook's setup. Pyodide runs in a web worker here, where a\n"
+    "# synchronous XHR may set responseType='arraybuffer', letting a sync\n"
+    "# data_path() read binary.\n"
+    "def _lite_fetch_rel(_rel):\n"
+    "    _dst = mne_data_path + '/' + _rel\n"
+    "    if not os.path.exists(_dst):\n"
+    "        from js import XMLHttpRequest\n"
+    "        _xhr = XMLHttpRequest.new()\n"
+    "        _xhr.open('GET', _base + _rel, False)\n"
+    "        _xhr.responseType = 'arraybuffer'\n"
+    "        _xhr.send()\n"
+    "        if _xhr.status != 200:\n"
+    "            raise FileNotFoundError(\n"
+    "                f'Could not fetch {_rel} (HTTP {_xhr.status})'\n"
+    "            )\n"
+    "        os.makedirs(os.path.dirname(_dst), exist_ok=True)\n"
+    "        with open(_dst, 'wb') as _fh:\n"
+    "            _fh.write(bytes(_xhr.response.to_py()))\n"
+    "    return _dst\n"
+    "def _lite_lazy_fetch(_folder, _fname):\n"
+    "    _lite_fetch_rel(_folder + '/' + _fname)\n"
+    "    return _Path(mne_data_path + '/' + _folder)\n"
+    "def _lite_kiloword_data_path(*_a, **_kw):\n"
+    "    return _lite_lazy_fetch("
+    "'MNE-kiloword-data', 'kword_metadata-epo.fif')\n"
+    "mne.datasets.kiloword.data_path = _lite_kiloword_data_path\n"
+    "def _lite_erp_core_data_path(*_a, **_kw):\n"
+    "    return _lite_lazy_fetch(\n"
+    "        'MNE-ERP-CORE-data', "
+    "'ERP-CORE_Subject-001_Task-Flankers_eeg.fif'\n"
+    "    )\n"
+    "mne.datasets.erp_core.data_path = _lite_erp_core_data_path\n"
+    "def _lite_mtrf_data_path(*_a, **_kw):\n"
+    "    return _lite_lazy_fetch('mTRF_1.5', 'speech_data.mat')\n"
+    "mne.datasets.mtrf.data_path = _lite_mtrf_data_path\n"
+    "# testing hands back the folder and lets the shimmed readers pull\n"
+    "# individual files, so a notebook that wants the EEGLAB recording does\n"
+    "# not also drag down the 39 MB movement raw.\n"
+    "def _lite_testing_data_path(*_a, **_kw):\n"
+    "    return _Path(mne_data_path + '/MNE-testing-data')\n"
+    "mne.datasets.testing.data_path = _lite_testing_data_path\n"
+    "# Same again for the datasets behind a single example each. Only the\n"
+    "# files those examples read are served, and the shimmed readers below\n"
+    "# pull them individually.\n"
+    "def _lite_folder_data_path(_folder):\n"
+    "    def _data_path(*_a, **_kw):\n"
+    "        return _Path(mne_data_path + '/' + _folder)\n"
+    "    return _data_path\n"
+    "for _ds, _folder in (\n"
+    "    ('ssvep', 'ssvep-example-data'),\n"
+    "    ('misc', 'MNE-misc-data'),\n"
+    "    ('eyelink', 'MNE-eyelink-data'),\n"
+    "    ('fnirs_motor', 'MNE-fNIRS-motor-data'),\n"
+    "    ('refmeg_noise', 'MNE-refmeg-noise-data'),\n"
+    "    ('phantom_kernel', 'MNE-phantom-kernel-data'),\n"
+    "    ('multimodal', 'MNE-multimodal-data'),\n"
+    "):\n"
+    "    getattr(mne.datasets, _ds).data_path = _lite_folder_data_path(_folder)\n"
+    "def _lite_eegbci_load_data(subject, runs, *_a, **_kw):\n"
+    "    _runs = [runs] if isinstance(runs, (int, float)) else list(runs)\n"
+    "    _subjects = (\n"
+    "        list(subject) if isinstance(subject, (list, tuple))\n"
+    "        else [subject]\n"
+    "    )\n"
+    "    _out = []\n"
+    "    for _s in _subjects:\n"
+    "        for _r in _runs:\n"
+    "            _rel = (\n"
+    "                'MNE-eegbci-data/files/eegmmidb/1.0.0/'\n"
+    "                f'S{int(_s):03d}/S{int(_s):03d}R{int(_r):02d}.edf'\n"
+    "            )\n"
+    "            _out.append(_Path(_lite_fetch_rel(_rel)))\n"
+    "    return _out\n"
+    "mne.datasets.eegbci.load_data = _lite_eegbci_load_data\n"
+    "\n"
+    "# Some MNE-sample-data files (e.g. the fixed-orientation forward/\n"
+    "# inverse used by the point-spread tutorial) aren't in the eager\n"
+    "# _sample_files list above because only one or two notebooks need\n"
+    "# them. Rather than hand-listing every such file, lazily fetch any\n"
+    "# sample-data path the first time read_forward_solution/\n"
+    "# read_inverse_operator is asked to open it.\n"
+    "def _lite_fetch_if_under_mne_data(fname):\n"
+    "    _p = str(fname)\n"
+    "    if _p.startswith(mne_data_path + '/'):\n"
+    "        _lite_fetch_rel(_p[len(mne_data_path) + 1:])\n"
+    "    return fname\n"
+    "# Most readers just need their file pulled down before MNE opens it.\n"
+    "# One wrapper, driven by the table further below; readers that need\n"
+    "# more than this (a sibling file, a chain of candidates) keep their\n"
+    "# own shim.\n"
+    "def _lite_wrap_reader(_mods, _name, _arg):\n"
+    "    _orig = getattr(_mods[0], _name)\n"
+    "    def _wrapped(*_a, **_kw):\n"
+    "        if _a:\n"
+    "            _a = (_lite_fetch_if_under_mne_data(_a[0]),) + _a[1:]\n"
+    "        elif _arg in _kw:\n"
+    "            # positionally, as the hand-written shims did\n"
+    "            _a = (_lite_fetch_if_under_mne_data(_kw.pop(_arg)),)\n"
+    "        return _orig(*_a, **_kw)\n"
+    "    for _m in _mods:\n"
+    "        setattr(_m, _name, _wrapped)\n"
+    "# Lazily fetch the heavy sample raw / source-space files only when a\n"
+    "# notebook actually reads them (same pattern as the fwd/inv shims\n"
+    "# above), instead of pulling the whole sample set up front.\n"
+    "# Nearly every MNE reader validates its filename through\n"
+    "# _check_fname(must_exist=True) before opening it, so hooking that one\n"
+    "# function covers read_info, read_evokeds, read_cov, read_label and the\n"
+    "# rest without a wrapper each. Failures stay silent here so MNE still\n"
+    "# raises its own, clearer error for a file that genuinely is missing.\n"
+    "import mne.utils.check as _mne_check\n"
+    "_orig_check_fname = _mne_check._check_fname\n"
+    "def _lite_check_fname(fname, overwrite=False, must_exist=False,\n"
+    "                      *_a, **_kw):\n"
+    "    if must_exist:\n"
+    "        try:\n"
+    "            _lite_fetch_if_under_mne_data(fname)\n"
+    "        except Exception:\n"
+    "            pass\n"
+    "    return _orig_check_fname(fname, overwrite, must_exist, *_a, **_kw)\n"
+    "_mne_check._check_fname = _lite_check_fname\n"
+    "# modules that imported it before now hold their own reference; ones\n"
+    "# loaded later (mne lazy-loads most of itself) pick up the patch\n"
+    "for _m in list(sys.modules.values()):\n"
+    "    if (getattr(_m, '__name__', '').startswith('mne')\n"
+    "            and getattr(_m, '_check_fname', None) is _orig_check_fname):\n"
+    "        _m._check_fname = _lite_check_fname\n"
+    "# read_label, read_epochs and read_raw_edf open their file directly\n"
+    "# rather than validating it first, so the hook above never sees them\n"
+    "# an EEGLAB .set keeps its samples in a sibling .fdt, so fetch both\n"
+    "_orig_read_raw_eeglab = mne.io.read_raw_eeglab\n"
+    "def _lite_read_raw_eeglab(input_fname, *_a, **_kw):\n"
+    "    _p = str(input_fname)\n"
+    "    if _p.startswith(mne_data_path + '/'):\n"
+    "        for _cand in (_p, _p[:-4] + '.fdt'):\n"
+    "            try:\n"
+    "                _lite_fetch_rel(_cand[len(mne_data_path) + 1:])\n"
+    "            except Exception:\n"
+    "                pass\n"
+    "    return _orig_read_raw_eeglab(input_fname, *_a, **_kw)\n"
+    "mne.io.read_raw_eeglab = _lite_read_raw_eeglab\n"
+    "# read_raw_nirx and read_raw_egi open a folder, so there is no single\n"
+    "# name to fetch; conf.py leaves a listing next to the copy.\n"
+    "def _lite_fetch_dir(_rel):\n"
+    "    _manifest = _lite_fetch_rel(_rel + '/_lite_manifest.txt')\n"
+    "    with open(_manifest) as _fh:\n"
+    "        _names = [_n.strip() for _n in _fh if _n.strip()]\n"
+    "    for _name in _names:\n"
+    "        # one unreachable member must not abandon the rest of the\n"
+    "        # recording; the reader complains if it needed that file\n"
+    "        try:\n"
+    "            _lite_fetch_rel(_rel + '/' + _name)\n"
+    "        except Exception as _e:\n"
+    "            print('[JupyterLite] skipped ' + _name + ': ' + repr(_e))\n"
+    "    return mne_data_path + '/' + _rel\n"
+    "def _lite_dir_reader(_orig):\n"
+    "    def _read(fname, *_a, **_kw):\n"
+    "        _p = str(fname)\n"
+    "        if _p.startswith(mne_data_path + '/'):\n"
+    "            try:\n"
+    "                _lite_fetch_dir(_p[len(mne_data_path) + 1:])\n"
+    "            except Exception as _e:\n"
+    "                print('[JupyterLite] could not fetch '\n"
+    "                      + _p + ': ' + repr(_e))\n"
+    "        return _orig(fname, *_a, **_kw)\n"
+    "    return _read\n"
+    "mne.io.read_raw_nirx = _lite_dir_reader(mne.io.read_raw_nirx)\n"
+    "mne.io.read_raw_egi = _lite_dir_reader(mne.io.read_raw_egi)\n"
+    "# the logging tutorial reads a KIT file from inside the installed\n"
+    "# package; the wheel excludes mne/**/tests, so stage the served copy\n"
+    "# into the path the tutorial builds rather than editing the tutorial\n"
+    "import shutil as _shutil\n"
+    "_orig_read_raw_kit = mne.io.read_raw_kit\n"
+    "def _lite_read_raw_kit(input_fname, *_a, **_kw):\n"
+    "    _p = str(input_fname)\n"
+    "    if _p.endswith('test.sqd') and not os.path.exists(_p):\n"
+    "        try:\n"
+    "            _staged = _lite_fetch_rel('MNE-kit-testdata/test.sqd')\n"
+    "            os.makedirs(os.path.dirname(_p), exist_ok=True)\n"
+    "            _shutil.copyfile(_staged, _p)\n"
+    "        except Exception as _e:\n"
+    "            print('[JupyterLite] could not stage test.sqd: ' + repr(_e))\n"
+    "    return _orig_read_raw_kit(input_fname, *_a, **_kw)\n"
+    "mne.io.read_raw_kit = _lite_read_raw_kit\n"
+    "# a BrainVision .vhdr is a text header pointing at a .eeg and a .vmrk\n"
+    "_orig_read_raw_brainvision = mne.io.read_raw_brainvision\n"
+    "def _lite_read_raw_brainvision(vhdr_fname, *_a, **_kw):\n"
+    "    _p = str(vhdr_fname)\n"
+    "    if _p.startswith(mne_data_path + '/'):\n"
+    "        _stem = _p[:-5] if _p.endswith('.vhdr') else _p\n"
+    "        for _cand in (_p, _stem + '.eeg', _stem + '.vmrk'):\n"
+    "            try:\n"
+    "                _lite_fetch_rel(_cand[len(mne_data_path) + 1:])\n"
+    "            except Exception:\n"
+    "                pass\n"
+    "    return _orig_read_raw_brainvision(vhdr_fname, *_a, **_kw)\n"
+    "mne.io.read_raw_brainvision = _lite_read_raw_brainvision\n"
+    "# eyelink .asc recordings are single files\n"
+    "# the heatmap example draws its stimulus straight through pyplot, and\n"
+    "# read_xdf goes through pyxdf -- neither is an MNE reader, so shim the\n"
+    "# two entry points as well\n"
+    "import matplotlib.pyplot as _plt\n"
+    "_orig_imread = _plt.imread\n"
+    "def _lite_imread(fname, *_a, **_kw):\n"
+    "    return _orig_imread(_lite_fetch_if_under_mne_data(fname), *_a, **_kw)\n"
+    "_plt.imread = _lite_imread\n"
+    "try:\n"
+    "    import pyxdf as _pyxdf\n"
+    "    _orig_load_xdf = _pyxdf.load_xdf\n"
+    "    def _lite_load_xdf(fname, *_a, **_kw):\n"
+    "        return _orig_load_xdf(\n"
+    "            _lite_fetch_if_under_mne_data(fname), *_a, **_kw\n"
+    "        )\n"
+    "    _pyxdf.load_xdf = _lite_load_xdf\n"
+    "except Exception:\n"
+    "    pass\n"
+    "# The readers that only need the fetch. Two of them are bound on a\n"
+    "# private alias as well as the public one, so both are listed.\n"
+    "import mne.minimum_norm as _mne_minv\n"
+    "import mne.chpi as _mne_chpi\n"
+    "for _mods, _name, _arg in (\n"
+    "    ((mne,), 'read_forward_solution', 'fname'),\n"
+    "    ((_mne_minv, mne.minimum_norm), 'read_inverse_operator', 'fname'),\n"
+    "    ((mne.io,), 'read_raw_fif', 'fname'),\n"
+    "    ((mne.io,), 'read_raw', 'fname'),\n"
+    "    ((mne,), 'read_source_spaces', 'fname'),\n"
+    "    ((mne,), 'read_label', 'filename'),\n"
+    "    ((mne,), 'read_epochs', 'fname'),\n"
+    "    ((mne.io,), 'read_raw_edf', 'input_fname'),\n"
+    "    ((mne,), 'read_bem_solution', 'fname'),\n"
+    "    ((mne,), 'read_events', 'fname'),\n"
+    "    ((mne.io,), 'read_raw_eyelink', 'fname'),\n"
+    "    ((_mne_chpi, mne.chpi), 'read_head_pos', 'fname'),\n"
+    "):\n"
+    "    _lite_wrap_reader(_mods, _name, _arg)\n"
+    "# read_source_estimate is handed the stem of a .stc pair, so fetch\n"
+    "# both hemispheres before letting MNE resolve the name itself.\n"
+    "_orig_read_source_estimate = mne.read_source_estimate\n"
+    "def _lite_read_source_estimate(fname, *_a, **_kw):\n"
+    "    _p = str(fname)\n"
+    "    if _p.startswith(mne_data_path + '/'):\n"
+    "        for _suf in ('', '-lh.stc', '-rh.stc'):\n"
+    "            try:\n"
+    "                _lite_fetch_rel(_p[len(mne_data_path) + 1:] + _suf)\n"
+    "            except Exception:\n"
+    "                pass\n"
+    "    return _orig_read_source_estimate(fname, *_a, **_kw)\n"
+    "mne.read_source_estimate = _lite_read_source_estimate\n"
+    "# plot_alignment locates its head surface by probing the filesystem\n"
+    "# with os.path.exists before any reader runs, so a reader shim never\n"
+    "# fires. Fetch the candidates first and let MNE choose as it normally\n"
+    "# would. Several viz modules bind the name at import time, so rebind\n"
+    "# it wherever the original landed instead of in one known place.\n"
+    "import mne._freesurfer as _mne_fs\n"
+    "_orig_get_head_surface = _mne_fs._get_head_surface\n"
+    "def _lite_get_head_surface(surf, subject, subjects_dir, bem=None,\n"
+    "                           verbose=None):\n"
+    "    _sd = str(subjects_dir) if subjects_dir is not None else ''\n"
+    "    if subject and _sd.startswith(mne_data_path + '/'):\n"
+    "        _rel = _sd[len(mne_data_path) + 1:] + '/' + str(subject)\n"
+    "        if surf in ('head-dense', 'seghead'):\n"
+    "            _cands = ['bem/' + str(subject) + '-head-dense.fif',\n"
+    "                      'surf/lh.seghead']\n"
+    "        else:\n"
+    "            # same order MNE tries, so the browser picks the same\n"
+    "            # surface the rendered docs did\n"
+    "            _cands = ['bem/outer_skin.surf',\n"
+    "                      'bem/' + str(subject) + '-head.fif']\n"
+    "        for _c in _cands:\n"
+    "            try:\n"
+    "                _lite_fetch_rel(_rel + '/' + _c)\n"
+    "            except Exception:\n"
+    "                pass\n"
+    "    return _orig_get_head_surface(\n"
+    "        surf, subject, subjects_dir, bem=bem, verbose=verbose\n"
+    "    )\n"
+    "_mne_fs._get_head_surface = _lite_get_head_surface\n"
+    "# import the 3D module first so the sweep below is guaranteed to see\n"
+    "# it; anything imported later picks the patched name up on its own.\n"
+    "import mne.viz._3d  # noqa: F401\n"
+    "for _m in list(sys.modules.values()):\n"
+    "    if (getattr(_m, '__name__', '').startswith('mne')\n"
+    "            and getattr(_m, '_get_head_surface', None)\n"
+    "            is _orig_get_head_surface):\n"
+    "        _m._get_head_surface = _lite_get_head_surface\n"
+    "# same story for the skull surfaces, which _check_fname insists\n"
+    "# already exist on disk\n"
+    "_orig_get_skull_surface = _mne_fs._get_skull_surface\n"
+    "def _lite_get_skull_surface(surf, subject, subjects_dir, bem=None,\n"
+    "                            verbose=None):\n"
+    "    _sd = str(subjects_dir) if subjects_dir is not None else ''\n"
+    "    if subject and _sd.startswith(mne_data_path + '/'):\n"
+    "        try:\n"
+    "            _lite_fetch_rel(\n"
+    "                _sd[len(mne_data_path) + 1:] + '/' + str(subject)\n"
+    "                + '/bem/' + surf + '_skull.surf'\n"
+    "            )\n"
+    "        except Exception:\n"
+    "            pass\n"
+    "    return _orig_get_skull_surface(\n"
+    "        surf, subject, subjects_dir, bem=bem, verbose=verbose\n"
+    "    )\n"
+    "_mne_fs._get_skull_surface = _lite_get_skull_surface\n"
+    "for _m in list(sys.modules.values()):\n"
+    "    if (getattr(_m, '__name__', '').startswith('mne')\n"
+    "            and getattr(_m, '_get_skull_surface', None)\n"
+    "            is _orig_get_skull_surface):\n"
+    "        _m._get_skull_surface = _lite_get_skull_surface\n"
+    "# dig_mri_distances reaches a second, unrelated _get_head_surface, the\n"
+    "# one in mne/surface.py: it takes a list of candidate sources and\n"
+    "# probes bem/ with os.path.exists and glob, raising if the directory\n"
+    "# is absent, so the candidates have to land before it runs.\n"
+    "import mne.surface as _mne_surface\n"
+    "_orig_surface_head = _mne_surface._get_head_surface\n"
+    "def _lite_surface_head_surface(subject, source, subjects_dir,\n"
+    "                               on_defects, raise_error=True):\n"
+    "    _sd = str(subjects_dir) if subjects_dir is not None else ''\n"
+    "    if subject and _sd.startswith(mne_data_path + '/'):\n"
+    "        _rel = _sd[len(mne_data_path) + 1:] + '/' + str(subject)\n"
+    "        _srcs = [source] if isinstance(source, str) else list(source)\n"
+    "        for _s in _srcs:\n"
+    "            try:\n"
+    "                _lite_fetch_rel(\n"
+    "                    _rel + '/bem/' + str(subject) + '-' + _s + '.fif'\n"
+    "                )\n"
+    "            except Exception:\n"
+    "                pass\n"
+    "    return _orig_surface_head(\n"
+    "        subject, source, subjects_dir, on_defects,\n"
+    "        raise_error=raise_error\n"
+    "    )\n"
+    "_mne_surface._get_head_surface = _lite_surface_head_surface\n"
+    "# plot_bem globs bem/*.surf and requires the bem directory to exist,\n"
+    "# so pull its three contours (plus the MRI it draws them on) down\n"
+    "# first; fetching creates the directory as a side effect.\n"
+    "_orig_plot_bem = mne.viz.plot_bem\n"
+    "def _lite_plot_bem(subject=None, subjects_dir=None, *_a, **_kw):\n"
+    "    _sd = str(subjects_dir) if subjects_dir is not None else ''\n"
+    "    if subject and _sd.startswith(mne_data_path + '/'):\n"
+    "        _rel = _sd[len(mne_data_path) + 1:] + '/' + str(subject)\n"
+    "        _want = ['bem/inner_skull.surf', 'bem/outer_skull.surf',\n"
+    "                 'bem/outer_skin.surf',\n"
+    "                 'mri/' + str(_kw.get('mri', 'T1.mgz'))]\n"
+    "        _bs = _kw.get('brain_surfaces')\n"
+    "        if _bs is not None:\n"
+    "            _bs = [_bs] if isinstance(_bs, str) else list(_bs)\n"
+    "            for _b in _bs:\n"
+    "                _want += ['surf/lh.' + _b, 'surf/rh.' + _b]\n"
+    "        for _c in _want:\n"
+    "            try:\n"
+    "                _lite_fetch_rel(_rel + '/' + _c)\n"
+    "            except Exception:\n"
+    "                pass\n"
+    "    return _orig_plot_bem(subject, subjects_dir, *_a, **_kw)\n"
+    "mne.viz.plot_bem = _lite_plot_bem\n"
+    "\n"
+    "# EXPERIMENTAL 3D: MNE's normal Brain/VTK stack can't load in WASM, so\n"
+    "# route SourceEstimate.plot() through pyvista-js (vtk.js) instead.\n"
+    "# pyvista-js (0.15) has no scalar colormap in its renderer, so we\n"
+    "# approximate MNE's Brain look with solid-colored meshes: a two-tone\n"
+    "# curvature base (light gyri + dark sulci) plus many thin 'hot' bands\n"
+    "# for the activation, on a black background with even scene lighting.\n"
+    "# Static, one time point, no time slider yet. Fully guarded — any\n"
+    "# failure prints a message so the notebook completes. Returns a stub\n"
+    "# 'brain' whose methods (add_foci/add_text/show_view/...) are safe\n"
+    "# no-ops, so tutorials that call brain.add_foci(...) after plot() work.\n"
+    "class _LiteBrain:\n"
+    "    def screenshot(self, *_a, **_kw):\n"
+    "        import numpy as _np\n"
+    "        return _np.zeros((2, 2, 3), dtype='uint8')\n"
+    "    def __getattr__(self, _name):\n"
+    "        return lambda *_a, **_kw: None\n"
+    "def _lite_stc_plot(self, *_a, **_kw):\n"
+    "    try:\n"
+    "        import numpy as _np\n"
+    "        import nibabel as _nib\n"
+    "        from scipy.spatial import cKDTree as _KDTree\n"
+    "        from matplotlib import colormaps as _cmaps\n"
+    "        import pyvista_js as _pv\n"
+    "        _subj = (_kw.get('subject')\n"
+    "                 or (_a[0] if _a and isinstance(_a[0], str) else None)\n"
+    "                 or 'sample')\n"
+    "        _sdir = _kw.get('subjects_dir')\n"
+    "        _sdir = (str(_sdir) if _sdir is not None else\n"
+    "                 mne_data_path + '/MNE-sample-data/subjects')\n"
+    "        # surfaces are fetched relative to the served mne_data root, so\n"
+    "        # derive that from subjects_dir rather than assuming sample --\n"
+    "        # a dataset may keep its FreeSurfer subjects under its own folder.\n"
+    "        _rel_sdir = (_sdir[len(mne_data_path) + 1:]\n"
+    "                     if _sdir.startswith(mne_data_path + '/')\n"
+    "                     else 'MNE-sample-data/subjects')\n"
+    "        _init = _kw.get('initial_time', None)\n"
+    "        if _init is None:\n"
+    "            _ti = int(_np.argmax(_np.abs(self.data).mean(0)))\n"
+    "        else:\n"
+    "            _ti = int(_np.argmin(_np.abs(self.times - _init)))\n"
+    "        _hot = _cmaps['hot']\n"
+    "        _N = 10\n"
+    "        def _flat(_t):\n"
+    "            return _np.hstack([\n"
+    "                _np.full((len(_t), 1), 3, dtype=_np.int64),\n"
+    "                _t.astype(_np.int64)]).ravel()\n"
+    "        def _sub(_pts, _tris, _mask, _lift=0.0, _cen=None):\n"
+    "            _sel = _tris[_mask]\n"
+    "            if len(_sel) == 0:\n"
+    "                return None\n"
+    "            _u, _iv = _np.unique(_sel, return_inverse=True)\n"
+    "            _p = _pts[_u]\n"
+    "            if _lift and _cen is not None:\n"
+    "                _p = _cen + (_p - _cen) * (1.0 + _lift)\n"
+    "            return _p, _iv.reshape(-1, 3)\n"
+    "        _plotter = _pv.Plotter()\n"
+    "        _plotter.background_color = 'black'\n"
+    "        # even lighting so the surface isn't black when rotated\n"
+    "        for _lp in ((1, 0, 0), (-1, 0, 0), (0, 1, 0),\n"
+    "                    (0, -1, 0), (0, 0, 1), (0, 0, -1)):\n"
+    "            _plotter.add_light(_pv.Light(\n"
+    "                position=(300.0 * _lp[0], 300.0 * _lp[1],\n"
+    "                          300.0 * _lp[2]),\n"
+    "                focal_point=(0.0, 0.0, 0.0), intensity=0.4))\n"
+    "        _nlh = len(self.vertices[0])\n"
+    "        _hemis = (('lh', 0, self.vertices[0]),\n"
+    "                  ('rh', 1, self.vertices[1]))\n"
+    "        for _h, _hi, _vno in _hemis:\n"
+    "            if len(_vno) == 0:\n"
+    "                continue\n"
+    "            _pre = _rel_sdir + '/' + _subj + '/surf/' + _h\n"
+    "            _lite_fetch_rel(_pre + '.inflated')\n"
+    "            _lite_fetch_rel(_pre + '.curv')\n"
+    "            _bpath = _sdir + '/' + _subj + '/surf/' + _h\n"
+    "            _rr, _tris = mne.read_surface(_bpath + '.inflated')\n"
+    "            _cv = _nib.freesurfer.read_morph_data(_bpath + '.curv')\n"
+    "            _hdata = self.data[:_nlh] if _hi == 0 else self.data[_nlh:]\n"
+    "            # color each surface vertex from the nearest ACTIVE source\n"
+    "            # within a small radius, so single-vertex (point) sources\n"
+    "            # show as visible blobs and dense sources fill in as usual\n"
+    "            _sv = _hdata[:, _ti].astype(float)\n"
+    "            _act = _sv != 0\n"
+    "            _scal = _np.zeros(len(_rr))\n"
+    "            if _act.any():\n"
+    "                _atree = _KDTree(_rr[_vno][_act])\n"
+    "                _ad, _ai = _atree.query(_rr)\n"
+    "                _scal = _np.where(_ad <= 12.0, _sv[_act][_ai], 0.0)\n"
+    "            # offset hemispheres along x so they do not overlap\n"
+    "            _off = -60.0 if _h == 'lh' else 60.0\n"
+    "            _pts = _np.round(_rr, 2)\n"
+    "            _pts[:, 0] = _pts[:, 0] + _off\n"
+    "            _cen = _pts.mean(0)\n"
+    "            # curvature base: light gyri (curv<0) + dark sulci (curv>=0)\n"
+    "            _fc = _cv[_tris].mean(1)\n"
+    "            for _cm, _col in (\n"
+    "                    (_fc < 0, (0.68, 0.68, 0.68)),\n"
+    "                    (_fc >= 0, (0.38, 0.38, 0.38))):\n"
+    "                _s = _sub(_pts, _tris, _cm)\n"
+    "                if _s is not None:\n"
+    "                    _plotter.add_mesh(\n"
+    "                        _pv.PolyData(points=_s[0], faces=_flat(_s[1])),\n"
+    "                        color=_col, smooth_shading=True)\n"
+    "            # activation as a smooth hot gradient in N value bands,\n"
+    "            # each lifted 2% off the surface to avoid z-fighting\n"
+    "            _fv = _scal[_tris].mean(1)\n"
+    "            _p90 = _np.percentile(_scal, 90.0)\n"
+    "            _fmax = float(_scal.max())\n"
+    "            # keep the background gray: for sparse point sources the\n"
+    "            # 90th pct is ~0 (most of the brain is zero), which would\n"
+    "            # paint everything, so fall back to a fraction of the max.\n"
+    "            _fmin = _p90 if _p90 > _fmax * 0.05 else _fmax * 0.4\n"
+    "            if _fmax > _fmin:\n"
+    "                _edges = _np.linspace(_fmin, _fmax, _N + 1)\n"
+    "                for _i in range(_N):\n"
+    "                    if _i < _N - 1:\n"
+    "                        _m = (_fv >= _edges[_i]) & (_fv < _edges[_i + 1])\n"
+    "                    else:\n"
+    "                        _m = _fv >= _edges[_i]\n"
+    "                    if int(_m.sum()) == 0:\n"
+    "                        continue\n"
+    "                    _rgb = _hot(0.25 + 0.41 * (_i / (_N - 1)))\n"
+    "                    _col = (float(_rgb[0]), float(_rgb[1]),\n"
+    "                            float(_rgb[2]))\n"
+    "                    _s = _sub(_pts, _tris, _m, 0.02, _cen)\n"
+    "                    if _s is not None:\n"
+    "                        _plotter.add_mesh(\n"
+    "                            _pv.PolyData(points=_s[0],\n"
+    "                                         faces=_flat(_s[1])),\n"
+    "                            color=_col, smooth_shading=True)\n"
+    "        # Open on the lateral profile (camera along the medial-lateral\n"
+    "        # X axis, superior up), like native MNE, instead of vtk.js's\n"
+    "        # default anterior/face-on view. Guarded so a missing\n"
+    "        # view_vector never costs us the render.\n"
+    "        try:\n"
+    "            _plotter.view_vector((-1.0, 0.0, 0.0),\n"
+    "                                 viewup=(0.0, 0.0, 1.0))\n"
+    "        except Exception:\n"
+    "            pass\n"
+    "        _plotter.show()\n"
+    "    except Exception as _e:\n"
+    "        print('[JupyterLite] pyvista-js 3D render unavailable: '\n"
+    "              + repr(_e))\n"
+    "    return _LiteBrain()\n"
+    "mne.SourceEstimate.plot = _lite_stc_plot\n"
+    "\n"
+    "# Pyodide/WASM has no OS threads, so MNE's ProgressBar background\n"
+    "# updater thread (used by the ProgressBar context manager, e.g. in\n"
+    "# permutation cluster tests) crashes with 'can't start new thread'.\n"
+    "# That thread only animates a cosmetic bar — the computation runs on\n"
+    "# the main thread and __exit__ writes the final state — so no-op its\n"
+    "# start/join. Only affects notebooks that use it; results are unchanged.\n"
+    "try:\n"
+    "    from mne.utils import progressbar as _mpb\n"
+    "    _mpb._UpdateThread.start = lambda self: None\n"
+    "    _mpb._UpdateThread.join = lambda self, *_a, **_kw: None\n"
+    "except Exception:\n"
+    "    pass\n"
+    "# tqdm also spawns its own monitor thread, which likewise can't start in\n"
+    "# WASM and emits a TqdmMonitorWarning. Setting monitor_interval=0 before\n"
+    "# any bar is created skips that thread entirely (bars still display).\n"
+    "try:\n"
+    "    import tqdm as _tqdm\n"
+    "    _tqdm.tqdm.monitor_interval = 0\n"
+    "except Exception:\n"
+    "    pass\n"
+    "\n"
+    "# Switch matplotlib to inline so figures render in the notebook.\n"
+    "import IPython\n"
+    "IPython.get_ipython().run_line_magic('matplotlib', 'inline')\n"
+    "import matplotlib.pyplot as plt\n"
+    "# Silence the spurious 'FigureCanvasAgg is non-interactive' warning\n"
+    "# at its source. MNE's plt_show calls fig.show() (the inline backend\n"
+    "# isn't detected as 'agg'), and the inline Agg canvas warns. Patching\n"
+    "# viz.utils.plt_show is not enough: other modules did\n"
+    "# `from .utils import plt_show` and hold their own reference. Every\n"
+    "# path resolves fig.show on the class at call time, so a no-op here\n"
+    "# silences it everywhere. Figures still render via the inline backend.\n"
+    "import matplotlib.figure as _mfig\n"
+    "_mfig.Figure.show = lambda self, *a, **k: None\n"
+    "import importlib\n"
+    "viz_utils = importlib.import_module('mne.viz.utils')\n"
+    "# Also display+close via IPython for paths that call plt_show\n"
+    "# directly, so figures render exactly once.\n"
+    "def pyodide_plt_show(show=True, fig=None, **kwargs):\n"
+    "    if not show:\n"
+    "        return\n"
+    "    import IPython.display\n"
+    "    _f = fig if fig is not None else plt.gcf()\n"
+    "    IPython.display.display(_f)\n"
+    "    plt.close(_f)\n"
+    "viz_utils.plt_show = pyodide_plt_show\n"
+    "\n"
+    "# EXPERIMENTAL 3D: plot_sparse_source_estimates builds its 3D renderer\n"
+    "# BEFORE the time-course figure, so in WASM the whole call dies and the\n"
+    "# notebook loses both halves. Rebuild it here: the same glass brain from\n"
+    "# the source space and a marker per active dipole via pyvista-js, plus\n"
+    "# the matplotlib time courses (which are the quantitative half). Same\n"
+    "# approach as the SourceEstimate.plot shim above.\n"
+    "def _lite_plot_sparse_source_estimates(\n"
+    "        src, stcs, colors=None, linewidth=2, fontsize=18,\n"
+    "        bgcolor=(0.05, 0, 0.1), opacity=0.2, brain_color=(0.7,) * 3,\n"
+    "        show=True, high_resolution=False, fig_name=None,\n"
+    "        fig_number=None, labels=None, modes=('cone', 'sphere'),\n"
+    "        scale_factors=(1, 0.6), **kwargs):\n"
+    "    import numpy as _np\n"
+    "    from itertools import cycle as _cycle\n"
+    "    from matplotlib.colors import to_rgb as _to_rgb\n"
+    "    if not isinstance(stcs, list):\n"
+    "        stcs = [stcs]\n"
+    "    _lhp = src[0]['rr']\n"
+    "    _pts = _np.r_[_lhp, src[1]['rr']] * 170\n"
+    "    _nrm = _np.r_[src[0]['nn'], src[1]['nn']]\n"
+    "    # use_tris is the decimated mesh and can be None on some source\n"
+    "    # spaces; fall back to the full tris in that case.\n"
+    "    _lt = src[0]['tris'] if high_resolution else src[0]['use_tris']\n"
+    "    _rt = src[1]['tris'] if high_resolution else src[1]['use_tris']\n"
+    "    if _lt is None or _rt is None:\n"
+    "        _lt, _rt = src[0]['tris'], src[1]['tris']\n"
+    "    _faces = _np.r_[_lt, len(_lhp) + _rt]\n"
+    "    _vertnos = [_np.r_[_s.lh_vertno, len(_lhp) + _s.rh_vertno]\n"
+    "                for _s in stcs]\n"
+    "    _uniq = _np.unique(_np.concatenate(_vertnos).ravel())\n"
+    "    # --- time courses -------------------------------------------------\n"
+    "    _fig = plt.figure(fig_number, layout='constrained')\n"
+    "    _fig.clf()\n"
+    "    _ax = _fig.add_subplot(111)\n"
+    "    _cyc = _cycle(colors if colors is not None else\n"
+    "                  plt.rcParams['axes.prop_cycle'].by_key()['color'])\n"
+    "    _marks = []\n"
+    "    for _v in _uniq:\n"
+    "        _ind = [_k for _k, _vn in enumerate(_vertnos) if _v in _vn]\n"
+    "        _c = next(_cyc)\n"
+    "        _marks.append((int(_v), _to_rgb(_c), len(_ind) > 1))\n"
+    "        for _k in _ind:\n"
+    "            _m = _vertnos[_k] == _v\n"
+    "            _ax.plot(1e3 * stcs[_k].times,\n"
+    "                     1e9 * stcs[_k].data[_m].ravel(),\n"
+    "                     c=_c, linewidth=linewidth)\n"
+    "    _ax.set_xlabel('Time (ms)', fontsize=fontsize)\n"
+    "    _ax.set_ylabel('Source amplitude (nAm)', fontsize=fontsize)\n"
+    "    if fig_name is not None:\n"
+    "        _ax.set_title(fig_name)\n"
+    "    pyodide_plt_show(show)\n"
+    "    # --- glass brain + dipole markers ---------------------------------\n"
+    "    try:\n"
+    "        import pyvista_js as _pv\n"
+    "        _plotter = _pv.Plotter()\n"
+    "        _plotter.background_color = tuple(\n"
+    "            float(min(max(_x, 0.0), 1.0)) for _x in bgcolor)\n"
+    "        for _lp in ((1, 0, 0), (-1, 0, 0), (0, 1, 0),\n"
+    "                    (0, -1, 0), (0, 0, 1), (0, 0, -1)):\n"
+    "            _plotter.add_light(_pv.Light(\n"
+    "                position=(300.0 * _lp[0], 300.0 * _lp[1],\n"
+    "                          300.0 * _lp[2]),\n"
+    "                focal_point=(0.0, 0.0, 0.0), intensity=0.4))\n"
+    "        _flat_faces = _np.hstack([\n"
+    "            _np.full((len(_faces), 1), 3, dtype=_np.int32),\n"
+    "            _faces.astype(_np.int32)]).ravel()\n"
+    "        _plotter.add_mesh(\n"
+    "            _pv.PolyData(points=_pts.astype(_np.float32),\n"
+    "                         faces=_flat_faces),\n"
+    "            color=tuple(float(_x) for _x in brain_color),\n"
+    "            opacity=float(opacity), smooth_shading=True)\n"
+    "        for _v, _col, _common in _marks:\n"
+    "            _sf = float(scale_factors[1] if _common\n"
+    "                        else scale_factors[0])\n"
+    "            _mode = modes[1] if _common else modes[0]\n"
+    "            _xyz = tuple(float(_q) for _q in _pts[_v])\n"
+    "            if _mode == 'sphere':\n"
+    "                _glyph = _pv.Sphere(radius=_sf, center=_xyz)\n"
+    "            else:\n"
+    "                _glyph = _pv.Cone(\n"
+    "                    center=_xyz,\n"
+    "                    direction=tuple(float(_q) for _q in _nrm[_v]),\n"
+    "                    height=2.0 * _sf, radius=_sf)\n"
+    "            _plotter.add_mesh(_glyph, color=_col, smooth_shading=True)\n"
+    "        try:\n"
+    "            _plotter.view_vector((-1.0, 0.0, 0.0),\n"
+    "                                 viewup=(0.0, 0.0, 1.0))\n"
+    "        except Exception:\n"
+    "            pass\n"
+    "        _plotter.show()\n"
+    "    except Exception as _e:\n"
+    "        print('[JupyterLite] pyvista-js glass brain unavailable: '\n"
+    "              + repr(_e))\n"
+    "mne.viz.plot_sparse_source_estimates = _lite_plot_sparse_source_estimates\n"
+    "\n"
+    "# Each MNE plot is rendered once by pyodide_plt_show above (display()).\n"
+    "# When a plot call is also a cell's last expression, the method returns\n"
+    "# the Figure, which Jupyter echoes a SECOND time as the Out[] result\n"
+    "# (the duplicate seen below inline plots). Drop that redundant echo for\n"
+    "# Figures (and pure lists of Figures, e.g. ica.plot_properties) so each\n"
+    "# plot appears exactly once. Non-figure results (numbers, DataFrames,\n"
+    "# reprs) are untouched, and raw matplotlib figures never shown still\n"
+    "# render via the inline backend's end-of-cell flush, so nothing hides.\n"
+    "# Wrapped in try/except (like the patches below): if anything about\n"
+    "# the displayhook is unexpected, silently keep the current behavior\n"
+    "# (harmless double render) rather than breaking the setup cell.\n"
+    "try:\n"
+    "    _lite_dh = type(IPython.get_ipython().displayhook)\n"
+    "    if not getattr(_lite_dh, '_lite_no_fig_echo', False):\n"
+    "        _lite_dh_call = _lite_dh.__call__\n"
+    "        def _lite_displayhook(self, result=None):\n"
+    "            if isinstance(result, _mfig.Figure):\n"
+    "                result = None\n"
+    "            elif (isinstance(result, (list, tuple)) and result\n"
+    "                  and all(isinstance(_x, _mfig.Figure) for _x in result)):\n"
+    "                result = None\n"
+    "            return _lite_dh_call(self, result)\n"
+    "        _lite_dh.__call__ = _lite_displayhook\n"
+    "        _lite_dh._lite_no_fig_echo = True\n"
+    "except Exception:\n"
+    "    pass\n"
+    "\n"
+    "# Real fix (not a warnings filter) for the threadpoolctl Pyodide\n"
+    "# RuntimeWarning seen via mne.sys_info(): threadpoolctl 3.6.0 (latest\n"
+    "# release) still calls the deprecated Pyodide JsProxy.as_object_map().\n"
+    "# Pyodide's own message says to use as_py_json() instead; both yield the\n"
+    "# same library filepaths, so we swap the call at its source. This removes\n"
+    "# the deprecated API usage entirely, so the warning is never emitted.\n"
+    "# The upstream fix is already merged (joblib/threadpoolctl#201) but\n"
+    "# unreleased; Pyodide bundles the released 3.6.0 wheel. DROP THIS PATCH\n"
+    "# once threadpoolctl 3.7.0 is released and Pyodide bundles it.\n"
+    "try:\n"
+    "    import os as _os\n"
+    "    import threadpoolctl as _tpc\n"
+    "    def _find_libraries_pyodide(self):\n"
+    "        from pyodide_js._module import LDSO\n"
+    "        for _fp in LDSO.loadedLibsByName.as_py_json():\n"
+    "            if _os.path.exists(_fp):\n"
+    "                self._make_controller_from_path(_fp)\n"
+    "    _tpc.ThreadpoolController._find_libraries_pyodide = (\n"
+    "        _find_libraries_pyodide\n"
+    "    )\n"
+    "except Exception:\n"
+    "    pass\n" + LITE_RENDERER_CELL
+    # Draw MNE's 3D figures with pyvista-js. Appended last so MNE is
+    # already imported; see doc/sphinxext/jupyterlite_lite_renderer.py.
+)

From 1e6e216f567d7dcd7ee6073769a87f32203bfa1c Mon Sep 17 00:00:00 2001
From: natinew77-creator <nati.new77@gmail.com>
Date: Tue, 11 Aug 2026 09:27:04 -0400
Subject: [PATCH 2/3] DOC: add the changelog entry for the setup cell

---
 doc/changes/dev/14150.other.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 doc/changes/dev/14150.other.rst

diff --git a/doc/changes/dev/14150.other.rst b/doc/changes/dev/14150.other.rst
new file mode 100644
index 00000000000..948bb812fb1
--- /dev/null
+++ b/doc/changes/dev/14150.other.rst
@@ -0,0 +1 @@
+Add the setup cell that installs MNE into the browser kernel for the JupyterLite documentation, by `Natneal B`_.

From 6e49df16978498bd7128199f6666ceeefeefb120 Mon Sep 17 00:00:00 2001
From: natinew77-creator <nati.new77@gmail.com>
Date: Fri, 14 Aug 2026 09:32:12 -0400
Subject: [PATCH 3/3] DOC: correct what keep_going does in the setup cell

It controls whether a dependency with no pure-Python wheel aborts the
install or is reported at the end. It was never about version bounds, and
since the move to Pyodide 314 there are none left to clear anyway.
---
 doc/sphinxext/jupyterlite_setup_cell.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/sphinxext/jupyterlite_setup_cell.py b/doc/sphinxext/jupyterlite_setup_cell.py
index 10729a27cb8..5204ec7713c 100644
--- a/doc/sphinxext/jupyterlite_setup_cell.py
+++ b/doc/sphinxext/jupyterlite_setup_cell.py
@@ -25,8 +25,8 @@
     "# bundled into the JupyterLite build is preferred over the older PyPI\n"
     "# release;\n"
     "# piplite checks the local index first and falls back to PyPI for deps.\n"
-    "# keep_going=True lets it install even if Pyodide's bundled\n"
-    "# matplotlib/scipy/numpy are older than MNE's declared minimums.\n"
+    "# keep_going=True so a dependency with no pure-Python wheel is reported\n"
+    "# at the end rather than aborting the whole install on the first one.\n"
     "await piplite.install(\n"
     "    ['mne', 'scikit-learn', 'joblib', 'pandas', 'seaborn', "
     "'mne-connectivity', 'nibabel', 'pyvista-js', 'pyxdf', 'mffpy', "