Headband Transport

interface HeadbandFrameV1 {
  schemaVersion: "v1";
  source: string;                        // e.g., "muse-ble"
  sequenceId: number;
  emittedAtMs: number;
  eeg: HeadbandSignalBlock;              // always present
  ppgRaw?: HeadbandSignalBlock;          // PPG (if available)
  optics?: HeadbandSignalBlock;          // Athena optics
  accgyro?: HeadbandSignalBlock;         // Athena accelerometer/gyroscope
  battery?: HeadbandBatteryBlock;        // battery level
}

interface HeadbandSignalBlock {
  sampleRateHz: number;
  channelNames: string[];                // e.g., ["TP9", "AF7", "AF8", "TP10"]
  channelCount: number;
  samples: number[][];                   // rows of [ch0, ch1, ch2, ch3]
  timestampsMs?: number[];
  clockSource?: "device" | "local";
}

interface HeadbandTransport {
  onFrame?: (frame: HeadbandFrameV1) => void;
  onStatus?: (status: HeadbandTransportStatus) => void;
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  start(): Promise<void>;
  stop(): Promise<void>;
}

interface HeadbandTransportStatus {
  state: HeadbandTransportState;
  atMs: number;
  reason?: string;
  errorCode?: string;
  recoverable?: boolean;
  details?: Record<string, unknown>;
}

const transport: HeadbandTransport = /* BleTransport or other */;

transport.onFrame = (frame) => {
  const eegSamples = frame.eeg.samples;
  // samples[sampleIdx][channelIdx]: each row is one time step [tp9, af7, af8, tp10]
};

transport.onStatus = (status) => {
  console.log(`State: ${status.state}`, status.reason);
};

await transport.connect();
await transport.start();

// ... later
await transport.stop();
await transport.disconnect();