Public plugin API contract (v1)
This document defines the supported API contract for community plugins. The SDK types and manifest definitions in the phials-plugin-example repository under sdk/ serve as the single source of truth for plugin development.
See also: Getting started, Plugin types overview, Type references, Community plugins, and Plugin overview.
Trust and security model
Community plugins execute in the same renderer process as Phials. The dynamic import() of your main.js bundle runs within the application window and has access to browser APIs. Phials does not enforce sandboxing or process-level isolation in the current version.
To help users manage permissions, Phials gates certain capabilities on the PluginAPI instance passed to your plugin:
api.invoke: Restricted to Tauri command names matching your declared manifest permissions.api.clipboard: Methods require clipboard permissions in the manifest.api.fetch: Access requires thenetwork.fetchpermission in the manifest.
These manifest permissions exist to clarify plugin capabilities and inform users of potential risks. They do not sandbox your code or prevent direct access to global browser APIs (such as the browser’s native fetch or direct DOM manipulation).
Versioning and compatibility
Manifest fields
| Field | Requirement | Description |
|---|---|---|
version | Required | Semver string representing the plugin version. |
minAppVersion | Required | Minimum Phials application version required. Phials will not load the plugin if the application version is lower. |
pluginApiVersion | Optional (default: 1.0.0) | Version of the public API contract the plugin uses. Phials will not load the plugin if the application’s API version is lower than this value. |
Set minAppVersion to the earliest version of Phials that supports the features your plugin relies on. Set pluginApiVersion to the API version your plugin is compiled against.
Semver rules
- Plugin
version: Follow semantic versioning for your plugin releases. minAppVersion: Specify the lowest Phials version that supports the APIs and behaviors your plugin uses.pluginApiVersion: Increments represent API compatibility:- Major version changes indicate breaking contract modifications (such as renamed types or altered callback signatures).
- Minor version changes indicate additive features (such as new optional fields or new event types).
- Patch version changes represent non-breaking clarifications or documentation updates.
Additive vs breaking changes
- Additive changes: New optional properties, new event names, new permitted Tauri commands, or new provider capabilities that older application builds can safely ignore.
- Breaking changes: Renaming or deleting types, adding required manifest fields, narrowing permissions, or changing callback parameters.
Current behavior
Phials validates minAppVersion against the running application version, and pluginApiVersion against the supported API contract. If your manifest requests the filesystem.write permission, the corresponding read commands are automatically allowed. The network.fetch permission gates the api.fetch utility, and the shell.execute permission is unsupported.
API types classification
Stable public API types
The following types are defined in sdk/plugin-types.generated.d.ts in the example repository. These files are auto-generated and should not be edited manually.
The community PluginAPI may also expose optional clipboard and fetch fields if requested in your manifest. These are part of the runtime surface even if they are not defined statically on the base type interface.
Command types
Command types are defined in sdk/command-types.generated.d.ts:
Deprecated and legacy-preferred types
| Surface | Status | Recommended approach |
|---|---|---|
| SelectionProvider | Deprecated | Use CommandProvider with defaultPlacements containing selectionBar placements. See Selection providers. |
| ToolbarButtonProvider | Legacy | Use CommandProvider with toolbar placements. See Toolbar providers. |
| ContextProvider | Legacy | Use CommandProvider with contextMenu placements and CommandShortcut. See Context providers. |
All provider type discriminants are supported for backward compatibility. New features should use the command type unless explicitly documented otherwise.
Internal types (do not use in plugins)
The following types represent internal host UI components. They are not part of the public SDK contract and cannot be imported or used in community plugins:
| Internal name | Description |
|---|---|
PluginRegistration | Host activation record. |
CommandRegistration, ToolbarCommandItem, HeaderBarCommandItem, SelectionBarCommandItem | UI command wiring. |
ContextMenuUserItem, ContextMenuUserConfig, ToolbarUserItem, ToolbarUserConfig, HeaderBarUserConfig, CommandSettings | Persisted layouts and user configurations. |
SDK folder layout
The template repository contains the following definition files under the sdk/ folder:
File in sdk/ | Description |
|---|---|
plugin-types.generated.d.ts | Stable public and deprecated provider, container, and settings types. |
command-types.generated.d.ts | Stable command and placement definitions. |
file-types.generated.d.ts | File model types, including FileEntry and FileCategory. |
shortcuts-types.generated.d.ts | Shortcut mappings and definitions. |
events-types.generated.d.ts | Event bus maps and handlers. Authors can augment PluginEvents to register custom events. |
pane-context.stub.d.ts | Type-only stub for CommandContext.pane. |
manifest-schema.ts | Helpers for validation and manifest schema definitions. |
UI and Svelte imports
- Previews and command components can use
ComponentandSnippetfrom thesveltepackage. - The Phoundry UI library exports
ToastEntry(used onCommand.toastData) and styling structure definitions.
Unsupported surfaces
The following surfaces are internal and not supported for community plugins:
- Tauri command payloads not documented on PluginAPI.
- The global application
coresingleton beyond what is exposed on CommandContext or provider properties.
Provider type documentation
type | Link |
|---|---|
preview | preview.md |
context | context.md |
metadata | metadata.md |
toolbar | toolbar.md |
view | view.md |
theme | theme.md |
selection | selection.md |
module | module.md |
command | command.md |
Experimental surfaces
There are no experimental surfaces exposed in the current API version. Any API or type not explicitly documented in the SDK or this contract is unsupported.