> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API versions & changelog

> Track the API versions for LynxHub modules and extensions at version 3.5.0.

LynxHub uses API versioning to ensure compatibility between the host application and installed plugins (modules and extensions).

***

## Current API versions

For the LynxHub client version `3.5.0`, the active API versions are:

| Plugin type    | Current API version | Target config field   |
| :------------- | :------------------ | :-------------------- |
| **Modules**    | `2.1.0`             | `moduleApiVersion`    |
| **Extensions** | `2.0.0`             | `extensionApiVersion` |

***

## Compatibility model

Every plugin must specify its required API version inside its `metadata.json` configuration file:

```json theme={null}
{
  "name": "my-plugin",
  "id": "my-plugin-id",
  "version": "1.0.0",
  "moduleApiVersion": "2.1.0"
}
```

When loading plugins at startup, LynxHub performs the following compatibility checks:

1. **Exact match or minor version updates**: The host loads the plugin if its requested API version is equal to or lower than the host's supported version (within the same major version).
2. **Major version mismatch**: If the plugin requires a higher major API version than the host supports, the host disables the plugin and notifies the user with a compatibility warning.
3. **Missing version fields**: If the plugin configuration does not specify an API version, it defaults to legacy compatibility mode and may run with limited API features.

***

## Configuring semver ranges

When publishing a plugin, you must declare compatible API ranges in your plugin's `versioning.json` registry file under the `engines` field. The host application checks this range to ensure compatibility.

### Easy semver guide

Use these simple formats to control which host versions can run your plugin:

* **Caret `^` (Recommended)**: Matches the major version. Allows safe updates.
  * *Example*: `"^2.0.0"` works with `2.0.0`, `2.1.0`, and all `2.x.x` versions. It will **not** work with `3.0.0`.
* **Tilde `~` (Strict)**: Matches the major and minor version. Only allows patch fixes.
  * *Example*: `"~2.1.0"` works with `2.1.0` and `2.1.1`. It will **not** work with `2.2.0`.
* **Exact version (Strict)**: Requires the exact version number.
  * *Example*: `"2.1.0"` only works with `2.1.0`.

### Example configuration

Here is an example `versioning.json` snippet showcasing how to specify compatibility for a module and an extension:

#### For a module:

```json theme={null}
{
  "versions": [
    {
      "version": "1.2.0",
      "commit": "abcdef1234567890abcdef1234567890abcdef12",
      "engines": {
        "moduleApi": "^2.1.0"
      },
      "stage": "public",
      "platforms": ["win32", "linux", "darwin"]
    }
  ]
}
```

#### For an extension:

```json theme={null}
{
  "versions": [
    {
      "version": "1.0.0",
      "commit": "1234567890abcdef1234567890abcdef12345678",
      "engines": {
        "extensionApi": "^2.0.0"
      },
      "stage": "public",
      "platforms": ["win32"]
    }
  ]
}
```

***

## API changelogs

The following changelogs detail API additions, modifications, and deprecations for the 3.5.0 release.

### Version 3.5.0

This major release introduced the V3 UI redesign, a unified IPC system, and major API version bumps.

#### Modules (API 2.1.0)

* Bumped `moduleApiVersion` to `2.1.0`.
* Added the `supportCustomArguments` configuration flag to let modules explicitly enable or disable custom argument UI rendering.
* Integrated **Alert** UI feedback support across most module execution steps.

#### Extensions (API 2.0.0)

* Bumped `extensionApiVersion` to `2.0.0`.
* Enabled extensions to dynamically inject positional cards directly into the **Tools** and **Games** pages.
* Enabled extensions to dynamically intercept and listen to any IPC event (running callbacks before and after calls) across both main and renderer processes.
* Replaced the legacy IPC implementation with a unified IPC handler system, passed to both main and renderer entrypoints.
* Added API support to trigger modals directly from card dropdown menus.