Add a published .d.ts diff to the release process to catch breaking type changes

リポジトリに既存の release または CI プロセスから始め、npm pack を使用して最新の公開済みパッケージと release candidate を比較します。dist/*.d.ts を抽出し、非加法的な型の変更を特定して、チェックを失敗させるか、適切なバージョンの引き上げを伴う breaking change の明示的な承認を必須にします。

Problem

4.2.4 shipped as a patch but contained breaking TypeScript type changes with no changelog note. The main one: ObservableStatus<T> was refactored from a flat interface (data: T) into a discriminated union (data: T | undefined unless narrowed on status), which breaks the standard destructure-and-use pattern across every data hook, including the documented suspense pattern. It is type-only (no runtime impact), but it reds strict-TS consumer CI on upgrade.

It slipped through because:

• The change came in via #583 ("use useSyncExternalStore to sync data"), whose title looked like an internals change, not a public API break.
• It then sat unreleased for ~3 years (v4.2.3 was 2022-08, #583 merged 2023-07).
• 4.2.4 batched 35 PRs of accumulated main into one bump, with no step auditing the cumulative public type surface.

Proposal

Add a release-time (or CI) check that diffs the candidate's emitted types against the last published version:

1. npm pack the latest published version, extract dist/*.d.ts.
2. npm pack the release candidate, extract dist/*.d.ts.
3. Diff them. Any non-additive change (removed/narrowed/changed signature) fails the check or requires an explicit "breaking" acknowledgment and a minor/major bump.

This exact diff would have flagged both the ObservableStatus union change and the useFirestoreDocData widening (#733) immediately.

Related

• Remediation for the live 4.2.4 release is tracked separately (deprecate + re-cut as 4.3.0 with a migration note).
• Surfaced while reviewing #740.