Manifest reference

Manifest reference

Complete structure

{
  "id": "top.qomicex.assistant",
  "name": "AI Assistant",
  "version": "1.2.0",
  "minLauncherVersion": "0.1.0",
  "layers": ["l3"],
  "render": "iframe",
  "permissions": ["ui:toast", "config:read", "config:write", "network:cors_proxy"],
  "dependencies": [
    { "id": "top.qomicex.markdown", "version": ">=1.0.0" }
  ],
  "entry": {
    "frontend": "dist/index.html",
    "theme": "dist/theme.css"
  },
  "contributes": {
    "menuItems": [
      { "path": "/plugins/p/top.qomicex.assistant", "label": "AI Assistant", "icon": "A", "action": "overlay" }
    ],
    "overlay": {
      "file": "dist/overlay.html",
      "title": "AI Assistant",
      "width": 380,
      "height": 500,
      "minimizable": false,
      "resizable": true
    }
  }
}

Field summary

entry object

contributes object

Plugin-owned i18n (l10n)

l10n/
├── bundle.json          # default language (English recommended)
└── bundle.zh-CN.json    # overrides by launcher locale

const strings = await __PLUGIN_API__.call('getPluginStrings')  // merged bundle (no permission)
const locale = await __PLUGIN_API__.call('getLocale')           // e.g. 'zh-CN'

icon field spec (menus / install modes / top-level icon)

1. Font Awesome class name (recommended): "fa-solid fa-server". Zero assets, follows the theme color (currentColor), resolved by the launcher (sidebar and install dialogs render uniformly).
   • Do not hardcode the available set: the built-in table evolves with the launcher. Get the full list at runtime with call('listIcons'), or offline from the ICON_NAMES export of @qomicex/plugin-ui.
   • Names outside the table render blank (historically ignored silently). qomicex verify / lint validate them statically, report an error, and suggest the closest built-in names.
   • In-page icons should not call getIconSvg; use <Glyph> with per-icon subpath imports (see Plugin API — Icons).
2. In-package relative path: "dist/icon.svg" (for multicolor/brand icons; resolved to the plugin file-service URL).
3. Absolute URL / emoji / plain text: e.g. "https://…/icon.png", "🏆", "A". Emoji do not follow the theme color and do not scale well; prefer option 1 or 2.
4. Private icons (contributes.iconTheme): point at an in-package icon-theme.json shaped as { "schemaVersion": 1, "icons": { "<icon key>": { "type": "svg", "path": "M…" } } }. Declared keys show up in listIcons() and are resolved first by getIconSvg — you can ship icons the built-in table lacks without waiting for a launcher release.

installModes array elements

__PLUGIN_API__.registerMethod('installMode:to-server', (ctx) => {
  // ctx = { kind: 'modpack', source: 'modrinth'|'curseforge'|'technic',
  //         projectId?, fileId?, name, gameVersion?, iconUrl?, path? }
  // path is only present for local imports; the method should return fast
  // (kick off the task and return), reporting progress to the download center itself
})

hooks array elements

{
  "permissions": ["hook:register"],
  "contributes": {
    "hooks": [
      { "method": "scanVersions", "priority": 10 }
    ]
  }
}

menuItems array elements

settingsPages array

{
  "contributes": {
    "settingsPages": ["dist/settings.html"]
  }
}

• Each path is the relative path of an HTML file inside the .qplugin package; the tab disappears automatically when the plugin is disabled
• The launcher renders one tab per path under Settings → Plugins → Plugin settings (vertical tabs on the left list each plugin; the right side is an iframe sandbox with the same __PLUGIN_API__ bridge as plugin pages)
• For the full development guide (writing the settings HTML, using getSettings/setSettings, openPluginSettings navigation, lifecycle rules), see Plugin settings page

icon examples

// 1) emoji / plain text
{ "path": "/plugins/p/xxx", "label": "AI Assistant", "icon": "🤖" }

// 2) absolute URL
{ "path": "/plugins/p/xxx", "label": "AI Assistant", "icon": "https://example.com/icon.png" }

