Svelte 5 migration plan

[ericpgreen2]

Plan for migrating from Svelte 4 to Svelte 5 and upgrading bits-ui 0.22 → 2.x in a single PR.

Originally planned as two PRs (Svelte 5 bump first, bits-ui upgrade second), but research showed this isn't viable:

• bits-ui 0.22's dependency @melt-ui/svelte 0.76.2 explicitly excludes Svelte 5 (>=3 <5) and has known runtime bugs
• bits-ui maintainer confirmed 0.x won't be updated for Svelte 5
• bits-ui 2.x requires Svelte 5 (^5.33.0), so upgrading bits-ui first on Svelte 4 is also not possible
• The two upgrades must happen atomically

The plan is in .claude/plans/svelte-5-upgrade.md. Includes dependency compatibility analysis, migration steps, scope estimates, and future work.

Checklist:

• Covered by tests
• Ran it and it works as intended
• Reviewed the diff before requesting a review
• Checked for unhandled edge cases
• Linked the issues it closes
• Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
• Intend to cherry-pick into the release branch
• I'm proud of this work!

---

Developed in collaboration with Claude Code

[djbarnwal]

I asked claude some questions around the bits ui part. Got this -

No, you can't reliably use bits-ui v0.x with Svelte 5. The library's peer dependencies require Svelte 4, and the internal implementation uses Svelte 4 APIs (like let: directives and slot-based patterns) that behave differently or break in Svelte 5.
Svelte 5 does have a compatibility layer for Svelte 4 components, so some things may work partially, but bits-ui v0.x is not tested or supported on Svelte 5 — you'd likely hit subtle bugs and broken behavior, especially around transitions, slots, and event handling.
Bottom line: Upgrading to Svelte 5 means you also need to upgrade to bits-ui v1.x and migrate your component usage. There's no shortcut here.