feat: hold first paint for fonts and fade in the ui on load

[flamboh]

Note

🤖 Claude Opus 5.5 on behalf of Oliver

ELI5

The app now waits a split second for its font before appearing, then gently fades in so nothing jumps around while it loads.

Problem

On a cold load, text first renders in a fallback font and then swaps to Satoshi, and the whole UI appears at once. Together, that makes the first second feel jarring.

Fix

• src/runtime/holdForFonts.ts adds fonts-loading to <html> and removes it once Satoshi loads, or after 800ms, whichever comes first. Satoshi is a variable font, so a single document.fonts.load covers every weight.
• A new page-enter tailwind utility fades a region in with a 6px rise over 480ms. page-slide-in slides a region in from off-screen left with no fade, on an ease-out curve (cubic-bezier(0.22, 1, 0.36, 1), the same curve the mobile drawer uses). Both stay paused while fonts-loading is set, and both use backwards fill so no transform is left behind to break fixed descendants.
• Workspace: the main column fades in place (no rise), while the sidebar slides in at the same time (desktop only, so the mobile drawer is unaffected). The share page and the save app's theme toggle and column fade up, with the column 60ms behind the toggle.
• Under reduced motion, nothing moves: the rise drops to 0 and the sidebar slide becomes a fade.

UI Changes

Before

https://gh-file-drop-api-prod-galwoqjslzlnws6s.oliver-boorstein.workers.dev/f/a4f17b9b63b51c2b/before.webm

After

This recording predates the current motion: in it, both regions fade and rise, and the sidebar enters first.

https://gh-file-drop-api-prod-galwoqjslzlnws6s.oliver-boorstein.workers.dev/f/4e6d8628b90524ec/after.webm

Review guide

• Flows: Hard-reload / and /?app=tagium-save with cache disabled and "fast 4g" throttling. Expect no fallback-font flash: the main column fades in place in Satoshi, as the sidebar slides in from the left, fully opaque, at the same time. Also open a share link to check the page fades in.
• Edge cases: Block *.fontshare.com; the UI should still appear after about 800ms in the fallback font. On mobile (390px), the drawer should not flash during load and should still open and close. With reduced motion enabled, everything fades with no movement, including the sidebar.
• Tradeoff: On a cold cache, the UI waits up to 800ms for the font. Warm loads are effectively instant because the font promise resolves immediately. In vp dev, the CSS is injected by JS, so the hold may not engage; it is reliable in production builds.
• Verified: tsc, lint, and all 682 unit tests pass. A Codex browser pass on production builds (before vs. after) confirmed the font hold, the 800ms cap, the stagger, transform: none after the animation, the mobile drawer, the save app, reduced motion, and no new console errors.

---

Made by Claude Opus 5.5 in Claude Code (T3 Code), browser verification by GPT-6 Sol in Codex.

[github-actions]

React Doctor found 2 new issues in 2 files · 2 warnings · score 93 / 100 (Great) · 2 fixed · vs main

2 warnings

src/features/library/TagSidebarPanel.tsx

• ⚠️ L82 React function has high control-flow complexity no-high-complexity-react-function

src/features/workspace/audioTagger.tsx

• ⚠️ L45 React function has high control-flow complexity no-high-complexity-react-function

_{Reviewed by React Doctor for commit 617f820. See inline comments for fixes.}

[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	617f820	Commit Preview URL Branch Preview URL	Sep 25 2026, 10:14 AM