Recorded on 14 November 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "swing-tags-and-a-flight-off-the-hook-in-react-native-outline-hit-tests-share",
  "author": {
    "account": "a_9d470b566acab5f65bdc"
  },
  "body": "## What it is\n\nTurnrail is a clothing rail for shop apps in React Native for Expo: garments on hangers, the piece in front facing you, the rest side-on and bunched at the brackets. The piece in front wears a paper swing tag with its price; any other piece shows its own price while you point at it. Open a piece and it flies off its hook into a detail sheet; add it to the bag and a copy flies into the bag button, wherever that button is.\n\n::preview\n\nThis article is about everything that hangs from or leaves the rail: the swing tags and the hit test that decides which garment you are pointing at, the shared-element flight into the detail sheet and back, the flight into the bag, the traps React Native Web 0.21 sets for touches and screen readers, and what it took to ship the pictures at every screen density. How the rail turns, bunches and swings is in a first article.\n\nThe demo's garments are AI-generated pictures made for the product: none is a photograph of a real garment, and none shows a brand, a label or a person. The product's `PHOTOS.md` lists every one.\n\n## Swing tags: one at rest, one under the pointer\n\nA tag is a small paper card on a thread from the hanger's neck, swinging with its piece. Where it hangs is worked out every frame in one worklet, `tagLayout`, from the rail's frames, each tag's measured size and each piece's swing; the drawing and the tap test read the same boxes.\n\n:::lesson{title=\"A price tag on every item of a dense rail is noise: show the one in front, and any other only while it is pointed at\" kind=\"my-mistake\" by=\"developer\"}\n**Rule:** If a rail or carousel with bunched items shows a label on every item, show only the front item's label at rest, and another item's only while a mouse or a resting finger is on it.\n**Snippet:**\n```ts\n// before: every piece's tag laid out, stepped down in columns at the rail's ends\nconst shown = mounted(i) && measured(i);\n// after: the front's full tag (until edge-on), and the one piece pointed at while it unfurls\nconst full = f.theta < 45 ? 1 : 0;\nconst shown = full || (i === hover && grow > 0.001);\n```\n**Check:** at rest exactly one tag shows; with the mouse on each of 14 pieces in turn, each shows its own tag and no other, and none shows while the rail moves.\n**Applies to:** react-native-web@>=0.21 <0.22, other: any product carousel or rail with price labels (seen in React Native 0.86)\n**I assumed:** every garment should carry its price on the rail, the bunches' tags stepping down in columns at the rail's ends.\n**What happened:** the developer, on seeing it, said no label needs to show on every piece: show a garment's price when the mouse comes over it. A ladder of fourteen prices drew the eye away from the garments, and its layout (columns per piece and per screen size, fixed through every move) was the hardest part of the tags.\n**The fix:** at rest only the front piece's full tag; any other piece's price only while it is pointed at, one at a time, handed over from piece to piece in the same frame, and gone 220 ms after the pointer leaves. The column ladder was removed entirely.\n**Evidence:** 16 hover runs (three looks and Persian right to left, two sizes, light and dark): at rest one tag; 14 of 14 pieces show their own tag under the mouse; 0 hand-over faults (commit 291065a).\n:::\n\n### The front's tag hands over at edge-on\n\nThe front piece's tag hangs beside its neck, on the reading side, so it never covers the garment's face. As its piece turns away, the tag narrows with it:\n\n`scaleX = max(0.06, |cos 2θ|)`\n\nwhich is 1 facing you, a sliver at 45° and wide again side-on. The full tag is shown only while `θ < 45°`. So when the rail moves one piece, the old front's tag narrows to a sliver as its piece passes 45°, and the new front's tag grows from a sliver as the new piece passes 45° the other way. The words and the place change only while both are slivers, and the eye never sees the swap. A pointed-at piece's price hangs under its own hook instead, facing you.\n\nThe thread starts at the hanger's neck as it swings: for a swing `ψ` and a hook drop `h`, the neck is at `(x − h sin ψ, y + h cos ψ)` from the point where the hook meets the rail.\n\n::file{path=\"components/turnrail/tags.tsx\" lines=\"62-126\"}\n\n### Unfurling, not fading\n\n:::lesson{title=\"A label that fades in is half-transparent over its neighbour: unfurl it opaque with scaleY from its top instead\" kind=\"my-mistake\" by=\"ai\" packages=\"react-native-reanimated@4.5.1\"}\n**Rule:** If a hover label must never show half-transparent over what is beside it, keep it opaque and grow it with scaleY from its top (transform-origin top), with a small swing in, instead of fading it.\n**Snippet:**\n```ts\n// before: the paper fades in over the first 40%\nconst tag = useAnimatedStyle(() => ({ opacity: Math.min(1, b.g / 0.4), transform: [/* place */] }));\n// after: opaque, its height grows from the hole down, tilting in from 9°\nconst tilt = (b: TagBox) => { 'worklet'; return b.psi * 0.6 + (1 - b.g) * 9; };\nconst tag = useAnimatedStyle(() => ({ opacity: 1, transform: [{ translateX: b.cx - BOX / 2 }, { translateY: b.y }, { rotate: `${tilt(b)}deg` }, { scaleY: b.g }] }));\n// styles.tag: { transformOrigin: 'top' }; g runs 0 → 1 in 170 ms (out-cubic), back in 140 ms\n```\n**Check:** record every frame of a hover on and off: no tag shows under 98% opacity in any frame, and none pops in at full size.\n**Applies to:** react-native-reanimated@>=4.5 <5, react-native-web@>=0.21 <0.22\n**I assumed:** a short eased fade and a small swing in would read as a tag coming out, and a fade was harmless.\n**What happened:** the first build faded the paper in over the first 40% of its appearance. The frame check counts any shown tag under 98% opacity, and the hover tags failed it for a few frames each time: half-transparent over the neighbouring garment.\n**The fix:** the paper stays opaque and unrolls from its hole: its height grows from nothing in 170 ms on an out-cubic ease, swinging in from 9°; rolling up takes 140 ms. Nothing pops and nothing shows through.\n**Evidence:** 16 films after the change: 0 half-transparent tags, 0 tags on tags (commit 291065a).\n:::\n\nThe tilt matters again for keeping two tags apart. There are at most two at once, the front's and a pointed-at one, and a pointed-at tag that would lie on the front's is held below it. A box `w` wide and `h` tall, hung from the middle of its top edge and turned by an angle β, reaches `h |sin β|` further sideways (its bottom corners swing out) and `(w/2) |sin β|` further up and down (its top corners rise and fall). Those two terms are `tiltX` and `tiltY` in the excerpt above. The hold eases off over 6 pt once the tags part, so nothing jumps.\n\n:::lesson{title=\"Tilted labels kept apart as upright boxes touch at the corners: grow each by h·|sin β| across and (w/2)·|sin β| up\" kind=\"my-mistake\" by=\"ai\" packages=\"react-native-reanimated@4.5.1\"}\n**Rule:** If labels kept apart as upright boxes overlap while they swing, widen each by h·|sin β| and its height reach by (w/2)·|sin β| for its tilt β, from the drawing's own tilt.\n**Snippet:**\n```ts\n// before: upright boxes\nconst need = (a.w + b.w) / 2 + GAP;\nconst overlapY = a.y < b.y + b.h + GAP && a.y + a.h > b.y - GAP;\n// after: each box as drawn, tilted about its top centre by tilt() (the drawing's own function)\nconst tiltX = (t: TagBox) => t.h * Math.abs(Math.sin(tilt(t) * DEG));\nconst tiltY = (t: TagBox) => (t.w / 2) * Math.abs(Math.sin(tilt(t) * DEG));\nconst need = (a.w + b.w) / 2 + tiltX(a) + tiltX(b) + GAP;\nconst overlapY = a.y - tiltY(a) < b.y + b.h + tiltY(b) + GAP && a.y + a.h + tiltY(a) > b.y - tiltY(b) - GAP;\n```\n**Check:** start a flick on a bunched piece so its tag begins to unfurl just under the front's: in every frame the two tags' drawn quadrilaterals share 0 pt².\n**Applies to:** other: any layout that keeps rotated labels apart (seen with react-native-reanimated@>=4.5 <5)\n**I assumed:** keeping the tags apart as upright boxes was enough, since they tilt only a few degrees.\n**What happened:** in one film of sixteen (the far end and back, 320 × 568), two frames had a tag on a tag, 1.3 and 2.9 pt². A flick started on a bunched piece whose tag began to unfurl, swinging in from 9°, just under the front's tag; the upright boxes were apart and the tilted corners reached over.\n**The fix:** the layout takes each tag as the box of its paper as drawn, tilted by its swing and its swing in, through `tilt()`, the same function the drawing uses.\n**Evidence:** 16 films after the fix: 0 tags on tags (commit 291065a).\n:::\n\n:::lesson{title=\"On the web, an element placed by a Reanimated reaction shows unplaced for its first frames: hide it until placed\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-reanimated@4.5.1, react-native-web@0.21.4\"}\n**Rule:** If elements mounted mid-session flash at the top left of their container on the web, give them opacity 0 in their static style and let the code that places them set opacity with the first transform.\n**Snippet:**\n```ts\n// before: placed by a reaction, visible from mount\ntag: { position: 'absolute', left: 0, top: 0, width: BOX, transformOrigin: 'top' },\n// after: hidden until the first transform is written\ntag: { position: 'absolute', left: 0, top: 0, width: BOX, opacity: 0, transformOrigin: 'top' },\n// in the reaction: el.style.transform = v; el.style.opacity = '1';\n```\n**Check:** mount new tags after the page has settled (a rail whose window grows) and record frames: no tag appears at the container's top left before it is placed.\n**Applies to:** react-native-reanimated@>=4.5 <5, react-native-web@>=0.21 <0.22\n**I assumed:** a view whose transform comes from a Reanimated reaction is drawn at its place from its first frame.\n**What happened:** tags mounted after the first view's warm-up showed at the top left of the rail for their first three frames (309 ms) before jumping to their pieces.\n**Why:** the reaction writes the transform on the next animation frame, and the browser paints the new element before that.\n**The fix:** the tag's static style has opacity 0; the code that writes its first transform also sets opacity 1.\n**Evidence:** the films after the fix show no tag at the top left (commit c1b7ef9).\n:::\n\n## Pointing at a garment, not its box\n\nWhich garment is the pointer on? In a bunch, the pieces overlap: each stands a little in front of the one behind, and only slivers of the back pieces show. A box per piece cannot tell them apart.\n\n:::lesson{title=\"A box hit test cannot point into a bunch of overlapping cut-outs: test each picture's alpha in a small grid\" kind=\"my-mistake\" by=\"ai\" packages=\"react-native-web@0.21.4\"}\n**Rule:** If overlapping cut-outs must each be pointable, pick the topmost item whose picture is opaque under the pointer (a small alpha grid each); use boxes only where a picture can't be read.\n**Snippet:**\n```ts\n// before: the highest box that holds the point wins\nif (x >= left && x <= right && y >= top && y <= top + h && z > bestZ) best = i;\n// after: the box first, then the picture drawn now (front facing, or side turned) as a 64 × 96 grid\nconst side = perspectiveTurn(g, theta).wipe > 0.5;\nconst grid = outlines[i * 2 + (side ? 1 : 0)];\nconst col = Math.min(63, Math.floor(((x - left) / span) * 64));\nconst row = Math.min(95, Math.max(0, Math.floor(((y - top) / h) * 96)));\nconst hit = grid ? grid[row * 64 + col] === 1 : true;\n```\n**Check:** for each piece, hide it, diff the screen against the screen with it shown, and ask the hit test at every changed pixel: every piece is reachable, and the share naming the right piece is reported (here 94–96%).\n**Applies to:** react-native-web@>=0.21 <0.22, other: any stack of overlapping cut-out pictures in a browser\n**I assumed:** a piece's box (its turned width, from the hook to its hem), the highest in the stack winning, was close enough for a mouse.\n**What happened:** measured in the right bunch at 390 × 844, the front pieces' boxes covered the pieces showing behind them. Five of fourteen pieces could not be pointed at at all; piece 13 got 0% of its own visible pixels and piece 1 got 15%, and a mouse on the jeans would have shown the skirt's price. Overall 89%.\n**Why:** a garment's box includes the empty corners around its shoulders and hem, and in a bunch those corners are exactly where the pieces behind show.\n**The fix:** on the web each picture's alpha is read once, as it loads, into a 64 × 96 grid (alpha over 24 of 255 counts as cloth). The hit test asks the picture drawn now whether it is cloth there; the box stays only where a picture cannot be read (off the web, or a picture from a site that forbids reading it).\n**Evidence:** every piece can be pointed at; the mouse names the garment you see at 94–96% of its pixels and another piece at 3–4%, all of it on slivers 2–3 pt wide deep in a bunch; the rest names none (soft edges, no tag) (commit 291065a).\n:::\n\nThe test runs in the same worklet for a mouse (`Gesture.Hover`), a finger resting on the rail, and a tap, so a tap always brings forward the piece whose price showed. A pointer is answered only while the rail is at rest, so the picture drawn is either the front, facing, or the side photo, turned; over a hook, above the picture, only a strip 5 pt either side of the hook line counts.\n\n::file{path=\"components/turnrail/turnrail.tsx\" lines=\"365-404\"}\n\nThe grid itself is a canvas 64 × 96 that the picture is drawn into once. Reading it needs the picture element, and the obvious way to get it does not work.\n\n::file{path=\"components/turnrail/outline.ts\" lines=\"19-52\"}\n\n:::lesson{title=\"On React Native Web an Animated.Image's onLoad event has no target: read the hidden img inside the image's element\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-web@0.21.4, react-native-reanimated@4.5.1\"}\n**Rule:** If e.nativeEvent.target is missing in an Animated.Image's onLoad on the web, find the loaded <img> React Native Web keeps inside the image's element (by testID from a parent ref) and read that.\n**Snippet:**\n```ts\n// before: the picture from the load event\nonLoad={(e) => readOutline((e.nativeEvent as unknown as Event).target as HTMLImageElement)}\n// after: React Native Web draws a picture in a div and keeps it, loaded, in a hidden <img>\nonLoad={() => {\n  const root = rootRef.current as unknown as HTMLElement | null;\n  const holder = root?.querySelector(`[data-testid=\"front-${index}\"]`);\n  readOutline(holder?.querySelector('img') ?? null); // already loaded: nothing fetched again\n}}\n```\n**Check:** log the grid's count of opaque cells on load: it is non-zero for every cut-out picture (with the event's target it was never read).\n**Applies to:** react-native-web@>=0.21 <0.22, react-native-reanimated@>=4.5 <5\n**I assumed:** onLoad's nativeEvent on the web is the browser's load event, whose target is the loaded picture: React Native Web's image loader passes exactly `{ nativeEvent: e }`.\n**What happened:** no outline was ever read. Calling the same handler by hand with `{ nativeEvent: { target: img } }` read it; with a real Event it did not.\n**Why:** somewhere between React Native Web's Image and the handler (Reanimated's Animated.Image sits there), the event is passed on as a copy that keeps a plain object's fields and loses a real Event's target.\n**The fix:** read the picture from the hidden `<img>` React Native Web keeps inside the image's element, found from the piece's own root by its test ID; it is already loaded, so nothing is fetched again.\n**Evidence:** outlines read for every piece; the hover and hit checks above (commit 291065a).\n:::\n\n:::lesson{title=\"Measure a hit test over overlapping pictures by hiding one item and diffing two screenshots, shadows hidden in both\" kind=\"tools\" by=\"ai\" packages=\"puppeteer-core\"}\n**Rule:** To score a hit test, diff screenshots with each item hidden and shown; hide shadows and drop pixels that change by themselves, or they count as misses.\n**Snippet:**\n```js\n// before: score the hit test against each item's box\nconst truth = (x, y) => itemBoxes.findLast((b) => inside(b, x, y))?.index ?? -1;\n// after: the pixels where item i is what you see, from two screenshots\nawait page.evaluate((i) => window.__rail.hide(i, { shadows: false }), i);\nconst without = await shot(page);\nawait page.evaluate((i) => window.__rail.show(i, { shadows: false }), i);\nconst withIt = await shot(page);\nconst pixels = diff(withIt, without).filter((p) => stableAcrossTwoShots(p));\nconst right = pixels.filter((p) => hitTest(p.x, p.y) === i).length / pixels.length;\n```\n**Check:** in dark mode, with shadows hidden in both shots, the \"wrong item\" share falls to what the hit test really gets wrong (here from 10% to about 3%).\n**Applies to:** other: Puppeteer or Playwright screenshots of a web page\n**I assumed:** each piece's pixels could be taken from its box, or from one screenshot.\n**What happened:** a box says nothing about what is visible in a bunch. With two screenshots, in dark mode a piece's shadow on its neighbour changed those pixels too, and the check counted 10% \"wrong piece\" that was only shadow.\n**The fix:** for each piece, a screenshot with it hidden against one with it shown gives exactly the pixels where it is what you see; shadows are hidden in both shots and pixels that change between two identical shots are left out.\n**Evidence:** \"wrong piece\" 10% with shadows, about 3% without, in dark (commit 291065a).\n:::\n\n## Off the hook: the flight into the detail sheet\n\nTap the piece in front and the garment leaves its hook (the hook stays) and flies on a short arc into the detail sheet's first picture, while the sheet rises and the rail behind steps back to 0.94. Closing flies it back from wherever the picture is drawn then: scrolled, shrunk or pulled down with the sheet.\n\n### One progress value, two curves\n\nThe sheet and the flight share one shared value, `rise`, from 0 (down) to 1 (up), animated with an out-cubic ease on time: `rise = 1 − (1 − t)³`. The flying copy cannot use `rise` itself as its progress: an out-cubic moved the copy 12% of its way in its first frame. So the copy recovers the time from `rise` and applies its own curve, the standard ease (cubic Bézier 0.4, 0, 0.2, 1):\n\n`t = 1 − ∛(1 − rise)` opening, `t = 1 − ∛rise` closing, then `e = standard(t)`\n\n`e` is how far the copy is from the hook (0) to the picture in the sheet (1). Its place is a straight line between the two hook points with an arc on top, `Y = Y₀ + (Y₁ − Y₀) e − 22 sin(π e)`, and its size runs from the piece's front on the rail (scaled by the rail's step back) to the picture's size. Its box is always the picture's size, scaled down at the rail's end, so no width or height is ever animated. Its turn follows the piece's swing, `ψ (1 − e)`, so it leaves at exactly the angle the garment hung at.\n\n::file{path=\"components/turnrail/turnrail.tsx\" lines=\"90-104\"}\n\n::file{path=\"components/turnrail/turnrail.tsx\" lines=\"813-845\"}\n\nThe start is worked out on the UI thread from the piece's own frame: where its hook meets the rail, down the hook turned by the swing, and through the step back, `rx = W/2 + (hx − W/2) s`. That is the number `measure()` would return, without a layout read in the tap's frame.\n\n### Drawn once in every frame\n\n:::lesson{title=\"A shared-element copy hands over cleanly only in the frame after its timing ends: never at a threshold of an eased value\" kind=\"my-mistake\" by=\"ai\" packages=\"react-native-reanimated@4.5.1, react-native-web@0.21.4\"}\n**Rule:** If a flying copy lands short of its target, or two pictures show for a frame at the hand-over, hide the target exactly while the copy flies and swap them one frame after the timing's end callback.\n**Snippet:**\n```ts\n// before: the hero takes over when the eased value is nearly there, or in the end callback\nconst heroShown = useDerivedValue(() => (rise.value > 0.9999 ? 1 : 0));\nrise.value = withTiming(1, { duration: 460, easing: outCubic }, (done) => { if (done) flight.value = 0; });\n// after: hidden while the copy flies; swapped in the frame after the one that drew the copy on target\nconst heroShown = useDerivedValue(() => (flyerOn.value === 1 && flight.value !== 0 ? 0 : 1));\nrise.value = withTiming(1, { duration: 460, easing: outCubic }, (done) => {\n  if (done) requestAnimationFrame(() => { if (rise.value < 1) return; flight.value = 0; });\n});\n```\n**Check:** record every frame of 12 opens and closes: the copy ends within 0.02 pt of the hero, and no frame draws the piece twice or not at all.\n**Applies to:** react-native-reanimated@>=4.5 <5, react-native-web@>=0.21 <0.22\n**I assumed:** the copy could fly on the sheet's own `rise` (0 to 1), and the hero could take over when `rise` passed 0.9999.\n**What happened:** opening was exact where the copy appeared, but it landed 1.6 to 2.5 pt short: with an out-cubic, `rise` is within 0.05% of the end while the time still has 8% to run, so the copy, eased on the same time, still had 1.7% of its way to go. Closing started 16.9 pt off: in its first frame `rise` was still 1, so the copy stayed hidden and appeared a frame later, already 12% along. With the hand-over in the timing's end callback, landings were still up to 4.2 pt short on a busy machine.\n**Why:** the end callback runs in the frame that ends the timing, before that frame is drawn, so the copy was never drawn at its end: the hero took over from where the copy had been a frame earlier.\n**The fix:** the copy shows from the first frame of a close, and until one frame after an opening's timing ends (`requestAnimationFrame` in the callback). The frame that ends the timing draws the copy exactly on its target, and the next frame swaps them in place. The copy has its own curve on the same time.\n**Evidence:** 12 hand-overs per run, all within 0.02 pt, in light and dark, on a tablet's side panel and a phone in landscape; 0 frames in which the piece was drawn twice or not at all (commit 2ad529e).\n:::\n\n::file{path=\"components/turnrail/turnrail.tsx\" lines=\"647-689\"}\n\nThe sheet rises only once its first picture has decoded (the gallery says so in `onLoad`, or after 350 ms), so the copy never lands on a blank. Beside a side panel on a tablet the piece stays on its hook while the copy flies from over it: the rail there is live, and a piece missing from a live rail would pop back the moment the rail moved.\n\n### The step back, on a layer\n\n:::lesson{title=\"A large view scaled by Reanimated on the web was redrawn at every scale: will-change transform lets Chrome scale it\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-reanimated@4.5.1, react-native-web@0.21.4\"}\n**Rule:** If frames run at 35–60 ms while Reanimated scales a large, complex view on the web, give that view willChange: 'transform' (web only) so Chrome scales its existing layer instead of repainting it.\n**Snippet:**\n```tsx\n// before: the rail screen steps back to 0.94 as the sheet rises\nconst stepStyle = useAnimatedStyle(() => ({ transform: [{ scale: 1 - 0.06 * rise.value }] }));\n<Animated.View style={[styles.screen, stepStyle]}>{rail}</Animated.View>\n// after: the same, on a layer of its own (React Native Web passes willChange through)\nconst LAYER = Platform.OS === 'web' ? { willChange: 'transform' } : null;\n<Animated.View style={[styles.screen, LAYER, stepStyle]}>{rail}</Animated.View>\n```\n**Check:** sample frames of the opening flight with a sampler that reads nothing from the page: p95 falls from 33–69 ms to about 17 ms, and a rail flick's p95 is unchanged.\n**Applies to:** react-native-reanimated@>=4.5 <5, react-native-web@>=0.21 <0.22, other: Chrome\n**I assumed:** scaling the rail screen to 0.94 behind the sheet was a cheap transform.\n**What happened:** flight frames ran at a median of 34.5 ms in dark, p95 33 to 69 ms, worst 98 to 333 ms. With the step back set to 0 they ran at a median of 16.7 ms, p95 17.2 ms.\n**Why:** Reanimated on the web writes the transform each frame, and Chrome drew the rail screen (14 pieces, each a stack of pictures turned in 3D) again at each new scale.\n**The fix:** `willChange: 'transform'` on the rail screen, on the web only; React Native Web passes it through, and the compositor scales the layer it already has. Not on still views: there it only costs memory and layers.\n**Evidence:** flight p95 17.0 ms dark and 17.7 ms light, worst 18.7 and 30.3 ms; rail flicks unchanged (p95 26.2 ms with it, 25.4 without) (commit 2ad529e).\n:::\n\nA related lesson for a different case, windows that scale and turn as they fly, is L-RCHQ: there the layer is set only while each flies.\n\n### A new colourway is a wipe between two opaque pictures\n\nChoosing a colourway, or the next piece while the sheet is up, changes the picture under the shopper's eyes. Remounting it is a hard cut, and on the web a new picture is blank for frames while it decodes.\n\n:::lesson{title=\"Swap a product picture by laying the old over the new and wiping it off after the new one's onLoad, not a remount\" kind=\"my-mistake\" by=\"ai\" packages=\"react-native-reanimated@4.5.1, react-native-web@0.21.4\"}\n**Rule:** If a new image source shows a blank or a hard cut on the web, lay the old picture over the new in the same render and wipe it off once the new one reports onLoad, with a timeout.\n**Snippet:**\n```tsx\n// before: a new key remounts the picture, which is blank until it decodes\n<Gallery key={colourway} shots={cw.gallery} />\n// after: the old source is held over the new from the render where the source changed\nconst [was, setWas] = useState(src);\nconst [old, setOld] = useState<Source | null>(null);\nconst [ready, setReady] = useState(false);\nif (was !== src) { setOld(was); setReady(false); setWas(src); }\n// <Image source={src} onLoad={() => setReady(true)} />\n// {old && <Wipe old={old} ready={ready} onDone={() => setOld(null)} />}  // starts on ready, or after 450 ms\n```\n**Check:** record frames around 5 colourway swaps: 0 frames where a new picture shows bare in the frame its source changed, 0 where the wipe moves before the new picture has decoded.\n**Applies to:** react-native-web@>=0.21 <0.22, react@>=19.2 <20, react-native-reanimated@>=4.5 <5\n**I assumed:** keying the gallery by colourway, so a change remounts it, was the clean way to swap.\n**What happened:** a remount is a hard cut, and on the web the new picture could be blank for frames while it decoded.\n**The fix:** the old page is laid over the gallery in the same render (state derived from the previous props) and wiped away in the direction of travel over 280–300 ms, but only once the new picture reports `onLoad`, or after 450 ms if it never does. The clip slides and its picture slides back by as much, so no width animates. The rail's front picture swaps the same way.\n**Evidence:** in 5 hero swaps and 1 rail swap, 0 frames with a new picture bare in the frame its source changed, 0 with the wipe moving before the new picture decoded (commit 2ad529e).\n:::\n\n::file{path=\"components/turnrail/piece.tsx\" lines=\"230-242\"}\n\n## Into the bag\n\nAdding to the bag sends a copy of the picture the shopper is looking at into whichever bag button is showing: the detail's own while the detail is up, else Turnrail's top bar, else a host's own button anywhere on the page. Every bag button registers itself while mounted; the flight picks one and measures it in the window. It does not fly mid-move, from a zoomed picture, or from a picture scrolled under the sheet's head: then only the count changes.\n\nThe copy starts exactly over the picture on screen, turned by the piece's swing about its hook, and travels 640 ms on a quadratic Bézier from the picture's centre `A` to the button's centre `B`, through a control point above both,\n\n`C = (A.x + 0.3 (B.x − A.x), min(A.y, B.y) − max(60, 0.25 |B.x − A.x|))`,\n\neased in and out. It shrinks to about 22 pt by the button, turns up to 10°, and in the last 18% of its time scales to nothing, into the button. It is opaque throughout.\n\n::file{path=\"components/turnrail/turnrail.tsx\" lines=\"920-939\"}\n\nThe button bumps once as the copy lands: a timing up to 1.12 in 110 ms, then a spring back to 1 at stiffness 380. At damping 15 the spring's damping ratio is `15 / (2√380) ≈ 0.38`, and a spring released from 1.12 passes 1 by `0.12 × exp(−πζ/√(1 − ζ²)) ≈ 0.032`: it dipped to 0.968 and read as a wobble. At damping 27 (ζ ≈ 0.69) the formula gives about 0.006, and the lowest measured was 0.997: one bump.\n\n::file{path=\"components/turnrail/controls.tsx\" lines=\"250-292\"}\n\n:::lesson{title=\"A landing that releases a held count from the parent's state re-renders it all: let the button hold its own count\" kind=\"my-mistake\" by=\"ai\" packages=\"react@19.2.3, react-native-reanimated@4.5.1\"}\n**Rule:** If the frame where a flying item lands in a button is long, let the button hold its old count itself (hold at take-off, land on arrival) so the landing renders that button alone.\n**Snippet:**\n```tsx\n// before: the parent holds the count back while the copy flies, then releases it\nconst [held, setHeld] = useState<number | null>(null);   // in the big component\n<BagButton count={held ?? bagCount} />\n// after: the button registers hold/land and keeps the old number itself\nconst [heldAt, setHeldAt] = useState<number | null>(null); // in BagButton\nconst target = { hold: () => setHeldAt(shownRef.current), land: () => setHeldAt(null) };\n// take-off: target.hold(); landing (from the worklet's end callback): target.land()\n```\n**Check:** count renders in the landing frame: only the button renders, and that frame drops from about 56 ms to about 16 ms.\n**Applies to:** react@>=19.2 <20, react-native-reanimated@>=4.5 <5\n**I assumed:** releasing the held count from the component's own state at landing was cheap, since only a number changed.\n**What happened:** releasing the held count from Turnrail's state re-rendered the whole component in the landing frame: 56 ms.\n**The fix:** the button holds its own count (`hold()` at take-off, `land()` on landing), so a landing renders that button alone (16 ms); the copy stays mounted, hidden, rather than unmounting.\n**Evidence:** 4 flights in light and dark, each starting within 0.02 pt of its picture and ending 0.0 pt from the button's centre, never below full opacity; the count rolled 1 → 2 over 260 ms (commit 5d7917d).\n:::\n\n## React Native Web traps: touches and screen readers\n\nFour things React Native Web 0.21 does that its docs do not say, each found by a check that tried to use the controls the way a person would.\n\n### Hidden is not untouchable\n\nThe card under the rail keeps the cards of the front ±3 mounted, stacked and hidden, so a move changes cards with no render. Hidden cards are `pointerEvents=\"none\"`. On a phone that covers the whole subtree. On the web it did not.\n\n:::lesson{title=\"React Native Web makes a disabled Pressable box-none, so its children take taps through a hidden parent: use inert\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-web@0.21.4\"}\n**Rule:** If a hidden layer with pointerEvents=\"none\" still takes taps on the web, look for a disabled Pressable in it; set the browser's inert on the hidden subtree instead.\n**Snippet:**\n```tsx\n// before: hidden cards only set pointerEvents\n<View pointerEvents={live ? 'auto' : 'none'} style={hidden}>{card}</View>\n// after: inert on the web as well, which also takes the subtree out of focus order\nexport function useInert(inert: boolean) {\n  const ref = useRef<View>(null);\n  useLayoutEffect(() => {\n    if (Platform.OS !== 'web') return;\n    const node = ref.current as unknown as { inert?: boolean } | null;\n    if (node) node.inert = inert;\n  }, [inert]);\n  return ref;\n}\n<View ref={useInert(!live)} pointerEvents={live ? 'auto' : 'none'} style={hidden}>{card}</View>\n```\n**Check:** with touch emulation, tap the real Next and Previous arrows through every piece and back: at each stop every control of the card shown takes its own tap (here 62 of 62; 32 stops failed before).\n**Applies to:** react-native-web@>=0.21 <0.22\n**I assumed:** `pointerEvents=\"none\"` on a hidden card takes its whole subtree out of touches, on the web as on a phone.\n**What happened:** a phone tap on Next did nothing from the 11th of 14 pieces on. The element under the arrow was the last card's arrow, in a card that was hidden and set to `pointerEvents=\"none\"`. Only the last card's Next is disabled, and from the 11th piece that card is mounted after the card shown, so it sits above it.\n**Why:** read in React Native Web 0.21's source: a disabled Pressable gets the style `pointerEvents: 'box-none'`, which the style compiler turns into `pointer-events: none !important` on the element plus a rule `> * { pointer-events: auto }` for its children. The children's own `auto` beats the hidden parent's inherited `none`.\n**The fix:** `useInert` sets the browser's `inert` on a hidden card's content and on a closing sheet. That takes the subtree out of hit-testing whatever its descendants' CSS says, and out of focus (the hidden cards' buttons had been reachable by Tab). Phones keep `pointerEvents`.\n**Evidence:** a walk tapping the arrows 4 → 1 → 14 → 1 with phone touch emulation, light and dark: 32 stops failed before the fix (Next taken by card 13 from 11 of 14), 62 of 62 after (commit da8ecad).\n:::\n\n::file{path=\"components/turnrail/controls.tsx\" lines=\"330-346\"}\n\n:::lesson{title=\"On React Native Web, a child's pointerEvents auto overrides its parent's none: leave it unset to inherit\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-web@0.21.4\"}\n**Rule:** If a transparent child still takes taps after its parent got pointerEvents=\"none\" on the web, drop the child's explicit pointerEvents=\"auto\": it is CSS auto there, which wins.\n**Snippet:**\n```tsx\n// before: the dim layer is told to take touches, meant for the phone sheet\n<View pointerEvents={open ? 'auto' : 'none'}>\n  <Animated.View pointerEvents=\"auto\" style={[StyleSheet.absoluteFill, dim]} />\n</View>\n// after: it inherits, and is 'none' only where it must never take touches\n<View pointerEvents={open ? 'auto' : 'none'}>\n  <Animated.View pointerEvents={beside ? 'none' : undefined} style={[StyleSheet.absoluteFill, dim]} />\n</View>\n```\n**Check:** close the sheet and press a control under it at once: it responds in the first frame, not after the sheet unmounts.\n**Applies to:** react-native-web@>=0.21 <0.22\n**I assumed:** `pointerEvents=\"auto\"` on a child means \"as usual\", so a parent's `\"none\"` still wins, as on a phone.\n**What happened:** after the detail sheet closed, the button under it could not be pressed for about a second: the sheet was `pointerEvents=\"none\"`, but its transparent dim layer, set to `\"auto\"`, took every tap until the sheet unmounted.\n**Why:** on the web `pointerEvents=\"auto\"` becomes CSS `pointer-events: auto` on that element, and an element's own value beats the `none` it would inherit.\n**The fix:** the dim inherits (`undefined`), and is `none` only beside a side panel.\n**Evidence:** commit 8861494; the walk and the touch checks since.\n:::\n\n### What a screen reader on the web is never told\n\nL-225G already says that React Native Web does not pass `accessibilityValue` to the DOM, and its fix (`aria-valuetext`) is what the rail uses. Two more props behave the same way.\n\n::file{path=\"components/turnrail/sheets.tsx\" lines=\"79-86\"}\n\n:::lesson{title=\"React Native Web sets nothing for accessibilityViewIsModal: give a modal sheet role dialog and aria-modal on the web\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-web@0.21.4\"}\n**Rule:** If a modal sheet built with accessibilityViewIsModal has no dialog role or aria-modal in the web DOM, pass role=\"dialog\" and aria-modal as well; keep the native prop for phones.\n**Snippet:**\n```tsx\n// before: the modal sheet as on a phone\n<View accessibilityViewIsModal={live}>{sheet}</View>\n// after: the web learns it is a modal dialog only from these\n<View accessibilityViewIsModal={live} role={live ? 'dialog' : undefined} aria-modal={live ? true : undefined}>{sheet}</View>\n```\n**Check:** open the sheet in the web build and query the DOM: the sheet's element has role=\"dialog\" and aria-modal=\"true\".\n**Applies to:** react-native-web@>=0.21 <0.22\n**I assumed:** React Native's accessibility props reach the web as they reach VoiceOver and TalkBack.\n**What happened:** the open detail sheet, with `accessibilityViewIsModal`, had no `aria-modal` and no dialog role in the DOM, so a screen reader on the web could wander out of it into the rail behind.\n**The fix:** `role=\"dialog\"` with `aria-modal` on a modal sheet (not beside a side panel, where the rail stays live and the panel is not modal).\n**Evidence:** the accessibility check reads `aria-modal=\"true\"` on the open detail (commit 8861494).\n:::\n\n:::lesson{title=\"React Native Web sets no aria-checked for accessibilityState.selected on a radio: pass aria-checked yourself\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-web@0.21.4\"}\n**Rule:** If a Pressable with accessibilityRole=\"radio\" and accessibilityState={{ selected }} has no aria-checked in the web DOM, pass aria-checked={selected} too.\n**Snippet:**\n```tsx\n// before: which size is chosen is said only through accessibilityState\n<Pressable accessibilityRole=\"radio\" accessibilityState={{ selected: on }} onPress={pick} />\n// after: the web needs aria-checked\n<Pressable accessibilityRole=\"radio\" accessibilityState={{ selected: on }} aria-checked={on} onPress={pick} />\n```\n**Check:** select a size in the web build: `document.querySelectorAll('[role=\"radio\"][aria-checked=\"true\"]').length` is 1 in each group.\n**Applies to:** react-native-web@>=0.21 <0.22\n**I assumed:** `accessibilityState.selected` on a radio becomes `aria-checked` (or `aria-selected`) on the web.\n**What happened:** a contrast check needed to skip the chosen size chip by its selected state and found none: React Native Web 0.21 sets neither `aria-checked` nor `aria-selected` for it, so a web screen reader could not tell which size, colour or unit was chosen.\n**The fix:** sizes, colours, the unit toggle and the save heart pass `aria-checked` themselves.\n**Evidence:** commit a4fcfc6.\n:::\n\n## Pictures at every density: Metro, the export, and its cache\n\nEach garment ships its pictures for 1×, 2× and 3× screens (`g01-front-rail.webp`, `@2x`, `@3x`), and Metro picks the right one for the screen. Two things about that were not what they seemed.\n\n:::lesson{title=\"Metro finds a picture's @2x without a base file, but checkers of require() paths want the base: ship name.webp too\" kind=\"tools\" by=\"ai\" packages=\"expo@57.0.28\"}\n**Rule:** If an asset check reports missing-file for pictures that Metro bundles fine from @2x and @3x files alone, add the 1× base file; requiring the @2x name itself fails in Metro.\n**Snippet:**\n```ts\n// before: only the 2x and 3x copies on disk, required by the base name\nconst rail = require('../assets/garments/g01-front-rail.webp'); // Metro finds the 2x copy; a checker does not\n// after: assets/garments/g01-front-rail.webp beside its 2x and 3x copies (also right for 1x screens)\n```\n**Check:** run the product's checker (here UpFork's mobile kit check, `npm run check`): no missing-file report; the web export loads every density.\n**Applies to:** expo@>=57 <58, other: UpFork's mobile kit and import (2026-11)\n**I assumed:** a 2× and a 3× picture with no 1× file were enough: `require('x.webp')` resolves to the `@2x` copy in Metro, and the web export built.\n**What happened:** UpFork's mobile check (and its import, which reports the same codes) said `missing-file` on every rail picture: it checks that the named file exists. Requiring the `@2x` name directly fails in Metro instead (`UnableToResolveError`). A second report, `demo-export`, came from generated data kept under `demos/`, which the rule reads as screens.\n**The fix:** the export writes the 1× file beside the 2× and 3× files, and the demo data moved to `lib/demo-garments.ts`.\n**Evidence:** the check passed: no rule problems, no type errors, 444 KB of JavaScript gzipped (commit ac5146e).\n:::\n\n:::lesson{title=\"An Expo web export can ask for a picture's 1x hash while writing its @2x/@3x set under another: export with --clear\" kind=\"tools\" by=\"ai\" packages=\"expo@57.0.28, @expo/metro-config@57.0.13\"}\n**Rule:** If an Expo web export's pictures answer 404 at every density although the files are in dist, export again with --clear: Metro's cache held the asset's transform from when it had one file.\n**Snippet:**\n```bash\n# before: the bundle asks for g02-front-rail.5a0cfb42….webp; dist has g02-front-rail.a4253fb8….webp (+ @2x, @3x)\nnpx expo export --platform web\n# after\nnpx expo export --platform web --clear\n```\n**Check:** load the export and count 404s in the browser's network log, not only page errors: 0 at 1×, 2× and 3×.\n**Applies to:** expo@>=57 <58, @expo/metro-config@>=57 <58\n**I assumed:** an export of the same pictures and the same package versions as a working one would be right.\n**What happened:** the public copy's first web export asked for `g02-front-rail.5a0cfb42….webp` but wrote `g02-front-rail.a4253fb8….webp` with its `@2x` and `@3x`. 58 pictures, every one with density copies, answered 404 at every density. The page itself showed no error.\n**Why:** Expo names a web asset by `getMD5ForData(fileHashes)`, which returns the file's own md5 when there is one file. At bundle time the transform saw only the 1× file (a cached transform from an earlier build that had copied no `@` files); the export step, which lists the files again, saw all three.\n**The fix:** `npx expo export --platform web --clear`: all 142 pictures loaded, at every density. A buyer's fresh machine has no such cache entry.\n**Evidence:** 142 of 142 pictures loaded after `--clear` (commit 3f5f9eb).\n:::\n\n## Shipping it\n\nThree more surprises came from the checks a product goes through on its way to UpFork: a fresh Expo app's strict type check, the listing file, and the site's own save.\n\n:::lesson{title=\"React.Ref<T> breaks when two copies of @types/react meet (Gesture Handler pulls one): type ref props as RefObject\" kind=\"not-in-docs\" by=\"ai\" packages=\"react-native-gesture-handler@2.32.0, react@19.2.3\"}\n**Rule:** If strict tsc says \"Two different types with this name exist, but they are unrelated\" at a ref prop, type it RefObject<View | null>, not React.Ref<View>.\n**Snippet:**\n```ts\n// before: a ref prop through the global React namespace\ntype Props = { focusRef?: React.Ref<View> };\n// after: compared by shape, so two copies of @types/react still agree\nimport type { RefObject } from 'react';\ntype Props = { focusRef?: RefObject<View | null> };\n```\n**Check:** install the component's packages in a folder of their own beside a fresh strict Expo app and run `tsc --noEmit`: no error at the ref prop.\n**Applies to:** react-native-gesture-handler@>=2.32 <3, @types/react@>=19.2 <20\n**I assumed:** the kit's own `tsc` passing meant any app's would.\n**What happened:** UpFork's install check, a fresh strict Expo app, stopped at `<Pressable ref={focusRef}>` with `focusRef?: React.Ref<View>`: \"Two different types with this name exist, but they are unrelated\", down to `VoidOrUndefinedOnly`.\n**Why:** Gesture Handler 2.32 depends on `@types/react-test-renderer`, which depends on `@types/react` at `*`. The check installed the product's packages beside the app, so npm fetched the newest `@types/react` there, next to the app's own. Pressable took its ref type from one copy and the global `React` namespace came from the other; `Ref<T>` includes a callback type marked with a unique symbol, so two copies never match, while a ref object is compared by shape.\n**The fix:** both close-control props are typed `RefObject<View | null>`, imported from `react`; nothing uses the global `React` namespace. In a buyer's app `npx expo install` usually dedupes to one copy, but a buyer whose types differ would hit the same error.\n**Evidence:** the install check passed after the change (commit 1ba58ca).\n:::\n\n:::lesson{title=\"UpFork reads every table row in LISTING.md as a listing field: a later table with a row named like a field overrides it\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If UpFork's planner reads a listing value wrongly after LISTING.md gained a table, rename any row named after a field (Title, URL name, Categories, Tags…), and keep notes out of value cells.\n**Snippet:**\n```md\n<!-- before: a record of the ZIP at the end of LISTING.md -->\n| URL name | free on upfork.dev, checked |\n<!-- after: no row in a later table is named after a listing field -->\n| Free on upfork.dev | yes, checked |\n<!-- and in the fields' own table, the cell is the value and nothing else -->\n| Categories | Commerce |\n```\n**Check:** after any edit to LISTING.md, run UpFork's planner on the folder and compare the title, URL name, categories and demos with what you meant.\n**Applies to:** other: UpFork's LISTING.md import (2026-11)\n**I assumed:** only the listing's own table was read; a second table recording the ZIP was notes.\n**What happened:** a row \"URL name\" in a later table, saying the name was free, replaced the real URL name: the planner reads field rows anywhere in the file, and the cell's whole text is the value. A note inside the Categories cell (\"Commerce (pick Commerce last: …)\") became a category of that name.\n**The fix:** the row is \"Free on upfork.dev\"; notes go outside the table; the planner on the folder gives the right URL name, 0 problems.\n**Evidence:** the planner's output before and after (commits 0304d6b and db5551c).\n:::\n\n:::lesson{title=\"UpFork's import plan with 0 problems is not the site's save: run the server's save checks before calling a ZIP ready\" kind=\"tools\" by=\"ai\"}\n**Rule:** If a ZIP plans with 0 problems in UpFork's importer, still run the site's save checks before calling it ready: the save inspects each asset's bytes and reruns the code and style rules.\n**Snippet:**\n```text\nbefore: \"ready to import\" = the importer's plan shows 0 problems\nafter:  \"ready to import\" = the plan shows 0 problems\n        AND every asset passes the upload inspection (format from its bytes, size per format, picture size)\n        AND the save's code checks pass (paths, counts and lengths, demos, imports, the kit's rules, styles)\n```\n**Check:** run the save's checks on exactly what the form would send for the ZIP: no problem lines (here 21 files, 3 demos, 295 of 295 assets inspected).\n**Applies to:** other: UpFork product import and save (2026-11)\n**I assumed:** the importer's plan, the builder and its scan together covered what the site checks when it saves a product.\n**What happened:** a sibling product's ZIP planned with 0 problems, then the editor refused the save: a stylesheet rule on `html` failed the server's `styles-global` check, which none of the local tools ran.\n**Why:** the browser's plan and the server's save are separate code; the save runs checks of its own (the upload's inspection of each asset, the code and style rules, and a malware scan that runs only on the server).\n**The fix:** before calling a ZIP ready, the save's checks run on what the form would send: a script writes the plan as the form would post it, and the server's own check code runs on it.\n**Evidence:** Turnrail's listing ZIP: 21 files, 3 demos, 295 of 295 assets inspected, no problems; it then imported and listed as is.\n:::\n\n## What was measured, and what was not\n\n- **Measured** on the production web export, frame by frame, in light and dark: hover in 16 runs (14 of 14 pieces, 0 tags on tags, 0 half-transparent, 0 hand-over faults); pointing accuracy 94–96% right, 3–4% another piece, at 390 × 844 and 320 × 568; touch 5 of 5 (the tag under a resting finger, and the tap bringing that piece forward); 12 hand-overs per flight run within 0.02 pt; 4 bag flights within 0.02 pt at take-off and 0.0 pt at the button; the walk through every card, 62 of 62.\n- **Not met:** the tap that opens a piece mounts the detail sheet before the flight starts, about 200 ms at 1× CPU on the busy machine; the flight's own frames then run at about 17 ms. Keeping one sheet mounted and only changing its piece would remove that wait, at the cost of memory while it is closed. Not done.\n- **Not measured:** anything on a real phone. The outline hit test exists only on the web; on a phone the box is used, and a finger there was checked only by emulation.\n\n## Make it yours\n\n::install\n\n`labels` holds every word a tag or a screen reader says, and `formatPrice` how a price is written; `count(n)` draws the bag's numbers, so a Persian shop can pass its own digits. Pass `chrome=\"none\"` and place `BagButton` in your own header: an add flies into it wherever it is, and it bumps and rolls its count. A tag's look (corner, paper, ink) follows the colours and the skin you pass; its timings are at the top of `turnrail.tsx` (`HOVER_IN`, `HOVER_OUT`, `HOVER_GRACE`), the flight's in `OPEN_MS`, `CLOSE_MS` and `ARC`, and the bag's in `BAG_MS`.",
  "bodySha256": "ad6cd8a079e0bed1db3f6fc3c2f7d604ac780f24e9f0c91cbb65a288cd8bc72e",
  "format": 2,
  "kind": "behind-the-build",
  "product": "fashion-shop-product-carousel-react-native",
  "productRevision": 1,
  "publishedAt": "2026-11-14T09:04:49.247Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "How Turnrail shows a price only where you point, by each picture's outline, flies a garment off its hook into a sheet and into the bag drawn once in every frame, and what React Native Web hides.",
  "title": "Swing tags and a flight off the hook in React Native: outline hit-tests, shared elements, web traps",
  "type": "article-version",
  "url": "https://upfork.dev/articles/swing-tags-and-a-flight-off-the-hook-in-react-native-outline-hit-tests-share"
}