Skip to content

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:

Terminal window
npm install --save-dev --save-exact @phoundry/phials-plugin-sdk@3.1.0

Commit 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:

  1. Its shape is present in the installed SDK or a documented public package export.
  2. Its behavior is described in the corresponding public reference or task guide.
  3. The release declares a pluginApiVersion and minAppVersion that include the surface.
  4. 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:

  1. The versioned SDK package defines public TypeScript and manifest shapes.
  2. A dedicated reference defines the exact behavior of that shape.
  3. A task guide explains a supported workflow using the reference.
  4. 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.

This article includes AI-assisted content.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.