Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Manifest Specification (plugin.json)

Every Dioxamine plugin must include a valid plugin.json file at the root of its archive. The manifest declares metadata, required permissions, versioning, and display preferences.

Example Manifest

{
  "schemaVersion": 1,
  "id": "com.rhythmcache.dioxamine.terminal",
  "name": "Terminal",
  "description": "Interactive PTY terminal using xterm.js",
  "version": "1.0.1",
  "versionCode": 2,
  "author": "RhythmCache",
  "entry": "index.html",
  "icon": "icon.png",
  "minAppVersionCode": 1,
  "permissions": [
    "shell"
  ],
  "fullscreen": true,
  "homepage": "https://github.com/rhythmcache/dioxamine"
}

Field Reference

FieldTypeRequiredDescription
schemaVersionIntegerYesManifest format version. Must currently be 1.
idStringYesUnique reverse-DNS identifier (lowercase letters, numbers, dots, and underscores). Must contain at least one dot (for example, com.example.myplugin).
nameStringYesHuman-readable title displayed in the plugin directory and header. Maximum 50 characters.
descriptionStringNoShort summary of plugin functionality. Maximum 200 characters. Default: "".
versionStringYesHuman-readable version string (for example, "1.0.0" or "2.1.0-beta").
versionCodeIntegerYesIncremental integer version used for upgrade detection. Must be greater than or equal to 1.
authorStringNoAuthor or organization name.
entryStringYesRelative path to the HTML entrypoint file (for example, "index.html" or "ui/main.html"). Path traversal (..) is forbidden.
iconStringNoRelative path to the plugin icon image (PNG, WebP, JPG, or SVG). Default: null.
minAppVersionCodeIntegerNoMinimum Dioxamine app versionCode required to execute this plugin. Default: 1.
permissionsArray<String>NoList of required permission identifiers. Only valid permission names are permitted. Default: [].
fullscreenBooleanNoIf true, hides the Dioxamine top bar on launch to provide an edge-to-edge full-screen display. Default: false.
homepageStringNoWeb URL pointing to the plugin repository, source code, or documentation.

Validation Rules

When installing or loading a plugin, Dioxamine strictly enforces the following validation checks:

  1. ID Format:
    • Must match the regular expression ^[a-z0-9]+(\.[a-z0-9_]+)+$.
    • Uppercase characters, spaces, and leading/trailing dots will cause installation to fail.
  2. Path Sanitization:
    • entry and icon paths must point inside the plugin directory.
    • Any path containing .. or leading slashes will be rejected.
  3. Permission Whitelist:
    • Every entry in permissions must be one of the recognized permission strings: shell, push, pull, install, forward, reverse.
    • Unknown permissions will fail manifest validation with an explicit error.
  4. App Version Compatibility:
    • If minAppVersionCode exceeds the running Dioxamine application version, installation will be blocked with a compatibility notice.