// 3) relative path inside the package (recommended)
// put the file at dist/icon.png in the plugin package and reference a relative path in the manifest
{ "path": "/plugins/p/xxx", "label": "AI Assistant", "icon": "dist/icon.png" }

Top-level icon (library plugin icon)

{
  "id": "top.qomicex.markdown",
  "name": "MarkdownLib",
  "icon": "fa-solid fa-file-lines",
  "layers": ["l3"],
  "entry": { "frontend": "dist/index.html" }
}

• The supported forms match menuItems[].icon (emoji / absolute URL / relative path inside the package / FontAwesome class name)
• Plugin management cards read them in this order: contributes.menuItems[0].icon ?? manifest.icon
• Library plugins should use the top-level icon and should not declare contributes.menuItems (which creates a sidebar entry)
• Prefer FontAwesome class names for icons (such as fa-solid fa-file-lines, fa-brands fa-markdown; they must be in the launcher’s BuiltinIcons.tsx preset list): SVG paths rendered through <img> stay black and do not follow the theme, whereas FA class names follow the light and dark themes

overlay object

layers layer definitions

{ "layers": ["l2", "l3"] }

• The iframe sandbox is the default rendering mode: plugins with entry.frontend use the iframe sandbox by default (<iframe sandbox="allow-scripts"> plus a postMessage bridge), isolated from the main UI’s DOM/CSS (opaque origin, preventing CSS leakage and same-origin theft). Inline rendering (same context as the main UI, compatible with older plugins) only happens when the manifest explicitly declares "render": "inline".
• The iframe sandbox also supports all __PLUGIN_API__ methods, .p-* component styles, and registerMethod/callPlugin (relayed across windows)
• Sandboxed plugin scripts run automatically when the srcdoc is parsed, without visiting the page
• Plugin activation conditions: after installation a plugin starts in the installed state, and actual activation depends on two things: ① entry.frontend exists (activatePlugin only renders and marks active when entry.frontend exists); ② the user enables it in the plugin list. This is independent of the layers declaration; a pure ["l3"] plugin with entry.frontend is still activated (using the iframe sandbox by default).
• Differences between the iframe sandbox and inline rendering:

  Dimension	iframe sandbox (default)	Inline rendering ("render":"inline")
  Isolation	Fully isolated from the main UI (separate window, opaque origin)	Same window as the main UI
  Script execution	Runs as soon as the srcdoc is parsed	Runs immediately when loaded on activation
  Dependency injection	registerMethod notifies the main window to relay	Calls the main window registry directly
  Use cases	Plugins that need isolation and independence (the recommended default)	Lightweight UI, plugins that need access to the main UI DOM

• L0/L1 are currently reserved declarative layers with no standalone runtime mechanism yet; L3 WASM is implemented: plugins that declare l3 and ship plugin.wasm in the package are loaded and executed by the launcher’s Rust layer (wasmtime) (see WASM plugins)
• L4 remote WebView is implemented: for plugins that declare render:"webview" or include "l4" in layers, the main window calls createRemoteWebview on activation to open a standalone Tauri WebviewWindow (process-level isolation from the main UI); the plugin UI renders inside that window, and API calls are forwarded to the main window through Tauri events for execution (see L4 remote WebView)
• Plugins that need an isolated environment or a long-running script (such as AI assistants or tool panels) → use the default iframe sandbox
• Pure UI/theme plugins, or lightweight plugins that depend on the main UI DOM → explicitly declare "render": "inline"
• If the plugin will later add WASM backend logic, you can layer "l3" on top
• Heavy UI / untrusted / process-isolation plugins (such as complex editors or game UI enhancements) → declare "render": "webview" or include "l4" in layers (standalone window, so a busy loop does not affect the main UI)

Version range syntax

• Segments are split on . and compared numerically one by one; - (prerelease) and + (build number) suffixes are ignored
• A missing segment counts as 0 (so 1.0 equals 1.0.0)
• ^, ~, *, the x wildcard, ||, and commas are not supported