fix: block sharing until imports finish and explain why

[flamboh]

Note

🤖 Claude Opus 5.5 on behalf of Oliver

Stacked on #203.

ELI5

Tagium used to let you share an album while its tracks were still downloading. The link then went out with placeholder tags or no cover. Now sharing waits until the import is finished, and the menu tells you what it's waiting for.

Problem

Nothing on the share path checked whether downloads had finished.

• Placeholder metadata: URL-imported tracks get placeholder metadata the moment they're queued. So "share album" / "share track" turned on immediately, and failed or canceled tracks stayed shareable.
• Late cover: the album cover is fetched separately and often lands after the first tracks. Sharing early published an album with no artwork. Recipients then get an explicit empty picture that overrides provider artwork (sharedAlbumDownload.ts).
• Hidden reason: when sharing was disabled, the reason lived only in a hover tooltip, next to a vague "unavailable" label.
• No recheck: publish() never rechecked eligibility, so the library could change after the dialog opened.
• Early hint (feat: spotlight share links for albums and tracks #203): the share hint could fire mid-import, pointing at the first finished track.

Fix

• Eligibility rules (shareEligibility.ts): albums and tracks are blocked while any track is downloading, failed, or canceled, and albums while their cover is still loading. Each case has a specific reason:
  • "2 of 3 tracks are still downloading"
  • "retry or remove the failed track to share this album"
  • "the album cover is still loading"
  • "this track is still downloading"
  • "retry this track's download to share it"
• coverPending album flag: set when a playlist import has a cover URL, and cleared when the cover lands or the fetch fails. A failed cover falls back to sharing without artwork.
• Visible reasons: disabled menu actions show their reason as a second line, replacing the "unavailable" label.
• Publish-time recheck: publish() reruns eligibility and shows the specific reason in the dialog ("… no link was created." / "… the link still has the previous version.").
• Hint timing: the share hint waits until no downloads or cover fetches are running, so it lands on the album once the album is actually ready. It then waits another 2 seconds before appearing; if anything changes in that window (a new import starts, the target changes, the mobile drawer closes), the 2 seconds start over.

Review guide

Setup: VITE_PUBLIC_SHARE_LINKS_ENABLED=true. Clear tagium:feature-discovery in localStorage to see the hint again.

Flows to check

1. Import a soundcloud set or youtube playlist and open the album … menu while it downloads. "share album" is disabled with "N of M tracks are still downloading", and no share hint appears.
2. Let a track fail (for example, cut the network). The album menu says to retry or remove the failed track, and the failed track's own menu says to retry its download.
3. Remove or retry the failed track. If the cover is still loading, the menu says so. Once everything is ready, the share hint appears on the album about 2 seconds later, and "share album" works.
4. Import a single track: the checkmark shows when it saves, and the hint follows about 2 seconds after.

Edge cases

• A cover fetch that fails doesn't block sharing forever; the album shares without artwork.
• Local uploads and received tracks are unchanged; they keep their existing reasons.

Decisions for the reviewer

• Strict gate: failed or canceled tracks block album sharing rather than being silently left out. The user decides whether to retry or remove.
• Settle first: the hint waits for every running import, not just the one it would point at, so it never lands on a half-finished album.
• 2-second delay: it restarts whenever the target changes, including opening the mobile library drawer. So on mobile, the hint shows 2 seconds after the drawer opens.
• Out of scope: soundcloudSetImport.ts is a legacy path only reached from its own test, so I left it.

Verified

• vp check passes, and all 680 unit tests pass. New tests cover:
  • the download/failed/canceled/cover-pending eligibility messages
  • the publish-time recheck
  • the disabled track action
  • the cover-failure path clearing coverPending
  • the hint waiting for imports to settle
  • the 2-second delay, including restarting it when another import starts
• A Playwright script against the dev server (mocked soundcloud/cobalt/cover, with downloads and the cover held back) stepped through every state below, checking each reason in the menu. It confirmed the hint stays hidden mid-import and that sharing turns on once everything is ready. A separate timing run measured the hint appearing 2.4s after a single track saved: the 2s delay plus screenshot and fade-in time.
• Not verified: real (unmocked) imports, and mobile.

UI Changes

Before (#203): mid-import at "downloading 1/3", sharing was already on and the hint fired.

After: each blocked state explains itself.

After: once everything is ready, the hint appears and sharing works.

After: the delay. The track has saved and no hint is showing yet; it appears 2 seconds later.

https://gh-file-drop-api-prod-galwoqjslzlnws6s.oliver-boorstein.workers.dev/f/86ad7f54a4a72726/hint-delay.webm

Full flow:

https://gh-file-drop-api-prod-galwoqjslzlnws6s.oliver-boorstein.workers.dev/f/7c9167e4c869bd8c/incomplete-flow.webm

---

Made by Claude Opus 5.5 in Claude Code (T3 Code).

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tagium	d57e1cf	Commit Preview URL Branch Preview URL	Sep 25 2026, 09:17 AM

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit d57e1cf.}