Version ranges

Matrix uses standard npm semver ranges. There is no Matrix-specific range syntax.

Range syntax

These all work in package.json dependencies, devDependencies, peerDependencies, etc., exactly as npm specifies:

Range	Resolves to
1.2.3	exact version 1.2.3
^1.2.3	>=1.2.3 <2.0.0
~1.2.3	>=1.2.3 <1.3.0
1.x, 1.*	>=1.0.0 <2.0.0
>=1.2.3 <2.0.0	range expression
1.2.3 || 2.0.0	OR of versions
latest	dist-tag
next, beta, alpha	dist-tag (target state — only latest is actively published today)

This is npm semver (https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies), verbatim. No Matrix-specific overlay.

Pre-release handling

Pre-release versions (0.2.3-rc.1, 1.0.0-alpha.0) follow strict semver-precedence rules. They are excluded from caret/tilde ranges by default:

• ^0.2.3 matches 0.2.4 but not 0.3.0-rc.1.
• To include pre-releases, write ^0.2.3-rc.0 (any pre-release of the same patch) or >=0.2.3-rc.0 <1.0.0.

Lockstep release reality

Most @open-matrix/* packages release together. In practice, current package.json files use either * (any version) or workspace:* (when inside the monorepo) or pinned exact versions; tight semver ranges aren't heavily exercised yet.

The bundled-package store on hivecast install contains all default packages at the same hivecast release; mixing versions on a fresh install is unusual. For consumers installing a specific Matrix package outside the bundled set, standard semver applies.

Catalog limitation

The package catalog (system.packages.registry.search) returns only the latest version per package. It cannot answer "what versions of @open-matrix/chat exist?" That information is in the artifact registry's package metadata endpoint:

curl -fsS https://registry.hivecast.ai/api/packages/hivecast-admin/npm/@open-matrix/chat | jq '.versions | keys'

For programmatic version listing, use the Gitea HTTP endpoint, not the catalog.

See also

• Package refs
• Channels
• Compatibility

Source: npm semver. No Matrix-specific extension exists or is planned.