Public plugin API contract (v1)

This note is the authoritative contract for the supported surface of community plugins. Types and manifest tooling live in the phials-plugin-example repository under sdk/ — that is the single source of truth for authoring.

Related: Getting started · Plugin types overview · Community plugins · Plugin overview · Provider guides under types/

Trust and security model

Community plugins are distributed as JavaScript executed in the same renderer process as Phials (dynamic import() of bundled main.js). That is trusted plugin execution: the bundle runs alongside the rest of the app window and can use the same browser capabilities unless a future version adds stronger isolation (not part of v1).

Phials exposes a PluginAPI object to onActivate and to provider hooks. For external plugins, parts of that API are permission-gated:

invoke is limited to an allowlist of Tauri command names derived from declared manifest permissions (see Community plugins).
clipboard read/write on the API object requires the corresponding manifest permissions when the host injects that surface.
fetch on the API object requires network.fetch when the host injects that surface.

Manifest permissions do not create a sandbox. They do not prevent a malicious or compromised bundle from using ungated browser APIs (for example calling fetch directly, importing other scripts, or touching DOM outside what Phials controls). The permission model gates Phials-provided helpers so honest plugins declare intent and the UI can communicate risk; it is not a security boundary against arbitrary code.

Launch vocabulary: Use trusted community plugins with permission-gated Phials APIs. Avoid calling renderer-loaded plugins “sandboxed” unless a real isolation mechanism exists.

Versioning and compatibility

Manifest fields (today and planned)

Field	Status	Role
`version`	Required today	Semver of the plugin package.
`minAppVersion`	Required today	Minimum Phials application version (semver). The host rejects incompatible bundles at install and activation.
`pluginApiVersion`	Optional (defaults `1.0.0`)	Semver of the public API contract / SDK surface. The host’s supported contract (exposed at runtime via Tauri) must be ≥ the manifest value.

Authors should treat minAppVersion as “earliest Phials build that can load and run this bundle correctly” and pluginApiVersion as “contract version this bundle was compiled against” (optional; defaults to 1.0.0 when omitted).

Semver expectations

Plugin version: follow semver for user-visible releases.
minAppVersion: use the lowest Phials version whose behavior the plugin actually requires.
pluginApiVersion (when added): bump major for breaking contract changes, minor for additive APIs, patch for documentation-only or non-breaking clarifications, aligned with project policy when published.

Additive vs breaking (contract)

Additive (minor / patch): New optional fields on types, new event names, new commands in the allowlist behind new permissions, new provider capabilities that old hosts ignore safely.

Breaking (major): Removing or renaming types, changing required manifest fields, narrowing permissions, changing callback signatures, or changing semantics of existing fields.

Current behavior

The host checks minAppVersion against the shipped Phials version and pluginApiVersion (or default 1.0.0) against the supported contract. filesystem.write implies read-level invoke commands at the API layer; network.fetch gates PluginAPI.fetch only, not all network use from script. shell.execute is not a supported v1 permission.

Classification of types

Stable public (v1) — plugin container and providers

Defined in sdk/plugin-types.generated.d.ts in phials-plugin-example (generated file — do not edit by hand; update by upgrading the example repo / sdk/ you depend on):

Category	Types
Container	`PhialsPlugin`
Provider union	`PluginProvider`, `ProviderType`
Preview	`PreviewProvider`, `PreviewProviderProps`, `ThumbnailProviderProps`, `FullscreenProviderProps`, `ProviderQuickAction`
Context (legacy)	`ContextProvider`, `ContextProviderItem`, `ContextProviderCategory`, `ContextItemContext`, `ItemShortcutConfig` — prefer commands for new work (below)
Metadata	`MetadataProvider`, `RawMetadata`, `ExtractedMetadata`, `FileMetadata`, `MetadataSchemaField`, `MetadataSchema`, `MetadataColumnPolicy`, `DirectoryMetadataProfileOptions`, `MetadataProviderDirectoryStats`, `DirectoryMetadataProfile`
Toolbar (legacy)	`ToolbarButtonProvider`, `ToolbarContext`, `ToolbarSubToolbarProps`, `ToolbarButtonDefinition`, `ToolbarButtonGroupDefinition`, `ToolbarButtonDropdownDefinition`, `ToolbarDropdownItem` — prefer commands with `toolbar` placement for new work
View	`FileBrowserViewProvider`, `FileBrowserViewProps`, `ViewColumnDefinition`
Theme	`ThemeProvider`, `ThemeVariables` (re-exports phoundry-ui theme shapes)
Selection (deprecated)	`SelectionProvider`, `SelectionContext`, `SelectionProviderItem`
Module	`ModuleProvider`, `ModuleProviderProps`
Settings / DB	`PluginSettingsSchema`, `SettingsField`, `SettingsFieldType`, `BooleanSettingsField`, `StringSettingsField`, `NumberSettingsField`, `SelectSettingsField`, `PathSettingsField`, `PluginDatabaseSchema`, `PluginTableDefinition`, `PluginColumnDefinition`, `PluginIndexDefinition`, `PluginColumnType`
Base and scoped APIs	`PluginAPI`, `PreviewAPI`, `ContextAPI`, `MetadataAPI`, `SelectionActionAPI`, `PluginSettings`, `PluginStorageAPI`, `PluginDatabaseAPI`, `DatabaseExecuteResult`, `ReadonlyAppSettings`, `ModalAPI`, `NotifyAPI`, `FileUtilsAPI`, `FileMatchAPI`, `EventsAPI`, `SelectionAPI`, `ClipboardAPI`, `FileOpsAPI`, `SelectionFileOpsAPI`

