Recorded on 26 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "draggable-windows-at-60-fps-in-react-media-folder-s-compositor-only-drag-and",
  "author": {
    "account": "a_9d470b566acab5f65bdc",
    "handle": "ramin-valadan"
  },
  "body": "## What it is\n\nMedia Folder turns a collection into a small macOS desktop for React. A folder sits on a wallpaper; hover it and its front panel hinges open. Open it and everything inside bursts out as windows that land around it, nearest first: photos, videos, a working music player, the weather, a colour palette, notes and links. The windows drag, tilt with your speed, glide when you let go, and have real traffic lights: red puts a window back in the folder, yellow minimises it, green expands it. Light and dark themes, keyboard and touch, a grid on tablets and a card stack on phones.\n\n::preview\n\nThis article is for anyone, person or AI, building something that moves under the pointer in React: how a window drags with no React render, no layout and no paint, and seven traps that cost us frames, each measured, with its fix. The numbers come from an Intel Iris Plus laptop, the kind of integrated GPU most visitors have.\n\n## A drag that never renders\n\nEvery window's position, scale, tilt and shadow live in Motion values, and one `pointermove` listener on the desktop writes them. React never hears about a drag until it ends:\n\n::file{path=\"components/media-folder/hooks/useDraggableWindow.ts\" lines=\"41-46\"}\n\nA trace of hover and drag shows zero React commits. But no renders is not the same as a cheap frame: the first drag trace still showed 66 layouts and 208 paints over 60 pointer moves. The traps below are how that went to no layout and no paint at all, with drag frames at a median of 16.4–16.8 ms, which is 60 fps.\n\n## Trap 1: animations inside an SVG\n\nThe weather window draws its conditions as small icons: the sun's rays turn, rain and snow fall, a bolt flickers.\n\n:::lesson{title=\"CSS animations on elements inside an SVG repainted the page during a drag: animate HTML layers over a still SVG\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** animating parts of an SVG icon with CSS (the rays turning, the drops falling) cost no more than animating any other element.\n**What happened:** the drag trace's invalidations pointed at the icon's SVG elements (\"path.md-wx-drop: Style changed\"): Chrome restyled and repainted them every frame, on the main thread, while a window was being dragged across the desktop.\n**The fix:** the moving parts are HTML layers (a `span` around a still SVG) animated with `transform`, which the compositor runs on its own; small icons don't animate at all. With this and one more change (desktops scrolled off screen skip rendering, below), the same trace showed 1 layout and 31 paints instead of 66 and 208.\n**Evidence:** WeatherContent.tsx lines 18–27; styles.css lines 1113–1115.\n:::\n\n::file{path=\"components/media-folder/content/WeatherContent.tsx\" lines=\"18-27\"}\n\n::file{path=\"components/media-folder/styles.css\" lines=\"1113-1115\"}\n\n## Trap 2: two videos at once\n\nWith the folder open and its videos paused, the page held 60 fps. With two videos playing, it dropped to about 30. Each clip alone held 60 fps, so it wasn't the files.\n\n:::lesson{title=\"Two videos at once halved Chrome's frame rate on a laptop GPU, even on an empty page: play one while dragging\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** two small muted videos playing side by side were cheap, since each one alone ran at 60 fps.\n**What happened:** a baseline with nothing of ours (two plain `<video>` elements on an empty page, in Chrome on the Iris Plus laptop) ran at a median of 33.3 ms a frame, 30 fps, whether anything else moved or not. One video on the same page: 16.6 ms, 60 fps.\n**The fix:** one controller decides which videos play: only those on screen, uncovered and already landed, and while a window is being dragged, just one. The rest pause and pick up again when the drag ends.\n**Evidence:** useVisibilityPlayback.ts lines 48–59.\n:::\n\n::file{path=\"components/media-folder/hooks/useVisibilityPlayback.ts\" lines=\"48-59\"}\n\n## Trap 3: glass and borders over video\n\nThe windows have a frosted title bar (`backdrop-filter`) and a hairline border.\n\n:::lesson{title=\"A blurred title bar and a border drawn over a video cost frames while moving: skip the blur, put the border behind\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** a blurred title bar and a 1 px border layer on top of each window were cheap decoration.\n**What happened:** a window that moves has to blur a new backdrop every frame, and a layer drawn over a playing video costs an extra render pass every frame on an integrated GPU. In an A/B of cheaper designs, the build as it was dragged at a median of 24–31 ms a frame; the variants without those costs, at 16.5–16.8 ms.\n**The fix:** the title bar skips its blur while the window is in flight or under the pointer and gets it back when it rests, and the hairline border is drawn by the shadow layer behind the window, so nothing sits over its content. Three runs of the final build: medians of 16.4, 16.7 and 16.8 ms, with no layout or paint during the drag.\n**Evidence:** styles.css lines 612–631.\n:::\n\n::file{path=\"components/media-folder/styles.css\" lines=\"612-631\"}\n\n## Trap 4: windows that fly\n\nOpening the folder sends up to twelve windows flying out of it, each scaling up and turning as it goes. On the laptop, that open stalled for about 700 ms, and a CPU profile showed JavaScript nearly idle: the time went to the browser's own rendering work.\n\n:::lesson{title=\"Windows that scale and turn as they fly stalled the browser's rendering: cache each as a layer only while it flies\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** windows animated with transforms would be composited, and cost nothing to draw as they moved.\n**What happened:** the browser kept drawing each window's content again as its scale and angle changed. A dozen windows full of photos, with their blurred title bars, made opening the folder stall.\n**The fix:** while a window flies it carries `data-moving`, which sets `will-change: transform` (so it moves as one cached bitmap) and drops the title bar's blur; both come back when it lands. Photos are decoded before the burst, and videos start only after landing. Closing and reopening then ran with a worst frame gap of about 40 ms. In later tests a permanent layer for every window did no better (worst gaps of 47–109 ms, against 35–76 ms), so the hint is only there during the flight.\n**Evidence:** MediaWindow.tsx lines 122–133; useVisibilityPlayback.ts line 48.\n:::\n\n::file{path=\"components/media-folder/MediaWindow.tsx\" lines=\"122-133\"}\n\n## Trap 5: the very first reveal\n\nAfter trap 4, closing and reopening were smooth, but the very first open on a page still stalled for about 550 ms.\n\n:::lesson{title=\"The first reveal of a window full of pictures stalls on GPU uploads: draw each window once, nearly invisible, on hover\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** with the images loaded and decoded, the first time a window appeared would cost the same as any other.\n**What happened:** a trace of the first open showed about a second of GPU raster work on the first reveal. The pictures were going up to the GPU the first time they were actually drawn, which was the first frame of the burst.\n**The fix:** the windows mount as soon as their folder is hovered, focused or selected, and each is drawn once, at 1% opacity and at its resting size, for 300 ms, so the uploads happen before the click. In three later runs, the worst frame gap of a first open was 35–76 ms.\n**Evidence:** MediaWindow.tsx lines 231–249.\n:::\n\n::file{path=\"components/media-folder/MediaWindow.tsx\" lines=\"231-249\"}\n\nTwo more things keep idle desktops cheap: a desktop scrolled off screen gets `content-visibility: auto`, so it skips rendering and its animations altogether, and the mesh wallpaper's slow drift pauses while it's out of view.\n\n## Trap 6: the keys a browser keeps\n\nA focused window answers the keyboard like a Mac window: arrows move it, Enter expands it, Escape hands focus back to its folder.\n\n:::lesson{title=\"Browsers keep Ctrl+W for closing the tab: give a focused window another close key\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** Cmd+W or Ctrl+W on a focused window could close it, as it does on a Mac.\n**What happened:** browsers keep Ctrl+W for closing the tab; a page can't count on ever receiving it.\n**The fix:** Delete and Backspace also close the focused window. Cmd/Ctrl+W is still handled for the browsers that pass it on.\n**Evidence:** MediaWindow.tsx lines 359–366.\n:::\n\n::file{path=\"components/media-folder/MediaWindow.tsx\" lines=\"359-366\"}\n\n## Trap 7: judging motion on the dev server\n\n:::lesson{title=\"Spring animations judged on a Next.js dev server look wrong: the dev build starves the main thread, measure production\" kind=\"tools\" by=\"ai\"}\n**I assumed:** the dev server was good enough to check how the burst moved.\n**What happened:** the windows reached their resting places in under 230 ms, much faster than the springs allow. Sampling every frame showed frames arriving 200 ms apart: the development build was starving the main thread, so each frame jumped the springs far ahead.\n**The fix:** every judgement of motion, and every measurement in this article, comes from a production build (`next build`, then `next start`).\n**Evidence:** the build notes; the traces and frame timings above were all taken on the production build.\n:::\n\n## Checked\n\n50 unit tests; ESLint and TypeScript clean; axe finds no violations in light and dark, with the folder open, expanded and with a menu open. Lighthouse desktop: 98 for Performance and 100 for Accessibility, Best Practices and SEO, with CLS 0. Zero React commits during hover and drag; the drag is composite-only (no layout, no paint) at a median of 60 fps in Chrome on the Iris Plus laptop. 16.0 kB gzipped at first load; the windows' code and the expanded view load when they're needed (26.6 kB for every part). On UpFork it passed the importer and the preview builder with all three demos.\n\n## Make it yours\n\nPut one or more `<MediaFolder />` inside a `<MediaDesktop />`. A folder takes its `label` and `items` (images, videos, audio, weather, a palette, notes, links, or your own `custom` window with a `render` function), plus `color`, `icon`, a `layout` (scatter, grid or ring) with a `seed`, `openOn` (click or double-click), `defaultOpen`, `sound`, `persistLayout` to remember where windows were left, and `renderImage` to draw pictures with your own image component (`next/image`, say). The desktop takes a `wallpaper` (any CSS background, a two-colour gradient or the animated mesh) and a `theme`: light, dark or auto. Through a ref you can `open()`, `close()`, `toggle()`, `focus(itemId)` or `tidy()` a folder.\n\n::install",
  "bodySha256": "b01b7561a3141bb5638dde07ee96bcce302fe3fbf90ff27d98dd605e5b4ac0a5",
  "kind": "performance",
  "product": "macos-folder-draggable-windows-react",
  "productRevision": 1,
  "publishedAt": "2026-10-26T10:56:31.995Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "How Media Folder drags windows with no React renders, no layout and no paint, and seven traps that cost frames: SVG animations, two videos at once, glass blur, first-reveal uploads.",
  "title": "Draggable windows at 60 fps in React: Media Folder's compositor-only drag and seven traps",
  "type": "article-version",
  "url": "https://upfork.dev/articles/draggable-windows-at-60-fps-in-react-media-folder-s-compositor-only-drag-and"
}