Stability & Versioning
What you can rely on, what may change, and how you will find out. Pulse is currently 0.38.0: pre-1.0, so the rules below for 0.x apply.
What counts as public API
Everything in this table is covered by the versioning rules. Anything else (files under src/ that are not reachable through an export, undocumented options, the exact HTML a component renders, the text of warnings and error messages) is internal and can change in any release.
| Surface | Where it is defined |
|---|---|
| Spec keys and their behaviour | spec.js reference, types/schema.d.ts |
createServer options and the context (ctx) passed to guards, fetchers and render | Server API reference, types/server.d.ts |
The runtime: mount, initNavigation, the data-* attributes the runtime binds (data-event, data-action, data-key, data-preserve, …) | Hydration and Navigation guides |
| UI component exports and their props | Component pages, @invisibleloop/pulse/ui |
| Package entry points | ., /server, /runtime, /ssr, /navigate, /schema, /image, /html, /ui, /charts, /testing, /md |
| CLI commands and flags | pulse --help |
pulse.config.js fields | Configuration |
| MCP tool and resource names, and their arguments | Slash Commands and How It Works |
How versions are numbered
| Release | Before 1.0 (now) | From 1.0 |
|---|---|---|
| Patch (0.22.x) | Bug fixes, docs, internal changes. Safe to take. | Same. |
| Minor (0.22.0) | New features, and may contain breaking changes. Read the release notes before upgrading. | New backwards-compatible features only. |
| Major | Not used until 1.0. | Breaking changes, and only here. |
New projects depend on ^0.38.0, which before 1.0 accepts patch releases only, so a fresh install cannot silently move to a release with breaking changes. Move up deliberately with pulse update.
main publishes a release, so versions advance quickly. The version number tells you the kind of change (derived from the commit type), not how large it is.Where changes are announced
Release notes are the GitHub Releases for each version, generated from the titles of the merged pull requests. A breaking change is marked as such in its pull request title.
Deprecation and removal
- From 1.0: a public API is deprecated in a minor release (with a warning that names the replacement) and removed no sooner than the next major release.
- Before 1.0: removals can happen in a minor release. They are listed in the release notes, and where practical the old form keeps working for at least one minor release with a warning.
- Security fixes are the exception: they can change behaviour in a patch release when a vulnerability cannot be fixed compatibly.
Supported versions
Only the latest published version receives fixes, including security fixes (see SECURITY.md). Node.js 22 and 24 are tested in CI; the supported range is >=22.
Upgrading with an AI agent
The pulse_update MCP tool does not upgrade on its own: its first call reports the installed and latest versions, the agent asks you, and it installs only after you approve.