Manifest

Every plugin ships a manifest.json at the repository root. The manifest is used during install, permission review, packaging, runtime loading, and catalog publication.

Minimal Level 0 Manifest

{
  "id": "dev.example.my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "Short user-facing summary.",
  "author": "Example",
  "compatibility": {
    "min_app_version": "0.8.0",
    "min_host_api_version": "0.2.13"
  },
  "capability_levels": [0],
  "host_capabilities": ["navigation", "file_intents", "theme_read"],
  "integration": {
    "level0": {
      "module_id": "my-plugin",
      "module_label": "My Plugin",
      "module_icon": "Sparkles",
      "sidebar_position": "main",
      "sidebar_order": 120,
      "panel_entry": "app/dist/index.js"
    }
  },
  "window": {
    "default_open_mode": "reuse_or_new",
    "reuse_key": "resource",
    "allow_multiple": true,
    "document_handlers": [
      {
        "id": "markdown",
        "label": "Markdown",
        "extensions": [".md", ".markdown"],
        "mime_types": ["text/markdown"],
        "route": "/document",
        "resource_param": "path"
      }
    ]
  },
  "entry": {
    "native": {
      "macos_arm64": "backend/target/release/libmy_plugin.dylib",
      "windows_x64": "backend/target/release/my_plugin.dll",
      "linux_x64": "backend/target/release/libmy_plugin.so"
    },
    "frontend": "app/dist/index.js",
    "frontend_styles": "app/dist/styles.css"
  },
  "permissions": [
    { "type": "ipc_register" },
    { "type": "host_theme_read" }
  ],
  "commands": [
    { "id": "ping", "description": "Return plugin health information." }
  ]
}

Rules

• id is stable forever after publication.
• version uses semver. Official plugins should start at 0.1.0.
• host_capabilities must match the SDK helpers the frontend consumes.
• permissions must be the smallest set needed for the feature.
• entry.frontend points to the built JavaScript bundle.
• entry.frontend_styles points to the built stylesheet when the plugin emits CSS.
• integration.*.panel_entry should point to the panel bundle used by the integration.
• commands[].id matches Rust backend command names before SDK prefixing.

Window Policy

Plugins can declare a window block when their routes or resources should participate in HaloForge’s multi-window dispatcher.

Multi-window policies require HaloForge 0.8.0 or newer and plugin host API 0.2.13 or newer. Keep compatibility.min_app_version and compatibility.min_host_api_version aligned with those requirements when publishing a plugin that declares window.

Field	Meaning
default_open_mode	smart, current, new_window, reuse_existing, or reuse_or_new.
reuse_key	plugin, route, resource, or none.
allow_multiple	Whether the plugin can have multiple windows open at once.
document_handlers	File/resource handlers that map extensions or MIME types into plugin routes.

The plugin declares intent; the host still owns actual window creation, focus, session restore, snap-layout compatibility, and conflict handling.

document_handlers entries support:

Field	Meaning
id	Stable handler ID unique within the plugin.
label	User-facing label for menus and open-with surfaces.
extensions	Lowercase extensions including the dot, for example .md.
mime_types	MIME types handled by this plugin.
route	Plugin route opened for the resource.
resource_param	Query parameter that receives the resource path or URI. Defaults to path.
open_mode, reuse_key, allow_multiple	Handler-level overrides for the plugin window policy.

document_handlers power host-owned file dispatch surfaces such as Open File and Open With. Source-specific host commands may still choose a stricter target: for example, File > Open Markdown is a current-window navigation action, while OS file activation and deep links can use the multi-window policy above.

The application menu bar is not a plugin-controlled DOM surface. As of host API 0.2.13, plugins should not assume they can inject arbitrary File/Edit/View menu items. If a plugin needs menu actions, add a documented, declarative manifest/SDK contribution first so HaloForge can keep labels, permissions, window targeting, and native menu behavior consistent.

Common Host Capabilities

Capability	SDK surface
navigation	useHostNavigation()
app_state	useHostAppState()
file_intents	useHostFileIntent()
file_dialogs	pickHostFile(), pickHostDirectory(), saveHostFile()
aichat	useHostAI()
enterprise_gateway	enterpriseGateway()
theme_read	useHostTheme(), useAppTheme()
event_subscribe	useHostEvent()

enterprise_gateway is the historical capability name for the host-managed image gateway. User-facing UI should say “HaloForge Cloud gateway” or “Managed gateway” unless the screen is explicitly enterprise-only.

Permission Naming

Permission names are strict. For example, AIChat access is host_aichat_access, not host_a_i_chat_access.

Managed image gateway access uses:

{ "type": "host_enterprise_gateway_access" }

The permission name is retained for compatibility. Product language should remain neutral.