feat: make LSL optional via lazy native load + feature detection

node-labstreaminglayer dlopen's liblsl at require time, so a static
import crashed the whole app on startup when liblsl was missing/
incompatible (e.g. Apple Silicon without the Homebrew build) — even for
Muse-only users who never need LSL.

Load the native bindings lazily and fail soft so LSL becomes a true
advanced, opt-in feature:
- src/main/lsl/native.ts: guarded require() in try/catch (memoized),
  exposing loadLSL() and isLSLAvailable()
- outlets.ts/inlets.ts: type-only imports + loadLSL() at call time;
  all ops no-op gracefully when liblsl is unavailable
- lsl:isAvailable IPC + preload bridge for renderer feature detection
- ConnectModal hides 'External LSL stream' when unavailable
- lslBridge no-ops sendEpoch/sendMarker when unavailable (no IPC spam)

Result: Muse/Neurosity work with zero LSL/LabRecorder dependency; LSL
features appear only where liblsl loads.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jdpigeon

.llms/learnings.md

@@ -89,6 +89,16 @@ Any hook function (e.g. `initResponseHandlers` in `src/renderer/utils/labjs/func
 
 Alternatives evaluated and rejected: `@neurodevs/node-lsl` and `@neurodevs/ndx-native` both require the same Homebrew install (they hard-code `/opt/homebrew/Cellar/lsl/...` paths) and have a much different async/worker-thread API that would force a substantial rewrite.
 
+## LSL is optional — load the native module lazily, never statically
+
+`node-labstreaminglayer` `dlopen`s liblsl via koffi **at require time**. A static `import … from 'node-labstreaminglayer'` in the main process therefore runs that dlopen during module evaluation at startup — so a missing/incompatible liblsl (e.g. Apple Silicon without the Homebrew build) crashes the *entire app* on launch, even for Muse-only users who don't need LSL at all.
+
+LSL is an advanced, opt-in capability: Muse and Neurosity connect via Web Bluetooth and record to CSV without it. So the native module must load lazily and fail soft:
+- `src/main/lsl/native.ts` does a guarded `require('node-labstreaminglayer')` in try/catch (memoized), exposing `loadLSL()` (module | null) and `isLSLAvailable()`. `outlets.ts`/`inlets.ts` use **type-only** imports + `loadLSL()` at call time, no-opping when null.
+- Feature-detect in the renderer via the `lsl:isAvailable` IPC: `ConnectModal` hides the "External LSL stream" option and `lslBridge` no-ops `sendEpoch`/`sendMarker` when unavailable (avoids IPC spam from first-party devices).
+
+Build note: with `module: ESNext` source but CommonJS main output, a guarded `require(...)` of an externalized dep type-checks (global `require` from `@types/node`) and stays a `require` in `out/main/index.js` (electron-vite externalizes it) — confirmed lazy, not bundled. Do **not** revert to a static import.
+
 ## Pre-existing TypeScript errors (do not treat as regressions)
 
 - `src/renderer/epics/experimentEpics.ts` (lines 170, 205) — RxJS operator type mismatch

src/main/index.ts

@@ -19,6 +19,7 @@ import MenuBuilder from './menu';
 import { FILE_TYPES } from '../renderer/constants/constants';
 import { lslOutlets } from './lsl/outlets';
 import { lslInlets } from './lsl/inlets';
+import { isLSLAvailable } from './lsl/native';
 import type {
   LSLEpoch,
   LSLMarker,
@@ -474,6 +475,11 @@ const emitLSLStatus = (status: LSLStatus) => {
   mainWindow?.webContents.send('lsl:status', status);
 };
 
+// Feature-detection probe: the renderer uses this to show/hide LSL UI. When
+// liblsl can't be loaded, LSL is silently unavailable and the app falls back
+// to first-party devices (Muse/Neurosity) only.
+ipcMain.handle('lsl:isAvailable', () => isLSLAvailable());
+
 ipcMain.on('lsl:sendEpoch', (_event, epoch: LSLEpoch) => {
   try {
     lslOutlets.pushEpoch(epoch);

src/main/lsl/inlets.ts

@@ -7,12 +7,9 @@
  * pylsl, etc.).
  */
 import log from 'electron-log';
-import {
-  resolveStreams,
-  StreamInfo,
-  StreamInlet,
-} from 'node-labstreaminglayer';
+import type { StreamInfo, StreamInlet } from 'node-labstreaminglayer';
 import type { DiscoveredStream, LSLInletEpoch } from '../../shared/lslTypes';
+import { loadLSL } from './native';
 
 const POLL_INTERVAL_MS = 16; // ~60Hz poll
 
@@ -38,14 +35,17 @@ class LSLInletManager {
   private discoveredInfos = new Map<string, StreamInfo>();
 
   discoverStreams(waitTime: number = 1.0): DiscoveredStream[] {
+    const lsl = loadLSL();
+    if (!lsl) return [];
+
     // Free any StreamInfos we cached but never subscribed to on the previous
     // scan so we don't leak their C handles.
     for (const [uid, info] of this.discoveredInfos) {
       if (!this.inlets.has(uid)) info.destroy();
     }
     this.discoveredInfos.clear();
 
-    const streams = resolveStreams(waitTime);
+    const streams = lsl.resolveStreams(waitTime);
     const results: DiscoveredStream[] = [];
     for (const info of streams) {
       const uid = info.uid();
@@ -68,13 +68,15 @@ class LSLInletManager {
     onDisconnected?: () => void
   ): boolean {
     if (this.inlets.has(uid)) return true;
+    const lsl = loadLSL();
+    if (!lsl) return false;
     const info = this.discoveredInfos.get(uid);
     if (!info) {
       log.warn(`[lsl] subscribeStream: unknown uid ${uid} — discover first`);
       return false;
     }
 
-    const inlet = new StreamInlet(info);
+    const inlet = new lsl.StreamInlet(info);
     try {
       inlet.openStream(5);
     } catch (err) {

src/main/lsl/native.ts

@@ -0,0 +1,45 @@
+/**
+ * Lazy, fail-safe loader for the native LSL bindings.
+ *
+ * `node-labstreaminglayer` loads liblsl via koffi (FFI) at require time. On a
+ * machine where liblsl is missing (e.g. Apple Silicon without the Homebrew
+ * build) that require throws. LSL is an advanced, opt-in capability — Muse and
+ * Neurosity work entirely without it — so a failed load must never crash app
+ * startup. We attempt the require once, swallow any failure, and report
+ * availability so callers (outlets, inlets, the renderer feature-gate) can
+ * degrade gracefully.
+ */
+import log from 'electron-log';
+
+type LSLModule = typeof import('node-labstreaminglayer');
+
+let cached: LSLModule | null = null;
+let attempted = false;
+
+/**
+ * Returns the loaded LSL module, or null if liblsl could not be loaded.
+ * The load is attempted lazily on first call and the result is memoized.
+ */
+export function loadLSL(): LSLModule | null {
+  if (attempted) return cached;
+  attempted = true;
+  try {
+    // require (not a static import) so a missing liblsl degrades to a disabled
+    // feature instead of throwing during module evaluation at startup.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    cached = require('node-labstreaminglayer') as LSLModule;
+    log.info('[lsl] native module loaded — LSL features enabled');
+  } catch (err) {
+    cached = null;
+    log.warn(
+      '[lsl] node-labstreaminglayer unavailable — LSL features disabled ' +
+        '(expected if liblsl is not installed):',
+      err instanceof Error ? err.message : err
+    );
+  }
+  return cached;
+}
+
+export function isLSLAvailable(): boolean {
+  return loadLSL() !== null;
+}

src/main/lsl/outlets.ts

@@ -6,12 +6,9 @@
  * LSL network where they can be recorded by LabRecorder or any LSL inlet.
  */
 import log from 'electron-log';
-import {
-  StreamInfo,
-  StreamOutlet,
-  IRREGULAR_RATE,
-} from 'node-labstreaminglayer';
+import type { StreamOutlet } from 'node-labstreaminglayer';
 import type { LSLEpoch } from '../../shared/lslTypes';
+import { loadLSL } from './native';
 
 const MARKER_STREAM_NAME = 'BrainWavesMarkers';
 
@@ -29,10 +26,13 @@ class LSLOutletManager {
     channelNames: string[],
     sampleRate: number
   ): void {
+    const lsl = loadLSL();
+    if (!lsl) return;
+
     this.destroyDeviceOutlet(deviceId);
 
     const streamName = `BrainWaves-${deviceType}-${deviceId}`;
-    const info = new StreamInfo(
+    const info = new lsl.StreamInfo(
       streamName,
       'EEG',
       channelNames.length,
@@ -44,7 +44,7 @@ class LSLOutletManager {
     info.setChannelTypes('EEG');
     info.setChannelUnits('microvolts');
 
-    const outlet = new StreamOutlet(info);
+    const outlet = new lsl.StreamOutlet(info);
     this.outlets.set(deviceId, outlet);
     log.info(
       `[lsl] created EEG outlet ${streamName} (${channelNames.length}ch @ ${sampleRate}Hz)`
@@ -88,15 +88,17 @@ class LSLOutletManager {
    */
   createMarkerOutlet(): void {
     if (this.markerOutlet) return;
-    const info = new StreamInfo(
+    const lsl = loadLSL();
+    if (!lsl) return;
+    const info = new lsl.StreamInfo(
       MARKER_STREAM_NAME,
       'Markers',
       1,
-      IRREGULAR_RATE,
+      lsl.IRREGULAR_RATE,
       'string',
       'brainwaves-markers'
     );
-    this.markerOutlet = new StreamOutlet(info);
+    this.markerOutlet = new lsl.StreamOutlet(info);
     log.info(`[lsl] created marker outlet ${MARKER_STREAM_NAME}`);
   }
 

src/preload/index.ts

@@ -183,6 +183,10 @@ contextBridge.exposeInMainWorld('electronAPI', {
   // ------------------------------------------------------------------
   // LSL — main-process outlets push to the LSL network, inlets pull from it
   // ------------------------------------------------------------------
+  // True only when the native liblsl bindings loaded. Renderer feature-gates
+  // all LSL UI/forwarding on this so the app works without liblsl installed.
+  isLSLAvailable: (): Promise<boolean> => ipcRenderer.invoke('lsl:isAvailable'),
+
   sendLSLEpoch: (epoch: LSLEpoch): void =>
     ipcRenderer.send('lsl:sendEpoch', epoch),
 

src/renderer/components/CollectComponent/ConnectModal.tsx

@@ -29,6 +29,9 @@ interface Props {
 interface State {
   selectedDevice: Device | null;
   instructionProgress: INSTRUCTION_PROGRESS;
+  // True only when native liblsl loaded in the main process. The "External LSL
+  // stream" device option is hidden otherwise so the app works without liblsl.
+  lslAvailable: boolean;
 }
 
 enum INSTRUCTION_PROGRESS {
@@ -50,6 +53,7 @@ export default class ConnectModal extends Component<Props, State> {
     this.state = {
       selectedDevice: null,
       instructionProgress: INSTRUCTION_PROGRESS.SEARCHING,
+      lslAvailable: false,
     };
     this.handleSearch = debounce(this.handleSearch.bind(this), 300, {
       leading: true,
@@ -62,6 +66,13 @@ export default class ConnectModal extends Component<Props, State> {
     this.handleinstructionProgress = this.handleinstructionProgress.bind(this);
   }
 
+  componentDidMount() {
+    window.electronAPI
+      ?.isLSLAvailable?.()
+      .then((ok) => this.setState({ lslAvailable: ok }))
+      .catch(() => this.setState({ lslAvailable: false }));
+  }
+
   UNSAFE_componentWillUpdate(nextProps: Props) {
     if (
       nextProps.deviceAvailability === DEVICE_AVAILABILITY.NONE &&
@@ -196,7 +207,9 @@ export default class ConnectModal extends Component<Props, State> {
             >
               <option value={DEVICES.MUSE}>Muse</option>
               <option value={DEVICES.NEUROSITY}>Neurosity Crown</option>
-              <option value={DEVICES.LSL}>External LSL stream</option>
+              {this.state.lslAvailable && (
+                <option value={DEVICES.LSL}>External LSL stream</option>
+              )}
             </select>
           </div>
           {this.props.deviceType === DEVICES.LSL && this.renderLSLDiscovery()}

src/renderer/types/electron.d.ts

@@ -99,6 +99,7 @@ declare global {
     cancelBluetoothSearch: () => Promise<void>;
 
     // LSL
+    isLSLAvailable: () => Promise<boolean>;
     sendLSLEpoch: (epoch: LSLEpoch) => void;
     sendLSLMarker: (marker: LSLMarker) => void;
     discoverLSLStreams: () => Promise<DiscoveredStream[]>;

src/renderer/utils/eeg/lslBridge.ts

@@ -11,6 +11,15 @@ import { EEGData } from '../../constants/interfaces';
 
 const DEFAULT_BATCH_SIZE = 32;
 
+// Cache the main-process LSL availability so the hot epoch/marker paths don't
+// flood IPC when liblsl isn't loaded. Probed once; defaults to false until the
+// async check resolves (a few early samples may be dropped — harmless, and the
+// main process no-ops them anyway).
+let lslAvailable = false;
+void window.electronAPI?.isLSLAvailable?.().then((ok) => {
+  lslAvailable = ok;
+});
+
 /**
  * Transforms a raw EEG observable (per-sample EEGData) into an observable of
  * batched LSLEpoch objects ready to be forwarded over IPC.
@@ -37,9 +46,11 @@ export const batchSamplesToEpoch = (
   );
 
 export const sendEpoch = (epoch: LSLEpoch): void => {
+  if (!lslAvailable) return;
   window.electronAPI?.sendLSLEpoch?.(epoch);
 };
 
 export const sendMarker = (marker: LSLMarker): void => {
+  if (!lslAvailable) return;
   window.electronAPI?.sendLSLMarker?.(marker);
 };