Plugins

The plugin system allows you to extend IsoFind's functionality without modifying the software itself. Each plugin is an independent module that integrates directly into the interface and can interact with your isotopic data via the internal API.

Accessing the Plugin Manager

Main menu › Plugins › Plugin manager

Figure 1: "Plugin manager" menu under the "Plugins" menu.

The manager centralises all plugins installed on your instance. It presents a dashboard with the total number of plugins, the number of active plugins and available updates.

When offline mode is enabled, an orange badge appears in the manager title. This mode blocks all network connections initiated by plugins.

Installing a Plugin

Plugin manager › Install a plugin

Figure 2: Plugin installation menu.

IsoFind offers two installation methods depending on your network configuration.

From a file

Drag an .isplugin or .zip file directly into the drop zone, or click Select a file to open the file browser. IsoFind reads the plugin manifest, verifies the required fields and installs the code automatically.

The installation proceeds through seven steps visible in the progress bar:

Step	Operation
1	Environment preparation
2	File reading
3	Archive decompression
4	Manifest reading and validation
5	Main code extraction
6	Conflict detection
7	Finalisation and registration

From a URL

Enter the direct URL of an .isplugin file in the provided field and click Download. IsoFind downloads and installs the plugin in a single operation. This method is not available when offline mode is active.

If JSZip is not loaded in your instance, installation from a .zip file will fail with an explicit message. Verify that the library is included in your configuration.

Plugin Structure

Each plugin is an archive containing at minimum two files: a manifest and a main code file. The manifest describes the plugin and its requirements; the code file contains the logic executed by IsoFind.

The manifest file

The manifest is a manifest.json file placed at the root of the archive, in the v2 format (schema plugin-manifest-v2). Five fields are required. Unknown fields are rejected: the manifest accepts only the keys below.

Field	Type	Required	Description
id	string	Required	Unique lowercase identifier (3 to 64 characters, pattern a-z 0-9 . _ -). Used as the install key.
name	string	Required	Name displayed in the manager.
version	string	Required	Semantic version X.Y.Z. Used for sorting and update detection.
sdk	object	Required	SDK compatibility, in the form { "min": "2.0.0" }. The host refuses a plugin whose min exceeds its own SDK version.
entry	string	Required	Main code file inside the archive. Defaults to plugin.js. Replaces the former main field.
description	string		Short description (600 characters maximum).
category	string		analysis, visualization, data or tools.
icon	string		URL of an icon, optional.
author	object		Object { name, email, url }. Note: this is no longer a plain string.
license	string		Plugin licence.
repository	string		Source repository URL, shown as a "Source code" link.
homepage	string		Plugin presentation page.
keywords	array		Keywords (16 maximum).
compatibility	object		Target editions: { "scope": "core" } (compatible with all editions) or { "scope": "editions", "editions": [...] } (limited to the listed editions).
dependencies	array		Identifiers of other required plugins (see Dependencies Between Plugins).
capabilities	array		Requested capabilities (see Capabilities). Without any capability, a plugin can only compute.
contributes	object		Declared extension points: formulas, menus, panels (see Extension Points).
signature	object		Detached signature, verified before execution (see Signature and Certificate).

The move from the permissions field to capabilities, and from main to entry, reflects the v2 model running in a sandbox. The historical language field no longer exists in the v2 manifest.

Extension Points (contributes)

The contributes field declares in advance what the plugin adds. The host therefore knows its extension points without executing the code, which also feeds the no-code creation wizard.

Extension point	Shape	Effect
formulas	list of { name, group, label, syntax, example }	Adds spreadsheet functions. The name is uppercase, as invoked in a cell; the formulas appear in the spreadsheet function selector.
menus	list of { id, label }	Adds menu entries. Requires the ui:menu capability.
panels	list of { id, label }	Declares panels that can be opened in the interface. Requires the ui:panel capability.

Capabilities

A plugin declares the capabilities it needs in its manifest. Each call to the host is refused if the corresponding capability was not granted at installation. A manifest without any capability can do nothing but compute. Nine capabilities exist. There is no file-system capability: the sandbox does not expose the disk to plugins.

Capability	Access granted
samples:read	Read the samples of the active database.
samples:write	Write samples.
analysis:run	Run internal analysis pipelines.
config:read	Read the plugin's own persistent configuration.
config:write	Write that configuration.
ui:notify	Display a notification in the interface.
ui:menu	Add a menu entry.
ui:panel	Open a panel in the interface.
network	Network requests. Blocked in offline mode, even when declared.

IsoFind API for Plugins

Each plugin has access to a global API object that exposes IsoFind interaction functions. This object is injected automatically at plugin execution.

Available functions

