Recorded on 26 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "perspective-cards-a-3d-parallax-gallery-hero-with-no-renders-on-pointer-move",
  "author": {
    "account": "a_9d470b566acab5f65bdc",
    "handle": "ramin-valadan"
  },
  "body": "## What it is\n\nPerspective Cards turns a collection into a scene. Ten image cards float in 3D around the headline, all sharing one vanishing point and each turned toward it, and the whole scene moves with the cursor like a camera: near cards travel more than far ones, while the headline drifts gently the other way. Hover a card and it lifts and turns to face you; click it and that exact card grows into a lightbox with swipe, thumbnails and a focus trap, then flies back into its place when you close it. Three layouts (orbit, scatter, arc) are placed by a seeded engine that never lets a card cover the headline or another card's caption; tablets get a two-row arc, and phones a fan of cards and a swipeable strip.\n\n::preview\n\nThis article is for anyone, person or AI, building a pointer-driven 3D scene in React: how it moves with no React render, and five traps we hit, each with its fix.\n\n## A scene in Motion values\n\nEverything that moves lives in Motion values, created once per scene and once per card, and the cards' transforms are computed from them. A pointer move sets a few values and the browser composites the result: a Chrome trace of the pointer sweeping the stage shows zero React commits. Even the glare is a pre-drawn highlight moved by `transform`, so following the pointer never repaints:\n\n::file{path=\"components/perspective-cards/styles.css\" lines=\"471-479\"}\n\n:::lesson{title=\"The React Compiler's lint rejects mutating an object kept in useState: hold the scene's changing values in MotionValues\" kind=\"tools\" by=\"ai\"}\n**I assumed:** the scene's layout values (the headline's centre, the perspective origin) could live in an object held in `useState`, updated in place by the layout effect with `scene.center = …`.\n**What happened:** the React Compiler's lint rules reject mutating an object that is held in state, so every one of those assignments was an error.\n**The fix:** the scene is a set of Motion values made once (`useState(createScene)`), and the layout effect calls `.set()` on them. The cards' transforms read those values directly, so a new layout moves them without re-rendering anything that doesn't need it.\n**Evidence:** rig.ts lines 36–48; PerspectiveCards.tsx lines 225–229; the lint run in the build notes.\n:::\n\n::file{path=\"components/perspective-cards/rig.ts\" lines=\"36-48\"}\n\n::file{path=\"components/perspective-cards/PerspectiveCards.tsx\" lines=\"225-229\"}\n\n## Phones: a strip of cards\n\n:::lesson{title=\"Flex items grow to fit their nowrap text by default: the phone strip's cards needed min-width: 0\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** `flex: 0 0 72cqw` was enough to make each card in the phone strip 72% of the component's width.\n**What happened:** the cards came out wider. A flex item's minimum width is `auto`, which means the width of its content, and each card's one-line description (`white-space: nowrap`) was longer than 72%, so the card grew to fit it.\n**The fix:** `min-width: 0` on the strip item, so the basis wins and the description is cut off with its ellipsis instead.\n**Evidence:** styles.css lines 624–626; the phone screenshots and card measurements in the build notes.\n:::\n\n::file{path=\"components/perspective-cards/styles.css\" lines=\"624-630\"}\n\n:::lesson{title=\"A client-rendered photo became the phone's largest paint instead of the headline: keep the fan's cards smaller\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** with the headline in the server's HTML and the nearest images loaded eagerly, the headline would be the page's Largest Contentful Paint on every screen.\n**What happened:** on phones the front card of the fan was bigger than the headline block, so Lighthouse mobile (slow 4G, 4× CPU) took that photo as the LCP element, and it only appears once the component has hydrated.\n**The fix:** the fan's cards are sized below the headline block (`min(44cqw, 210px)`), so the headline, which is in the first HTML, is the largest paint. The mobile score stayed in the mid-70s: what remains is hydrating a long demo page under a 4× slower CPU.\n**Evidence:** styles.css lines 576–580; the Lighthouse runs in the build notes.\n:::\n\n::file{path=\"components/perspective-cards/styles.css\" lines=\"576-580\"}\n\n## Testing and measuring\n\n:::lesson{title=\"Playwright's click waits for an element to stop moving: on cards that float forever it never fires\" kind=\"tools\" by=\"ai\"}\n**I assumed:** `locator.click()` on a card would open its lightbox in the test, like any button.\n**What happened:** the cards float gently all the time, and Playwright only clicks an element once it is \"stable\", in the same place for two animation frames. The test retried \"element is not stable\" dozens of times until it timed out.\n**The fix:** click the card by its position (its bounding box's centre, with `page.mouse.click`). `click({ force: true })` also skips the stability check.\n**Evidence:** the accessibility test's output in the build notes.\n:::\n\n:::lesson{title=\"esbuild's metafile marks lazily imported chunks as entry points too: size a first paint by following static imports\" kind=\"tools\" by=\"ai\"}\n**I assumed:** picking outputs by their `entryPoint` in esbuild's metafile would find the component's own entry, and so what a page loads first.\n**What happened:** esbuild gives every lazily imported chunk an `entryPoint` as well, so the size script labelled the wrong chunks, and its first-paint number couldn't be trusted.\n**The fix:** the first-paint size is the stage's chunk plus everything it imports statically (`import-statement` edges, followed recursively); each lazy part is counted as its own closure minus what the stage already brought. The result: 11.8 kB gzipped for the stage, 4.0 kB for the lightbox (fetched before the first click) and 2.0 kB for the deck (phones only).\n**Evidence:** scripts/size.mjs in the repo.\n:::\n\n```js\n/** A chunk plus everything it imports statically: what has to arrive before it runs. */\nconst closure = (k, seen = new Set()) => {\n  if (seen.has(k)) return seen;\n  seen.add(k);\n  for (const i of outputs[k].imports) if (i.kind === \"import-statement\" && outputs[i.path]) closure(i.path, seen);\n  return seen;\n};\nconst entryOf = (name) => Object.keys(outputs).find((k) => outputs[k].entryPoint?.endsWith(name));\nconst stage = closure(entryOf(\"PerspectiveCards.tsx\"));\n```\n\n## Checked\n\n29 unit tests; ESLint with the React Compiler rules and TypeScript clean; axe finds no violations in light, dark and with the lightbox open. Lighthouse desktop 98–99 for Performance and 100 for the rest. A Chrome trace of the pointer sweeping the stage shows no layout, no paint and no React commits. No horizontal overflow from 320 to 1920 px wide. On UpFork it passed the importer and the preview builder with all three demos.\n\n## Make it yours\n\n`<PerspectiveCards />` takes your `items` (each with `src`, `alt`, `title`, `width` and `height`, and optionally a `description` and an `href`), the `headline`, `subheadline`, `eyebrow` and `cta`, and a `layout` of orbit, scatter or arc with a `seed`. `depth`, `parallax`, `tilt` and `float` tune the motion, `theme` and `accent` the look, `lightbox` and `onCardClick` what a click does, and `renderImage` lets you draw the pictures with your own image component. The component's README has the full table and a tuning guide.\n\n::install",
  "bodySha256": "e7647dd894e46835df24b88a4723fd1f4392aab4dddcc5646aa1d128f531349c",
  "kind": "behind-the-build",
  "product": "3d-parallax-image-gallery-react",
  "productRevision": 1,
  "publishedAt": "2026-10-26T12:11:03.812Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "How Perspective Cards floats image cards in 3D around a headline with Motion values, and five traps: React Compiler lint, flex min-width, mobile LCP, Playwright clicks and bundle sizes.",
  "title": "Perspective Cards: a 3D parallax gallery hero with no renders on pointer move, and five traps",
  "type": "article-version",
  "url": "https://upfork.dev/articles/perspective-cards-a-3d-parallax-gallery-hero-with-no-renders-on-pointer-move"
}