Plugin Development

Overview

Signal capture in Psynaptix is built on a common provider interface. Built-in providers (for example, scalp-level electrical activity from a consumer headband, and pointing-device interaction) implement this interface. The same interface is the intended extension point for third-party providers.

The provider model

• Provider - a module that emits a declared family of signals and participates in the session lifecycle (session start, trial start, events, trial end, session end).
• Lifecycle - providers are initialized at startup and receive the session and trial lifecycle events needed to capture and store their signals.
• Calibration - providers can participate in the pre-session calibration routine, reporting readiness through the standard contract.

Becoming a provider

Building a new provider is an engineering effort against the provider interface, and it is currently done in coordination with the platform team:

• Design - the provider declares what signal family it emits and how it participates in calibration.
• Review - the platform team reviews the integration for safety and data-handling.
• Ship - once approved, the provider is integrated into the platform and becomes available in lesson configuration.

Safety & data handling

Any provider added to the platform must meet the same safety and privacy bar as the built-ins:

• Least privilege - a provider only touches the session data it is configured for.
• No cross-session access - providers cannot read other sessions' data or the platform's internal state.
• Fail-closed - if a provider misbehaves, it is stopped and the lesson continues without it.

Hotloading (implemented)

Independent developers can now ship signal-provider plugins that load at runtime without a platform redeploy:

• Packaged - a provider is delivered as a self-contained bundle plus a manifest declaring its identity, version, entry module, and capabilities.
• Validated - the client fetches the manifest, validates the id/version/capability set, and checks the entry origin before loading.
• Approved - only allowlisted plugins are served by the registry; unregistered plugins are not available to lessons.
• Constrained - the plugin receives only a narrow context (ingest endpoint, an opaque token, and a log helper); it has no access to internal state or other sessions' data.

Try the example: a small demo provider (demo-heartbeat) is bundled and served through the plugin registry, demonstrating the full manifest-to-runtime path. It is intended as a template for your own provider.

Desktop runtime (collector)

Some signal sources cannot run inside a browser: hardware the browser sandbox cannot reach (a BLE device beyond the Web Bluetooth surface, an infrared camera stream, native sensors). For these, the platform provides a desktop collector. A small local application that owns the hardware and serves derived metrics to the lesson over a local connection. The plugin contract is the same as the web runtime; the difference is where the plugin executes.

• One contract, two runtimes - a provider is authored once against the same provider interface; it runs in the browser (web runtime) or in the collector (desktop runtime), chosen by the plugin's declared runtime requirement.
• Runtime declaration - a manifest may declare whether it needs the desktop. A plugin that does not declare a runtime is available everywhere; one that declares a desktop requirement is refused in the browser and loaded by the collector instead.
• Derived data only - the collector processes signals locally and exposes derived metrics; raw signal frames do not leave the machine.
• Persistent hardware ownership - the collector keeps its device connection across the whole lesson, so the lesson does not need to re-establish hardware access between phases.

Authoring: build the same provider interface as a web plugin, declare the desktop runtime requirement in your manifest, and test against the collector's local harness (the same test tooling, pointed at the collector transport). Approved desktop plugins are distributed through the same registry and approval path as web plugins.

Getting started

1. Contact the team - provider development is by agreement; reach out with your provider idea.
2. Receive the reference - approved developers get the detailed provider reference and a starter example.
3. Develop - build your provider against the interface and test it with the provided tooling.
4. Submit - send your integration; the team reviews and, once approved, ships it.

Contact

To discuss a provider, contact the platform team with a short description of the signals you want to capture and the device or source involved. We will respond with next steps.