Function	Description
API.getSamples()	Returns the list of samples from the active database
API.getSelectedSamples()	Returns only the samples selected by the user
API.showNotification(message, type)	Displays a notification in the interface. Types: success, error, info, warning
API.registerMenuItem(label, callback)	Adds an entry to IsoFind's main menu
API.createPanel(html)	Creates a floating panel in the interface with the provided HTML content
API.getConfig(key)	Reads a persistent configuration value specific to the plugin
API.setConfig(key, value)	Writes a persistent configuration value specific to the plugin

Sandbox and SDK

Each plugin runs inside an isolated iframe. It never touches the application directly: it talks to a host bridge through messages. The capabilities granted at installation are passed to that iframe, and each host function is gated by the corresponding capability. For example, reading samples requires samples:read, displaying a notification requires ui:notify, and opening a panel requires ui:panel.

The host SDK version is 2.0.0. The manifest's sdk.min field sets the minimum required version; the host refuses a plugin that requires a version newer than its own.

The functions listed above are reached through this bridge and remain subject to capabilities: a call not covered by a granted capability is simply ignored. Menu entries, panels and formulas are not created through free calls but declared in contributes.

Signature and Certificate

A plugin can be signed to prove its origin. The signature is detached and verified by the host before any execution. It reuses the IsoFind PKI, with the same conventions as ISOF file signing.

signature field	Description
algorithm	ECDSA-P256 (P-256 curve, SHA-256 digest).
certificate_chain	Chain from author to Issuing CA, each certificate as base64 of PEM (at least two). The Root is pinned on the verifier side.
signature_b64	ECDSA signature in base64.
code_sha256	Informative. The verifier always recomputes this digest from the actual code.

What is signed is the canonical JSON of the pair "manifest without the signature field" and "digest of the entry-point code". Manifest and code are thus bound by a single signature: changing one invalidates the other. The chain goes up from the author to the Issuing CA and then the IsoFind Root, the latter being pinned by the verifier.

An unsigned plugin remains installable, but the host flags it as unverified. The Verify signatures setting (global settings) enforces verification before installation. The author's certificate is the one issued at enrolment (CSR generation, then signing in the IsoFind manager).

Dependencies Between Plugins

A plugin can declare in dependencies the identifiers of other plugins it needs. At installation, missing dependencies are offered for download and installed in chain, in the correct order. The system detects dependency cycles to avoid looping installations.

Python Plugins

Manifest › language: "python"

IsoFind supports plugins written in Python via Pyodide, a full Python environment running in the browser. The numpy and pandas packages are loaded automatically. The scipy and matplotlib packages can be requested on demand.

Python code accesses IsoFind data via the isofind module injected automatically into the Pyodide environment:

Python method	JavaScript equivalent
IsoFindAPI.get_samples()	API.getSamples()
IsoFindAPI.get_samples_df()	Returns a directly usable pandas DataFrame
IsoFindAPI.notify(message, type)	API.showNotification()

Loading Pyodide from the CDN is blocked in offline mode. To use Python plugins without an internet connection, configure a local path to Pyodide in the plugin settings.

Conflict Detection

Before any installation, IsoFind automatically analyses the plugin code to detect potential conflicts with already-installed plugins and dangerous code patterns.

Checked conflicts

Conflict type	Risk level	Description
Global variables	High	The plugin declares a variable already used by an installed plugin
Menu names	Medium	A menu entry shares the same name as an existing menu
Shared permissions	Low	Two plugins may modify the same data simultaneously
Similar category	Low	One or more plugins of the same category are already installed
localStorage.clear()	Critical	Deletion of all session data
document.write()	High	Can entirely erase the page content
eval()	High	Dynamic code evaluation, security risk
innerHTML injection	Medium	Injection of script tags into the DOM

If a conflict is detected, a summary window lists the issues before presenting two options: cancel the installation or install anyway. Critical-level conflicts cannot be bypassed.

Enabling and Disabling a Plugin

Each plugin card in the manager has an activation toggle. Disabling a plugin unloads its code from memory without uninstalling it. The plugin retains its settings and can be re-enabled at any time.

Figure 3: Enabling or disabling a plugin.

An enabled plugin is loaded automatically each time IsoFind starts. Its code runs in the global application context and can interact with the interface from launch.

Plugin Settings

Manager › Plugin card › Settings

The plugin settings window displays its complete information: version, author, description, identifier, category, installation date and contact address. If the plugin declares a repository in its manifest, a direct link is displayed.

Figure 4: Accessing plugin settings.

A Check for update button compares the installed version against the version available in the online library. If an update is detected, confirmation is requested before installation. This check is disabled in offline mode.

Uninstalling a Plugin

Uninstalling permanently removes the plugin and its configuration data. The operation is irreversible. IsoFind requests confirmation before proceeding.

If the plugin was active at the time of uninstallation, its code is unloaded from memory before deletion. Menu entries registered by the plugin are removed immediately.

Global Plugin Settings

Plugins › Plugin settings

