Compatibility

An extension must be compatible across its package release, manifest format, extension API, Terminay release, and Node runtime. Declare all but the package version in its manifest.

Declare your ranges

JSON 
"terminay": {
  "manifestVersion": 1,
  "api": "^1.2.0",
  "engines": {
    "terminay": ">=1.0.0",
    "node": ">=20"
  }
}
AxisRule
npm package versionYour release identity. Terminay installs an exact resolved version and integrity, never an implicit latest update.
manifestVersionUse 1. Unknown fields and unsupported formats fail validation.
apiThe public Extension API SemVer range. A major is breaking; minors add capabilities.
engines.terminay and engines.nodeState the Terminay and bundled Node versions your compiled package requires.
platformsOptional allowlist for darwin, linux, or win32.

How activation is decided

  1. Terminay validates the manifest, entrypoint, platform, and engine requirements.
  2. Its exact supported Extension API must satisfy your declared api range.
  3. It imports and probes the package in a fresh extension host.
  4. Only a successful registration becomes active.

Terminay never guesses or coerces an incompatible range. An incompatible extension remains visible as incompatible rather than silently falling back to another provider.

Release safely

  • Test the packed artifact—not only your working directory—against the intended Terminay release.
  • Make a new package version when you change the compiled code, manifest, or permissions.
  • Keep the API range as narrow as your implementation requires; do not claim a future major.
  • Declare compatible extension dependencies separately from ordinary npm library dependencies.

Updates install alongside the current slot and need fresh confirmation if permissions expand. Terminay retains a known-good slot; update or activation failure leaves the prior active version in place.