Este contenido aún no está disponible en tu idioma. Mostrando la versión en inglés.

API Stability Policy

Starting with v1.0.0, Oroya Animate follows a tagged stability model inspired by @microsoft/api-extractor. Every export from a @joroya/* package’s barrel (src/index.ts) is governed by one of three TSDoc tags. The AST audit requires every exported declaration to carry a stability tag:

Tag	Stability	Breaking change policy
`@public`	Stable	Breaking changes require a major version bump. Two-version deprecation window before removal.
`@experimental`	In flux	May change shape or be removed in any minor release. Pin the version if you depend on it.
`@internal`	Implementation detail	Not part of the public surface. Importing from outside its declaring package is unsupported and may break in any release.

Untagged exports default to @public (so the policy is conservative — if you forgot to tag something, you owe semver coverage on it).

Examples

/**
 * @public
 * Engine-agnostic scene-graph container.
 */
export class Scene { ... }

/**
 * @experimental
 * 2-bone analytical IK solver. Argument shape may change.
 */
export function solve2BoneIK(...) { ... }

/**
 * @internal
 * Renderer-private cache key format. Not exported from the barrel.
 */
export function makeCacheKey(...) { ... }

What remains `@experimental` in v1.2.0

These pieces are deliberately tagged experimental because their shape is still settling:

solve2BoneIK — argument order (world-space vs local-space inputs) may be reworked once a multi-bone IK solver lands.
Vehicle — wheel-options shape mirrors cannon-es directly; we may introduce friction tweaks per wheel as a follow-up.
WASM acceleration hooks (registerMathBackend) — the surface is in place but no production WASM ships yet.

Everything else exported from the @joroya/core, @joroya/renderer-*, @joroya/loader-gltf, @joroya/physics, @joroya/inspector, @joroya/input, and @joroya/assets package barrels is @public.

React/Vue bindings and the plugin registry/lifecycle are @public from 1.2.0. Their ownership and update contracts are covered by regression and real browser tests. See capabilities and acceptance.

SvgRenderer and SvgRendererOptions are additive @public exports from @joroya/renderer-svg starting in 1.3.0. The snapshot/export APIs keep their existing contracts. See persistent SVG scenes.

Tooling

pnpm api:check reports missing tags, exposed internals and unresolved exports across direct declarations, aliases, types and star chains. It remains informational.
pnpm api:compat compares the public declaration baseline and blocks removals, incompatible property/call signatures and required additions to option/definition contracts. Runtime semantics remain covered by tests.
pnpm architecture:check enforces package dependency direction.
pnpm api:check:strict fails on those issues and is required by CI.
Per-package dist/index.d.ts is the canonical surface. If a symbol is in that file, it is part of the public API regardless of in-source tag. Use @internal and keep the symbol out of the barrel for internals.

Migration windows

A @public symbol marked @deprecated in version N.x.y remains present (with a console.warn on first use, where possible) through version (N+1).x.y. It is removed in (N+2).0.0. This gives consumers at least one major version of notice for every breaking change.

Pre-1.0 history

Versions 0.1.0 through 0.12.0 predate this policy. The CHANGELOG records every breaking change in those versions, but no formal deprecation windows existed — pre-1.0 callers absorbed those breaks directly. From v1.0.0 forward, that does not happen on @public APIs.