Public SDK support contract
The public SDK is the complete supported interface between a plugin and Phials. Its boundary is default-deny: a type, field, method, host command, callback behavior, or runtime guarantee is supported only when the public SDK package or this documentation explicitly exposes it.
The current starter pins @phoundry/phials-plugin-sdk to 3.1.0 and targets
Plugin API 3.0.0. The package version identifies the installed SDK artifact;
pluginApiVersion identifies the runtime contract. Check both when updating a
plugin, rather than inferring host compatibility from an npm install.
A value that can be observed at runtime does not become public API by observation. A successful type cast, deep import, or direct browser interaction does not add that behavior to the Phials compatibility contract.
Supported surface
The public SDK consists of these coordinated surfaces:
| Surface | Contract |
|---|---|
| Plugin definition | PhialsPlugin, lifecycle hooks, settings and database declarations, and PluginProvider contracts |
| Capability contracts | Providers and callback props for commands, file viewing and editing, file metadata, file views, and panels and tabs |
| Runtime services | PluginAPI and the specialized API scope supplied to each documented callback |
| Shared models | Public file, command, shortcut, event, context, and component-facing types |
| Manifest | PluginManifest, supported permission names, validation helpers, and compatibility helpers |
| Written behavior | The exact lifecycle, compatibility, permission, event, data, and capability references in this documentation |
The plugin starter uses
the published SDK dependency instead of a copied SDK directory. Its root
env.d.ts enables the ambient declarations:
/// <reference types="@phoundry/phials-plugin-sdk" />Plugin source can then use public names such as PhialsPlugin, PluginAPI, and CommandProvider without importing Phials application source. Import runtime manifest helpers from the package’s public subpath:
import { definePlugin, definePluginManifest, parseManifest,} from "@phoundry/phials-plugin-sdk/manifest";The SDK type reference is generated from the same public source set. It is the quickest way to inspect an exact TypeScript signature. Written reference pages remain authoritative for behavior that a type alone cannot express, including ordering, cleanup, permissions, and failure semantics.
Public helper functions and constants are part of the same generated reference, including validateManifest, SUPPORTED_PLUGIN_API_VERSION, and PERMISSION_DESCRIPTIONS. They are not silently copied around the generated declaration pages.
SDK ownership
Phials publishes the public declarations, manifest schema, supported permission
names, and validation and compatibility helpers as the versioned
@phoundry/phials-plugin-sdk package. The SDK type reference describes public
signatures; the linked behavioral references describe the runtime guarantees.
As a plugin author, install or update the exact SDK dependency, read the public SDK and reference documentation, and test your plugin against the host versions you declare. For the current starter dependency:
npm install --save-dev --save-exact @phoundry/phials-plugin-sdk@3.1.0Commit the package and lockfile changes together. Do not copy application source or maintain a parallel SDK snapshot in your plugin. No SDK-sync command is part of the starter workflow.
Svelte and the phoundry-ui package have their own package contracts and
versions. Their public exports can be used as documented, but their versions
are not Plugin API versions. Phials guarantees only the integration behavior
named in the plugin documentation, not every API exposed by those dependencies.
Default-deny support rules
Plugin code can rely on a surface when all applicable conditions are true:
- Its shape is present in the installed SDK or a documented public package export.
- Its behavior is described in the corresponding public reference or task guide.
- The release declares a
pluginApiVersionandminAppVersionthat include the surface. - Any required plugin permission is present in the release manifest and approved by the user.
The following do not establish support:
- importing from a Phials source checkout or application build output;
- calling a host command absent from the approved host command reference;
- depending on undocumented object fields, DOM structure, CSS selectors, or application state;
- depending on a host persistence format, database layout, file location, or migration detail;
- constructing an API scope instead of using the instance supplied by Phials;
- treating a browser API as a Phials SDK guarantee.
When the public SDK cannot express a generally useful plugin outcome, the supported path is an additive public contract. Until that contract is documented and published, the missing surface is not portable across Phials releases.
Stability classes
Every surface in the current public SDK is stable for the Plugin API version that contains it. There is no experimental public surface.
| Change | Compatibility classification |
|---|---|
| Add an optional field, provider capability, event, method, or manifest behavior | Additive when existing plugins continue to behave correctly |
| Clarify documentation without changing accepted input or observable behavior | Patch-compatible |
| Correct behavior in a way an existing plugin may depend on | Requires an appropriate minimum Phials version; breaking corrections require a new major Plugin API version |
| Rename or remove a public type, method, field, permission, event, or callback parameter | Breaking |
| Add a required field or make an optional callback mandatory | Breaking |
| Narrow accepted input, permissions, delivery guarantees, or lifecycle behavior | Breaking |
An additive SDK feature can require both a newer Plugin API version and a newer minimum Phials version. The Plugin API version identifies the public contract; the minimum Phials version identifies the first app release that implements the behavior the plugin needs.
Contract-change policy
Public contract changes follow semantic versioning:
- patch versions contain non-breaking corrections and clarifications;
- minor versions add backward-compatible public capabilities;
- major versions contain breaking contract changes.
Phials keeps a plugin compatible when the running build satisfies both declared version boundaries. It does not infer compatibility from source code, package dependencies, or a successful build.
Plugin authors should update their pinned SDK dependency, review the public
contract changes, raise pluginApiVersion when using a newer contract, and
raise minAppVersion when it depends on newer app behavior. The exact
comparison is defined in the
version and compatibility reference.
Contract precedence
Use these sources in order of specificity:
- The versioned SDK package defines public TypeScript and manifest shapes.
- A dedicated reference defines the exact behavior of that shape.
- A task guide explains a supported workflow using the reference.
- Examples demonstrate one valid use but do not expand the contract.
If generated declarations, reference prose, and runtime behavior disagree, the release is a contract defect. Do not depend on the discrepancy. Report it with the Plugin API version, Phials version, exact release artifacts, and a minimal reproduction.