Figure 5: Global plugin settings.

Security

Setting	Description	Default value
Verify signatures	Validates plugin authenticity before installation	Enabled
Sandbox mode	Runs plugins in an isolated environment	Enabled
Automatic updates	Installs updates without requesting confirmation	Disabled

Default capabilities

These settings define the capabilities granted by default to newly installed plugins. They do not modify the capabilities of plugins already in place.

Capability	Default value
Network access (network)	Disabled

Offline Mode (Air-Gap)

Plugin settings › Offline mode

Figure 6: Air-gap mode settings.

Offline mode is designed for environments without internet access, particularly sensitive infrastructures or isolated network workstations. When active, all network connections initiated by plugins are blocked at the system level.

The following features are disabled in offline mode:

Feature	Behaviour in offline mode
Installation from a URL	Tab hidden in the installer
Online library	Access blocked with notification
Update checks	Blocked with notification
Pyodide loading (CDN)	Blocked unless a local path is configured
Plugin network capability	Blocked even if declared in the manifest

Local path for Pyodide

To use Python plugins in offline mode, you must download Pyodide and serve it locally. Enter the path to pyodide.js in the Local Pyodide path field. Example: /static/pyodide/.

Pyodide can be downloaded at github.com/pyodide/pyodide/releases. Place all files in a directory served by your IsoFind instance and enter the full path in the settings.

Exporting and Importing Plugins

The Export plugins section in settings allows you to save all installed plugins to an .isoplugins file. This file contains the metadata of all plugins and can be imported on another IsoFind instance.

To import a bundle, click Import an archive and select an .isoplugins file. IsoFind adds plugins absent from the instance without overwriting those already present.

The .isoplugins format contains only plugin metadata, not their source code. For a complete installation in an offline environment, also provide the corresponding .isplugin files.

Creating a Plugin

Plugins › Create a plugin

The creation wizard guides you through building a plugin in four steps. No prior knowledge of archive structure is required: IsoFind generates the manifest and prepares the exportable file.

Figure 7: Plugin creation wizard.

Step	Content
1. Information	Name, version, description, author, email
2. Configuration	Language (JavaScript or Python), required capabilities
3. Code	Code editor with starter templates
4. Finalisation	Summary, export options (README, icon), file generation

Available templates

Four starter templates are offered at the Code step. Each contains a functional structure ready to modify.

Template	Typical use
Empty	Start from scratch, minimal structure only
Basic	Simple plugin with notification and menu entry
Analyser	Isotopic data processing and result display
Visualiser	Creating a graphical panel in the interface

Connecting to the Site: Registry and Relay

The online library and the website both rely on the same catalogue, the registry.json registry (schema isofind-plugin-registry/v1) published on the site. Each entry describes a plugin and points to its signed .isplugin archive, without embedding the code.

Entry field	Required	Description
id, name, version, category	Required	Plugin identity and category.
download_url	Required	URL of the signed .isplugin archive.
author, author_cn		Declared author and signing certificate subject, shown as-is when the plugin is signed.
capabilities, sdk, compatibility		Requested capabilities (shown before download), minimum SDK version, compatible editions.
dependencies, repository		Required dependencies and source repository.
downloads, size, updated, icon		Display and sorting metadata.
signed		Declarative indication from the registry. It does not replace the signature verification performed at installation.

The application does not contact the site directly. It reads the registry through a local relay served by its own backend, at /plugins/registry.json, which fetches the catalogue server-side from the site. The frontend thus stays same-origin: no CORS issue, and no application token leaves toward a third party. The relay also rewrites the download_url values to /plugins/files/, so that archive downloads also stay same-origin.

In offline mode, this relay and the library are unreachable, like other network access. Distribution then happens through .isoplugins bundles and .isplugin archives provided manually.

Reference Plugins Provided

Several reference plugins are provided, signed, ready to install and to serve as a template. They use only the interface capabilities, with no access to data or to the network.

Plugin	Identifier	Category	Role
Extensions Hub	plugin-hub	tools	Entry point for extensions, loaded automatically.
14C Dating	c14-dating	analysis	Radiocarbon dating panel.
U-Th Dating	uth-dating	analysis	Uranium-thorium dating, closed-system age equation from activity ratios.
Advanced Spreadsheet Formulas	tableur-advanced-formulas	tools	Statistics, isotopy, mixing and Rayleigh, error propagation, York regression, rare-earth anomalies.

Plugin Library

Plugins › Browse the library

The library lists published plugins compatible with your version of IsoFind. It allows filtering by category and sorting by popularity, publication date or rating. Installation is one click from each plugin's details page.

The library is not accessible in offline mode. To distribute plugins in this context, use the .isoplugins bundle export and import.

To submit a plugin to the official library, see the Contribute page on the IsoFind website. Third-party plugins are subject to a code review before publication.