Community PluginAPI may also include optional clipboard and fetch members when the host attaches them according to your manifest; treat those as part of the v1 runtime surface even when not repeated on every line of the base type definition.

Stable public (v1) — commands

Shipped as sdk/command-types.generated.d.ts — author-defined surface:

Types
`CommandContextKey`, `CommandContext`, `CommandShortcut`
`CommandPlacementArea`, `CommandPlacementBase`, `ToolbarPlacementConfig`, `HeaderBarPlacementConfig`, `ContextMenuPlacementConfig`, `SelectionBarPlacementConfig`, `CommandPlacement`
`Command`, `CommandProvider`

Deprecated / legacy-preferred

Surface	Status	Preferred direction
`SelectionProvider`	Deprecated	`CommandProvider` with `defaultPlacements` including `{ area: "selectionBar", … }`. See Selection providers.
`ToolbarButtonProvider`	Legacy	`CommandProvider` with `toolbar` placements (and `subToolbar` where needed). See Toolbar providers.
`ContextProvider`	Legacy	`CommandProvider` with `contextMenu` placements and `CommandShortcut`. See Context providers.

All provider type discriminants remain legal in v1 for backward compatibility; new features should use command unless this doc set explicitly points you elsewhere.

Not in `sdk/` (do not use in plugins)

These names are not part of the published plugin contract. If you see them in older snippets or forks, avoid them — they describe host UI plumbing, not something you implement in main.js:

Example (do not use in plugins)	Note
`PluginRegistration`	Host bookkeeping.
`CommandRegistration`, `ToolbarCommandItem`, `HeaderBarCommandItem`, `SelectionBarCommandItem`	Host command UI wiring.
`ContextMenuUserItem`, `ContextMenuUserConfig`, `ToolbarUserItem`, `ToolbarUserConfig`, `HeaderBarUserConfig`, `CommandSettings`	Saved layout / session state inside the app.

Appendix A — `sdk/` layout (phials-plugin-example)

The example repo’s sdk/ folder holds the declarations you reference from your plugin project. Start from sdk/phials-plugin-sdk.d.ts (barrel) or open individual files:

File in `sdk/`	Contents
`plugin-types.generated.d.ts`	Stable public and deprecated types under container, providers, settings, database, and APIs (see tables above).
`command-types.generated.d.ts`	Stable public command types (`Command`, `CommandProvider`, `CommandContext`, placements, …).
`file-types.generated.d.ts`	`FileEntry`, `FileCategory`, and related file model types used on provider signatures.
`shortcuts-types.generated.d.ts`	`ShortcutDefinition`, `PlatformShortcuts`, and types required by `CommandShortcut` / context shortcuts.
`events-types.generated.d.ts`	`EventMap`, `EventHandler`, `EventSubscription`, `CoreEvents`, `PluginEvents`, … (authors augment `PluginEvents` for custom events).
`pane-context.stub.d.ts`	Type-only `PluginPaneContext` stand-in for `CommandContext.pane` in plugin projects.
`manifest-schema.ts`	`PluginManifest`, `PluginPermission`, `ValidationResult`, helpers for authoring and `npm run validate`.

Svelte / UI library

import("svelte").Component and import("svelte").Snippet as used on Command / providers.
phoundry-ui: ToastEntry (on Command.toastData), theme types re-exported by ThemeProvider.

Outside the contract on purpose

Individual Tauri invoke payloads beyond what PluginAPI["invoke"] documents.
Full host core singleton typings beyond what appears on CommandContext and your provider callbacks.

Appendix B — Provider guides

Each first-class provider type has a guide under types/; this contract aligns with:

`type`	Doc
`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

No additional APIs are marked @experimental in the v1 contract. Treat anything not listed in sdk/ or this document as unsupported for plugins until it appears here.