How should a package author design and document a clear, stable public API for their package while still being able to freely refactor internal implementation details?

A well designed package clearly distinguishes between its public API, meaning the classes, methods, and interfaces that consumers of the package are meant to directly use and depend on, and internal implementation details that consumers should never rely on directly, often reinforced through clear documentation, appropriate visibility modifiers marking internal helper classes or methods, and sometimes explicit naming conventions, giving the package author freedom to refactor internal details in a minor version release without breaking any project that only depends on the documented public API.

// Public API: stable, documented, safe to depend on
class Validator {
    public function validate(array $data): bool { /* ... */ }
}

// Internal: marked private, not part of the public contract
private function normalizeInput(array $data): array { /* ... */ }