Recorded on 6 November 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "a-camera-that-walks-up-to-a-shoe-springs-buying-inside-a-3d-room-and-a-wall",
  "author": {
    "account": "a_9d470b566acab5f65bdc"
  },
  "body": "## What this one is about\n\nFloodlit is a 3D night showroom for a small range of sports shoes: pairs on clear acrylic shelves against a plaster wall, each shelf lit by a strip in its shoe's own colour. The first article covered how the room is drawn. This one covers how it moves and how it sells: one camera that walks up to a shoe, along the wall and back, springs that never snap, a panel for buying that belongs to the room, a wall that is real HTML placed by CSS alone, phones, right to left, and access.\n\n::preview\n\nEverything here is in world units that are CSS pixels at the rest camera, with x to the right, y down and z towards the viewer. The shoes stand on the plane z = 24. A point on that plane appears on screen at `W/2 + (x − camera.x) × k + shiftX × W/2`, where `k = f / (camera.z − 24)` and `f` is the focal length. `shiftX` and `shiftY` are a lens shift: they slide the picture without turning the camera. The demo's ten shoes are five real photographs and five AI-generated images, listed in the product's `PHOTOS.md`.\n\n## The walk up: anchored on the shoe\n\nThe obvious way to walk a camera up to something is to ease its position and its distance from start to end. That makes the shoe swing across the screen on a curve: the same sideways move of the camera shifts the picture far more when it is close than when it is far, so the shoe drifts one way early and the other way late.\n\nSo the path is anchored on the shoe instead. Take a point on the shoe, a little above its slab. Work out where it is on screen now (`s0`) and where it must be at the end (`s1`). Then, at each moment `u` from 0 to 1:\n\n- the shoe's screen position moves in a straight line: `s(u) = s0 + (s1 − s0) × e(u)`, where `e` is the easing curve, plus a small rise of −14 px × sin(π·e) so it lifts a little on the way;\n- the distance eases in log space: `ln D(u) = ln D0 + (ln D1 − ln D0) × e(u)`, because equal steps in `ln D` look like equal steps of zoom;\n- the camera is solved from those two: `camera.x = anchor.x − (s.x − W/2 − shiftX·W/2) / k`, with `k = f / D(u)`.\n\nNear the end the distance goes a hair past its target and comes back, by 1.2% of the log distance travelled, shaped by `sin(π × (u − 0.7)/0.3)`. That settle is what makes the stop feel like a person stopping, not a crane. The walk up runs 1230 ms after a 60 ms delay, and the panel is told it may enter at u = 0.55, when the path to it is clear.\n\n::file{path=\"components/floodlit/room.ts\" lines=\"138-166\"}\n\n::file{path=\"components/floodlit/room.ts\" lines=\"307-340\"}\n\nWalking along to the next shoe is simpler, because the distance hardly changes: position and lens shift ease together over 700 ms, and the log distance gets a bump of 0.06 × sin(π·e), a small step back in the middle, the way you lean back to look along a wall. Back to the wall is the same anchored path in reverse, with a gentler curve (0.42, 0, 0.2, 1), a smaller rise and no settle.\n\nClosing has the opposite timing to get right. The wall's own HTML, its heading, names and prices, comes back on the way home:\n\n:::lesson{title=\"Walking back, the wall's words came back at once over the wrong shoes: wait until the camera is nearly home\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If HTML labels sit over a 3D view that moves, show them again only when the view is nearly where they belong; let the walk back say when (here its mark at u = 0.82).\n**Snippet:**\n```tsx\nimport { useEffect, useState } from \"react\";\ndeclare function whileVisible(ms: number, then: () => void): () => void;\n\n// before: the wall's words faded back on close, over 0.22 s, with the camera still close in\nexport function useWordsWaitForHome(room: { close: () => void }) {\n  const [returning, setReturning] = useState(false);\n  const close = () => {\n    setReturning(true);\n    room.close(); // the room's walk back calls onHome at u = 0.82 of its 840 ms\n  };\n  const onHome = () => setReturning(false); // passed to the room's events\n  // If the word never comes: whileVisible, from the lesson on the panel's cue below, counts only while visible.\n  useEffect(() => (returning ? whileVisible(1500, () => setReturning(false)) : undefined), [returning]);\n  return { returning, close, onHome }; // <div className=\"fl-body\" data-return={returning || undefined}>\n}\n```\n```css\n.fl-body[data-focus] .fl-plane,\n.fl-body[data-return] .fl-plane {\n  opacity: 0;\n}\n```\n**Check:** take screenshots back to back after closing: the names first show once the camera is home (at about 0.8 s here), not over a camera still close in.\n**Applies to:** other: HTML labels over a moving 3D view\n**I assumed:** words that fade in over 0.22 s would arrive with the room.\n**What happened:** frames from the middle of the walk back showed the names at their rest places while the camera was still close in, so a name sat under the wrong shoe for about half a second.\n**The fix:** a `home` event from the room, and the words wait for it.\n**Evidence:** commit 6fc7667; `scripts/qa/motion-sweep.mjs`, the close stills.\n:::\n\n:::lesson{title=\"A walk-up curve with a long slow start read as lag: check a filmstrip, not only the arrival time\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a click-started camera move shows almost no motion in its first 300 ms on a filmstrip, raise the start of its curve, as from (0.5, 0, 0.14, 1) to (0.36, 0.04, 0.16, 1), and keep the duration.\n**Snippet:**\n```ts\n// A cubic bezier from (0,0) to (1,1), as CSS cubic-bezier(), sampled once into a table.\nfunction sampledEase(x1: number, y1: number, x2: number, y2: number, n = 96) {\n  const bez = (t: number, a: number, b: number) => 3 * (1 - t) * (1 - t) * t * a + 3 * (1 - t) * t * t * b + t * t * t;\n  const table = new Float32Array(n + 1);\n  for (let i = 0; i <= n; i++) {\n    let lo = 0, hi = 1;\n    for (let k = 0; k < 24; k++) { const t = (lo + hi) / 2; if (bez(t, x1, x2) < i / n) lo = t; else hi = t; }\n    table[i] = bez((lo + hi) / 2, y1, y2);\n  }\n  return (u: number) => {\n    const p = Math.min(1, Math.max(0, u)) * n, i = Math.min(n - 1, Math.floor(p));\n    return table[i] + (table[i + 1] - table[i]) * (p - i);\n  };\n}\n// before: sampledEase(0.5, 0, 0.14, 1)\nconst walkEase = sampledEase(0.36, 0.04, 0.16, 1);\n// The walk up: u = (msSinceClick - 60) / 1230\n```\n**Check:** print the eased progress 300 ms after the click with `walkEase`: 18% (the old curve gives 8%). Then take a filmstrip of the real walk: the camera has moved in the first 100 ms (by 84 ms here; nothing had for 400 ms before).\n**Applies to:** other: eased camera or interface moves started by a click\n**I assumed:** a slow start would read as the weight of a real camera.\n**What happened:** a filmstrip showed almost nothing moving for 400 ms after the click, while the strip was already lit. It read as lag, not weight. The arrival time alone hid it.\n**The fix:** (0.36, 0.04, 0.16, 1). The filmstrip showed the camera moving by 84 ms, with the same arrival.\n**Evidence:** commit 3a3a4b5.\n:::\n\n## Springs that never snap\n\nEvery value that moves (the camera's five numbers, the room's dim, each strip's level, the bag) is a spring, `{ x, v }`, stepped with its exact solution rather than a numerical one, so a slow frame cannot make it unstable. A critically damped spring with angular frequency ω reaches its target with no overshoot:\n\n`e = exp(−ω·dt)`, `tmp = (v + ω·(x − target))·dt`, `x' = target + (x − target + tmp)·e`, `v' = (v − ω·tmp)·e`\n\nThe strips use an under-damped spring, a lamp coming up rather than a value arriving: ω 17 and ζ 0.84. Computed from the spring itself, for a step from rest, that peaks 0.77% over and reaches 95% at 213 ms. The first choice, ω 26 and ζ 0.8, peaked at 1.5% and read as a flash on light.\n\n::file{path=\"components/floodlit/spring.ts\" lines=\"6-26\"}\n\nThe camera does not follow its path directly. The path sets a goal, and the camera's five numbers chase it with critical springs at ω 34, stiff enough to look like the path, soft enough to absorb what a new command does to it. A new command (a click on another shoe in mid-walk, Esc, an arrow key) starts a new path from the camera's present pose.\n\n:::lesson{title=\"Carrying only the speed into a new camera path still braked: carry the spring's lead as well\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a spring-driven camera brakes hard when a new command starts a new path, carry both its velocity and the spring's lead over the pose into the new goal, fading over about 170 ms.\n**Snippet:**\n```ts\ntype Spring = { x: number; v: number };\nconst CARRY_SECONDS = 0.17;\n\n// Exact critically damped step.\nfunction critical(s: Spring, target: number, omega: number, dt: number) {\n  const e = Math.exp(-omega * dt);\n  const delta = s.x - target;\n  const tmp = (s.v + omega * delta) * dt;\n  s.x = target + (delta + tmp) * e;\n  s.v = (s.v - omega * tmp) * e;\n}\n\n// One axis; the room does the same for x, y, log distance and both lens shifts. path(u) is the walk's own curve.\n// before: no carry, then the velocity alone ({ v: pose.v, lead: 0 }); the new path starts at the pose either way.\nlet carry = { t0: 0, v: 0, lead: 0 };\nfunction startPath(pose: Spring, goal: number, now: number) {\n  carry = { t0: now, v: pose.v, lead: goal - pose.x };\n}\nfunction goalAt(pathValue: number, now: number) {\n  const tau = Math.max(0, now - carry.t0) / 1000;\n  const e = Math.exp(-tau / CARRY_SECONDS);\n  return pathValue + carry.v * tau * e + carry.lead * e; // at tau = 0 the goal has not moved at all\n}\n// each frame: critical(pose, goalAt(path(u), now), 34, dt), where path: (u: number) => number\n```\n**Check:** record the camera's screen speed every frame through six quick commands and take the largest change between two frames: it must be several times smaller than with no carry (about 4 px here, against 19.9 px with no carry and 15 px with the speed alone).\n**Applies to:** other: spring-smoothed paths that can be interrupted\n**I assumed:** a new path that started from where the camera was, with no jump in position, would feel continuous.\n**What happened:** position never jumped, yet it hit like a wall: a slow-starting path means the camera stops dead first. Carrying the speed helped, and it still braked, because a spring trails its goal, and restarting from the present pose pulled the goal back behind where it was heading.\n**The fix:** carry both. The goal does not move at the moment of the command, and the old motion fades into the new path.\n**Evidence:** commit 3a3a4b5; `room.ts` lines 180-202.\n:::\n\n::file{path=\"components/floodlit/room.ts\" lines=\"180-202\"}\n\nWalks are timed against the clock, which brings one more case: a frame that comes very late.\n\n:::lesson{title=\"A walk timed against the clock jumps to its end after a hidden tab: push its start forward by the gap\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If an animation is timed against the clock, push its start forward by any frame gap over about 120 ms, so a hidden tab or a long stall pauses it instead of jumping it to the end.\n**Snippet:**\n```ts\ntype Path = { t0: number; delay: number; duration: number };\nlet path: Path | null = null;\nlet carryT0 = 0; // when the carried speed began to fade (the lesson above)\nlet lastT = 0;\n\n// before: no gap handling, so u = (t - t0 - delay) / duration was 1 on the first frame back\nfunction frame(t: number) {\n  const dtMs = lastT ? t - lastT : 16.7;\n  lastT = t;\n  if (dtMs > 120) {\n    const paused = dtMs - 16.7; // keep one ordinary frame of progress\n    if (path) path.t0 += paused;\n    carryT0 += paused;\n  }\n  const u = path ? Math.min(1, Math.max(0, (t - path.t0 - path.delay) / path.duration)) : 1;\n  // draw at u; springs step with dt = min(dtMs, 50) / 1000\n}\n```\n**Check:** start a walk, hide the tab for two seconds and show it: log `u` on the last frame before and the first frame after. They differ by about one frame's progress (0.014 of a 1230 ms walk), not by the time hidden.\n**Applies to:** other: requestAnimationFrame animations timed against the clock\n**I assumed:** a walk that always lands where it should needed nothing for a stall.\n**What happened:** found while making the room stop drawing in a hidden tab: the first frame back would have been the walk's last, a jump across the whole wall.\n**The fix:** push the path's start, and the carry's, forward by the gap. The same line makes a stalled frame stretch the walk rather than teleport it.\n**Evidence:** commit 0481bb3; `room.ts` lines 689-697.\n:::\n\n## Looking around without turning a photograph\n\nThe shoes are flat photographs. A camera that turned, or moved sideways without compensation, would show the card at an angle it was never photographed from. So when the pointer moves, the camera moves sideways by up to `tan(1.5°) × distance`, and the lens shift moves the picture back by exactly as much on the shoes' plane: `shiftX += 2·dx·k / W`. Points on z = 24 stay put. The wall at z = 0 and the slab's front at z = 48 move against it, which is the parallax that says \"room\". Measured between looking far right and far left, the shoe changed by 0.7 levels on average and the slab band by 9.1.\n\n::file{path=\"components/floodlit/room.ts\" lines=\"630-656\"}\n\nHover brings the shelf's strip up on its spring. The torch, a small point light that follows the pointer at a short distance from the wall, rakes across the plaster and moves the shadows a little. With reduced motion there is no walk and no torch; states crossfade, and light still answers hover.\n\n## The wall is HTML, placed by CSS alone\n\nUnder the canvas the wall is a `<ul>` of real `<a href>` links, each with the shoe's picture, name and price, in the server's markup. Crawlers, middle-click, screen readers and a browser with JavaScript off need no WebGL. The first paint is those pictures, and the canvas fades in over them. For that to work the pictures must already stand exactly where the room will draw the shoes, before any script runs.\n\n:::lesson{title=\"A poster wall placed through the camera in React was empty without script: make the 3D plane 1:1 with CSS\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If HTML cards must line up with a WebGL perspective scene before any script runs, put the rest camera at z = f + planeZ, so that plane is 1:1 with CSS pixels, and lay the cards out in plain CSS.\n**Snippet:**\n```tsx\n// before (P3): placed in React through the camera, hidden until the first effect had run\n// let cardStyle: React.CSSProperties = { visibility: \"hidden\" };\n// if (slot && pose) { const [x0, y0] = screenAt(pose, W, H, slot.card.x, slot.card.y, SHOE_Z); ... }\n\n// after: the rest camera at the focal length from the shoes' plane, so k = f / (z - SHOE_Z) = 1 there.\nconst restZ = (f: number) => f + SHOE_Z;\n// Each card gets its column and row per breakpoint as CSS variables, in the server's markup.\nfunction slotVars(index: number, count: number, columnsFor: (width: number, count: number) => number) {\n  const out: Record<string, number> = {};\n  for (const [name, width] of [[\"lg\", 1100], [\"md\", 700], [\"sm\", 320]] as const) {\n    const cols = columnsFor(width, count);\n    const rows = Math.ceil(count / cols);\n    const row = Math.floor(index / cols);\n    const inRow = row === rows - 1 ? count - cols * (rows - 1) : cols;\n    out[`--c-${name}`] = index - row * cols;\n    out[`--r-${name}`] = row;\n    out[`--o-${name}`] = (cols - inRow) / 2; // a short last row is centred\n  }\n  return out;\n}\n```\n```css\n.fl-card {\n  position: absolute;\n  left: calc(var(--left) + (var(--col) + var(--off)) * (var(--w) + var(--gap)));\n  top: calc(var(--first) + var(--row) * var(--pitch) - var(--w) / var(--aspect) * var(--baseline));\n  width: var(--w);\n}\n```\n**Check:** compare the server's posters with the canvas by edge correlation on several views: the largest offset was 1 px here, on 7 views, against 2 px allowed. With JavaScript off, the wall and its links are there.\n**Applies to:** other: HTML overlays that must match a WebGL perspective camera\n**I assumed:** the cards could be placed by the room's own maths in React.\n**What happened:** they were hidden until the first effect, so the server's markup had no wall at all, and without JavaScript there were no shoes. The rest camera sat at an arbitrary distance, so the positions needed the camera's maths, which CSS cannot run.\n**The fix:** the 1:1 rest camera, and the same layout written in `cqw` and `calc`. A window too short for the wall steps back: the camera moves to `f × step + 24` and the HTML plane gets `scale(1/step)` about its centre, which is the same maths.\n**Evidence:** commit badceaf; the hydration and jump checks.\n:::\n\nThe layout is the same sums as the room's `layout.ts`, written once in TypeScript and once in CSS on the component's own container. A container cannot query itself, so the container is `.fl-root` and everything hangs off its child `.fl-body`:\n\n::file{path=\"components/floodlit/floodlit.css\" lines=\"23-69\"}\n\n::file{path=\"components/floodlit/floodlit.tsx\" lines=\"64-79\"}\n\nFor right to left, the markup mirrors the column (`inRow − 1 − col`) and CSS still places by `left` alone. Writing `left` and `inset-inline-start` together on the same card would look fine in LTR, where they are one property and the later wins, and lose in RTL, where the second is `right` and an over-constrained box keeps `right`.\n\nWithout WebGL, or after a lost context, the same posters stay, and the shoe in focus shows as a flat picture on a drawn shelf. The shelf's `top` comes from the picture's own `baseline`, because each picture stands at a different height in its frame; a shelf at a fixed 73% of the stage cut straight through one sole.\n\nThe posters and the room's textures are the same pictures, so they should be the same files:\n\n:::lesson{title=\"Poster and texture in two sizes fetched every shoe twice: let the room read the poster's currentSrc\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If an `<img>` poster and a WebGL texture show one picture, load the texture from the poster's `currentSrc`, with `sizes` one pixel past the small file so a desktop poster takes the texture's file.\n**Snippet:**\n```tsx\n// before: sizes=\"(min-width: 1100px) 20vw, (min-width: 700px) 25vw, 50vw\" chose the 480 file on a desktop,\n// while the room fetched the 960 for its texture: two downloads of every shoe.\n<img\n  ref={(el) => { posters.current[i] = el; }}\n  className=\"fl-poster\"\n  src={shoe.photo.src}          // the 960 file\n  srcSet={shoe.photo.srcSet}    // \"...-480.webp 480w, ...-960.webp 960w\"\n  sizes=\"(min-width: 700px) 481px, 50vw\" // 481, one past the small file, so a 1x desktop still takes the 960\n  alt={shoe.photo.alt}\n/>\n// The room's texture: whichever file the poster chose.\nconst texture = posters.current[i]?.currentSrc || shoe.photo.src;\n```\n**Check:** list the first view's picture requests at 1440×900: each shoe's file appears once, and the total is under budget (863 KB here, against 900).\n**Applies to:** other: pages that show one image as an img and as a WebGL texture\n**I assumed:** small posters and larger textures were the lighter choice.\n**What happened:** every shoe was fetched twice, and with the wall maps on top the first view came to 1028 KB against 900 allowed.\n**The fix:** one file for both; on a phone both are the 480. A separate change, the wall maps re-encoded from their sources at a lower quality, brought the total to 863 KB.\n**Evidence:** commit 0481bb3.\n:::\n\n## Buying inside the room\n\nIn focus, the shoe stands to one side and a panel stands beside it: series, name, price, a short description, size tiles with a unit switch, an add-to-bag pill, and the returns note. Arrow keys and two buttons walk along to the neighbours. The panel is not a modal laid over the room. It enters when the walk is 55% through, once the zone it will stand in is clear (the room calls `onPanelClear`), so it never slides in over shelves that are still fading. If that cue never comes, it comes in anyway after 1.8 s: a view with nothing to press is worse than a panel over a shoe still settling.\n\n:::lesson{title=\"A walk cut short by a new layout never gave the panel its cue: a cancelled path must still run its marks\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If an animation path fires a one-off cue partway (show the panel at 55%), run any cue it has not run yet when the path is cancelled, and give the cue a timed fallback.\n**Snippet:**\n```ts\ntype Mark = { u: number; done: boolean; run: () => void };\ntype Path = { t0: number; duration: number; at: (u: number) => number; mark?: Mark };\nlet path: Path | null = null;\n\n// The room, when the layout changes (a dragged window, a turned phone, a scrollbar that went).\nfunction onLayoutChanged() {\n  // before: path = null, and the panel's mark at u = 0.55 never ran\n  if (path?.mark && !path.mark.done) {\n    path.mark.done = true;\n    path.mark.run();\n  }\n  path = null; // the springs carry the camera to the new frame\n}\n```\n```ts\n// The page: if the cue never comes, the panel comes anyway, after 1.8 s of the page being visible.\nfunction whileVisible(ms: number, then: () => void): () => void {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const arm = () => {\n    clearTimeout(timer);\n    if (document.visibilityState !== \"hidden\") timer = setTimeout(then, ms);\n  };\n  arm();\n  document.addEventListener(\"visibilitychange\", arm);\n  return () => { clearTimeout(timer); document.removeEventListener(\"visibilitychange\", arm); };\n}\n// useEffect(() => (focusIndex >= 0 && !panelShown ? whileVisible(1800, () => setPanelShown(true)) : undefined), [focusIndex, panelShown]);\n```\n**Check:** resize the frame 200 ms into a walk up (390 to 420 px here): the panel shows before the 1.8 s fallback could have shown it (at 476 ms here). Before the fix it never showed.\n**Applies to:** other: animations that fire cues partway and can be cancelled\n**I assumed:** a walk always reaches its marks, because only a new command ends it.\n**What happened:** `setLayout` ended the walk with `path = null` before u = 0.55. The camera still arrived, carried by its springs, so the screen looked settled, and the panel waited for a cue that was gone.\n**The fix:** a path cut short runs its unrun mark at once, and the page has a 1.8 s safety net for the cue. That net's first version was a plain `setTimeout`, and the hidden-tab check caught it bringing the panel in while the walk was paused in a hidden tab: it now counts only while the page is visible.\n**Evidence:** commit 6fc7667; `scripts/qa/site-frame.mjs`, the resized case.\n:::\n\n### Size tiles\n\nThe tiles are a radio group. Choosing a size remembers it, so the next shoe opens with the same size chosen when it is in stock, and only three or fewer left shows \"only N left\". Pressing Add with no size chosen is not an error: a hint asks for a size, the tiles give a small pulse, the shoe's strip pulses with them, and focus moves to the size tiles.\n\n:::lesson{title=\"A key used to replay an animation remounted the size tiles and dropped keyboard focus: use element.animate()\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a React `key` change replays an animation on controls that may hold focus, play it with `element.animate()` instead: a new key remounts the elements and focus falls to the page.\n**Snippet:**\n```tsx\nimport { useEffect, useRef } from \"react\";\n\n// before: <SizeTiles key={pulse} ... /> to replay a CSS pulse, which remounted every tile under the focus\nexport function useNudge(pulse: number) {\n  const group = useRef<HTMLDivElement>(null);\n  useEffect(() => {\n    if (pulse <= 0) return;\n    const a = group.current?.animate(\n      [{ transform: \"none\" }, { transform: \"translate3d(0,-2px,0) scale(1.012)\", offset: 0.4 }, { transform: \"none\" }],\n      { duration: 500, easing: \"cubic-bezier(0.22,0.8,0.24,1)\" },\n    );\n    return () => a?.cancel();\n  }, [pulse]);\n  return group; // <div ref={group} role=\"radiogroup\"> ...tiles... </div>\n}\n```\n**Check:** press Add with no size chosen: focus lands on a size tile and is still there after the pulse (`document.activeElement` is that tile, not `body`).\n**Applies to:** other: React components that replay an animation by changing key\n**I assumed:** a key was the simplest way to replay a CSS animation.\n**What happened:** the click moved focus to a tile, then React remounted the tiles under it and focus fell to the page.\n**The fix:** a one-off `element.animate()`. Nothing in React changes, so nothing loses its place.\n**Evidence:** commit 0951249.\n:::\n\n:::lesson{title=\"A selected size tile ringed in the shoe's colour vanished on the day wall: ring it in the room's own ink\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a selected control's fill comes from product data, draw its border in the theme's fixed ink, not in the product's colour, and check 3:1 against what is behind it in every theme.\n**Snippet:**\n```css\n/* before (P3) */\n.fl-tile[data-on] {\n  background: var(--fl-led);\n  border-color: var(--fl-led);\n  color: var(--fl-led-ink);\n  font-weight: 650;\n}\n/* after: the fill keeps the shoe's colour, the ring is the room's ink */\n.fl-tile[data-on] {\n  background: var(--fl-led);\n  border-color: var(--fl-ink);\n  box-shadow: inset 0 0 0 1px var(--fl-ink);\n  color: var(--fl-led-ink);\n  font-weight: 650;\n}\n```\n**Check:** measure the selected tile's edge against the pixels just outside it, for every shoe in both themes: at least 3:1.\n**Applies to:** other: controls coloured from product data\n**I assumed:** the shoe's colour would always stand out from the plaster.\n**What happened:** the selected tile measured 1.01:1 against the day wall for the lagoon-coloured shoe, and 1.14 for the black one.\n**The fix:** the ring in `--fl-ink`, the fill in the shoe's colour.\n**Evidence:** commit badceaf, the contrast check.\n:::\n\n### The pill\n\nThe pill has a fixed size and six states: needs a size, ready, adding, added, error, and add another. Adding sweeps the shoe's colour across it as a transform, and the label swaps inside a fixed-height mask, so nothing reflows. Its text uses the colour's own ink. During the sweep that ink sits on the room's base on one side and the colour on the other, so a dark colour at night would have been pale text on a pale pill for 300 ms; while adding, the base is set to the opposite of the text's ink (`--fl-pill-base`), and the label reads on both ends of the sweep and on every blend between them.\n\n`onAddToBag` may return a promise. The pill waits at least 500 ms so \"adding\" is never a flicker, a rejected promise shows its message and keeps the size, and the bag is the component's own unless the host controls it.\n\n::file{path=\"components/floodlit/floodlit.tsx\" lines=\"603-648\"}\n\n:::lesson{title=\"Both clicks of a fast double click got past a state check: guard async re-entry with a ref set at once\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If an async action must run once per press, guard it with a ref set synchronously at the top of the handler; a check on state let a second click through here.\n**Snippet:**\n```tsx\nimport { useRef, useState } from \"react\";\n\ntype PillState = \"ready\" | \"adding\" | \"added\" | \"error\";\nexport function useAddOnce(addToBag: () => Promise<void>) {\n  const [pill, setPill] = useState<PillState>(\"ready\");\n  const addingNow = useRef(false);\n  const token = useRef(0); // choosing another size bumps it, so a late answer is ignored\n  const add = async () => {\n    // before: if (pill === \"adding\") return;\n    if (addingNow.current) return;\n    addingNow.current = true;\n    const mine = ++token.current;\n    setPill(\"adding\");\n    try {\n      await addToBag();\n      if (mine === token.current) setPill(\"added\");\n    } catch {\n      if (mine === token.current) setPill(\"error\");\n    } finally {\n      addingNow.current = false;\n    }\n  };\n  return { pill, add };\n}\n```\n**Check:** in a test, double-click the pill with an `onAddToBag` mock that takes 500 ms, and count the calls to the mock: exactly one, and the bag shows a quantity of 1.\n**Applies to:** other: React click handlers that guard async work on state\n**I assumed:** ignoring clicks while the state said \"adding\" would stop a second add.\n**What happened:** both clicks of a double click read the old state. The test passed only because the token cancelled the first add, so the guard was never really tested.\n**The fix:** a ref, set synchronously. State is for what shows.\n**Evidence:** commit 0951249, the buying check.\n:::\n\n:::lesson{title=\"A pill outline in a stretched viewBox went pointed at 1020 px wide: drop the viewBox\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If an SVG pill outline uses `preserveAspectRatio=\"none\"` with rx and ry in viewBox units, its ends distort once it is wider than the viewBox: drop the viewBox and size the rect in percentages.\n**Snippet:**\n```tsx\n// before (P3)\n<svg className=\"fl-pill-line\" aria-hidden=\"true\" preserveAspectRatio=\"none\" viewBox=\"0 0 300 56\">\n  <rect x=\"0.75\" y=\"0.75\" width=\"298.5\" height=\"54.5\" rx=\"27.25\" ry=\"27.25\" vectorEffect=\"non-scaling-stroke\" />\n</svg>\n// after: no viewBox, so rx and ry are real pixels at any width\n<svg className=\"fl-pill-line\" aria-hidden=\"true\">\n  <rect width=\"100%\" height=\"100%\" rx=\"27.25\" ry=\"27.25\" />\n</svg>\n```\n```css\n/* pulled in by half the stroke, so the whole line stays inside the 56 px pill */\n.fl-pill-line {\n  position: absolute;\n  inset: 0.75px;\n  width: calc(100% - 1.5px);\n  height: calc(100% - 1.5px);\n  overflow: visible;\n  fill: none;\n  stroke: var(--fl-line);\n  stroke-width: 1.5;\n}\n```\n**Check:** screenshot the pill at its narrowest and its widest (411 px and 1020 px here): both ends are half-circles of the same radius.\n**Applies to:** other: SVG shapes stretched with preserveAspectRatio none\n**I assumed:** `vector-effect: non-scaling-stroke` would keep the outline true at any width.\n**What happened:** it keeps the stroke's width, not the shape: the radius was in viewBox units, so it stretched with the box. Fine at 411 px, pointed at 1020 px on a 3440 px window.\n**The fix:** no viewBox, percentage sizes, and the svg inset by half the stroke.\n**Evidence:** commit badceaf.\n:::\n\nWhy a pill's border is an SVG stroke at all, rather than a masked ring, is lesson L-941T on this site; the stretched viewBox above is the trap that comes after it.\n\n### The title, the bag, and the host's header\n\nThe shoe's name is set in large type above the panel's side of the room, and it must never touch the shoe or be cut off. Its size comes from a rule, not a breakpoint:\n\n::file{path=\"components/floodlit/floodlit.tsx\" lines=\"650-669\"}\n\n:::lesson{title=\"A title that fit its width still touched a tall shoe: test it against the picture's own opaque pixels\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a heading sits above cut-out images of varying height, don't trust a share of the frame chosen by eye: test its line boxes against each image's alpha at every size, and set the share from that.\n**Snippet:**\n```ts\n// box: the shoe's picture on screen through the focus frame (y0 its top). detailTop: the host's header.\n// before (P3): const roomForHeight = Math.max(36, boxInfo.y0 + (boxInfo.y1 - boxInfo.y0) * 0.14 - detailTop - 92);\nexport function titleSize(box: { y0: number; y1: number }, detailTop: number, viewportH: number,\n  stacked: boolean, forWidth: number, widthAt100px: number) {\n  const titleTop = detailTop + Math.min(28, Math.max(12, viewportH * 0.03)) + 50; // below the back button\n  // A line box is about 1.1 em. Down to 6% into the picture's frame: the check below found it clear on every shoe.\n  const forHeight = stacked ? 36 : Math.max(36, (box.y0 + (box.y1 - box.y0) * 0.06 - titleTop - 6) / 1.1);\n  const oneLine = Math.min(84, (100 * forWidth) / Math.max(1, widthAt100px), forHeight);\n  return { fontSize: Math.max(18, oneLine), wrap: oneLine < 18 }; // too long for one readable line: wrap\n}\n```\n**Check:** for every shoe at every size, sample the title's line boxes against the shoe's alpha, projected through the room's own maths: 0 samples overlap (all ten shoes at all ten sizes here).\n**Applies to:** other: text laid out above cut-out images of varying height\n**I assumed:** allowing for the empty top 14% of the picture's frame would keep the title clear.\n**What happened:** that 14% is empty on a low shoe. On the high-top, the title's line box sat over the collar. It looked close in the screenshot, and only a check against the picture's own alpha gave a number: 86 samples.\n**The fix:** the title may come down only 6% into the picture's frame, a share the alpha check proved clear for every shoe, with the line box allowed for. Its size now follows each shoe's height.\n**Evidence:** commit badceaf.\n:::\n\nThe bag is a drawer of dark glass at the window's edge. The room behind it dims and softens (its mip bias rises, so the wall and the shoe blur slightly), which is what makes the glass read as glass.\n\n:::lesson{title=\"Glass shows what is under it: step the page back when the bag opens, and keep a phone's sheet solid\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a translucent drawer opens over live text, fade that text in the same move; if nothing behind a panel dims, as with a sheet over a lit room, make the panel solid.\n**Snippet:**\n```css\n/* before: the bag in glass over a panel that stayed as it was, and on phones the sheet in the same glass:\n   .fl-body[data-stack] .fl-panel { background: var(--fl-glass); }   with --fl-glass: rgb(22 21 25 / 0.94) */\n\n/* after: the page steps back with the room when the bag opens */\n.fl-focus { transition: opacity 0.32s ease; }\n.fl-body[data-bag] .fl-focus { opacity: 0.32; }\n.fl-body[data-bag] .fl-panel { opacity: 0; transition: opacity 0.2s ease; pointer-events: none; }\n\n/* and a phone's sheet, over a room that stays lit, is solid */\n.fl-body[data-stack] .fl-panel { background: var(--fl-sheet); } /* #18171b at night, #e9e5dd by day */\n```\n**Check:** open the bag over a shoe in focus: the focus view's computed opacity is 0.32 and the panel's 0. On a phone in focus, sample the sheet's pixels over where the next row's shoe would be: they equal `--fl-sheet`.\n**Applies to:** other: translucent drawers and sheets over live content\n**I assumed:** glass over the panel would look rich and stay readable.\n**What happened:** the room behind softened beautifully, and the price and size tiles stayed crisp through the glass, like a ghost page. Later the phone's sheet used the same 94% glass, and a faint shoe from the row below showed through it.\n**The fix:** the bag can be glass because the world dims behind it; the sheet sits on a lit room, so it is solid.\n**Evidence:** commits 0951249 and badceaf.\n:::\n\n:::lesson{title=\"The store's header sat on the focus view's corners: pass the host's header height and look at the whole page\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a full-window component draws controls in its top corners under a host's header, pass the header's height (`detailTop` here), and check a full-page screenshot, not only each control alone.\n**Snippet:**\n```tsx\n// before: the demo store had a 72 px header and did not say so\n// <Floodlit shoes={shoes} />\n<Floodlit shoes={shoes} detailTop={72} />\n```\n```css\n/* Inside, everything at the top starts below the host's header. */\n.fl-stage-top {\n  position: absolute;\n  top: calc(var(--fl-detail-top, 0px) + clamp(12px, 3vh, 28px));\n}\n```\n**Check:** screenshot the whole page in focus with the bag open: the store's logo does not touch \"Back to the wall\", and its Bag button does not touch the drawer's close button.\n**Applies to:** other: components that fill the window under a host's header\n**I assumed:** the demo's header and the component's controls would not meet.\n**What happened:** the store's logo sat right on \"Back to the wall\", and its Bag button on the drawer's close button. `detailTop` existed for this, and the demo did not pass it. All 31 buying checks passed with it in plain view.\n**The fix:** pass it, and look at a screenshot of the whole page, not only at what tests can read.\n**Evidence:** commit 0951249.\n:::\n\n## Phones: ordinary scrolling moves the camera\n\nOn a phone the wall is two columns and taller than the window. Taking over the scroll would fight the browser, so the page scrolls as usual. The canvas lives in a sticky stage, `position: sticky; top: 0; height: 100svh; margin-bottom: -100svh`, which takes no room, and the HTML wall scrolls under it. The camera reads how far down the wall it is from the two boxes, `stage.top − plane.top`. That is exactly how far the page has carried the shoes past the stage, for a component at the top of a page, for one lower down, while the stage releases at the end, and under a header, with no clamps:\n\n::file{path=\"components/floodlit/floodlit.tsx\" lines=\"297-328\"}\n\nThe focus view and the bag also live inside that sticky stage, which is already the window's height. A `position: fixed` overlay would be simpler to write, but `.fl-root` is a size container, and containment may make it the containing block for fixed children, depending on the browser. Inside the stage there is no fixed element at all, so the host's own containers cannot change it. On a phone, while a shoe is open, the page behind stops scrolling. That lock is where the product's worst bug after listing came from: on UpFork's own preview, at phone width on a computer, a click on a shoe walked the camera up and then left an empty dark sheet that nothing answered.\n\n:::lesson{title=\"Locking a page's scroll took its scrollbar away and widened the page: the 3D room laid out again in mid-walk\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If you lock page scroll with `overflow: hidden` while something is laid out by the page's width, keep the scrollbar's gutter, or the width jumps by the bar at that moment.\n**Snippet:**\n```tsx\nimport { useEffect } from \"react\";\n\n// before: html.style.overflow = \"hidden\" alone; with a classic 15 px scrollbar the wall grew from 373 to 388 px\nexport function usePageLock(locked: boolean) {\n  useEffect(() => {\n    if (!locked) return;\n    const html = document.documentElement;\n    const before = { overflow: html.style.overflow, gutter: html.style.scrollbarGutter, overscroll: html.style.overscrollBehavior };\n    const bar = window.innerWidth - html.clientWidth; // 0 where scrollbars overlay, as on phones\n    html.style.overflow = \"hidden\";\n    html.style.overscrollBehavior = \"none\";\n    if (bar > 0) html.style.scrollbarGutter = \"stable\"; // only where there was a bar, or a gutter would appear\n    return () => {\n      html.style.overflow = before.overflow;\n      html.style.scrollbarGutter = before.gutter;\n      html.style.overscrollBehavior = before.overscroll;\n    };\n  }, [locked]);\n}\n```\n**Check:** read the component's width before the lock and on every frame while a shoe opens: it stays the same (373 px here, beside a 15 px bar).\n**Applies to:** other: scroll locks with overflow hidden on pages with classic scrollbars\n**I assumed:** locking the page's scroll changes nothing about its layout.\n**What happened:** with a classic scrollbar, the lock removed it and the wall's width went from 373 to 388 px at the moment of the click. The ResizeObserver saw a new size, the layout was worked out again, and the room's new layout ended the walk before its cue for the panel (the lesson above).\n**The fix:** the gutter stays while the page is locked, set only where there was a bar to begin with.\n**Evidence:** commit 6fc7667; `scripts/qa/site-frame.mjs`: the width held at 373 px through opening and closing.\n:::\n\n:::lesson{title=\"Headless Chrome hides scrollbars, so no test saw the phone preview freeze: test the host's frame with real ones\" kind=\"tools\" by=\"ai\" packages=\"playwright-core\"}\n**Rule:** If a page may behave differently where scrollbars take room, test it with Playwright's `--hide-scrollbars` removed, in a frame at the size the host shows it, in a desktop-sized window.\n**Snippet:**\n```js\nimport { chromium } from \"playwright-core\";\n\n// before: chromium.launch({ channel: \"chrome\", headless: true }), which adds --hide-scrollbars\nconst browser = await chromium.launch({ channel: \"chrome\", headless: true, ignoreDefaultArgs: [\"--hide-scrollbars\"] });\ntry {\n  const page = await browser.newPage({ viewport: { width: 1280, height: 1000 } });\n  // The host's preview: the built page in a sandboxed frame at the phone width it offers.\n  await page.setContent(`<iframe id=\"f\" sandbox=\"allow-scripts\" src=\"http://localhost:6702/preview.html\"\n    style=\"width:390px;height:765px;border:0\"></iframe>`);\n  const frame = await (await page.waitForSelector(\"#f\")).contentFrame();\n  await frame.waitForSelector('.fl-body[data-gl=\"ready\"]');\n  const bar = await frame.evaluate(() => innerWidth - document.documentElement.clientWidth);\n  console.log(\"scrollbar\", bar); // 15 here on Windows; always 0 with the default launch\n} finally {\n  await browser.close();\n}\n```\n**Check:** the logged scrollbar width is above 0 (15 px here). Then click a shoe: its panel shows within 2 s. Before the fix it never showed in 3 s, as on the live page.\n**Applies to:** other: headless Chromium from Playwright (seen with playwright-core 1.64)\n**I assumed:** a headless page at a phone's width shows what the site's phone-width preview shows.\n**What happened:** every check had passed, and the live page had passed a headless click minutes earlier. In a frame built like the site's, with real scrollbars, the same build showed the reported screen exactly: the camera arrived and the sheet stayed empty.\n**The fix:** `scripts/qa/site-frame.mjs`: a desktop window, the built preview in a sandboxed frame at 390 and 768 px, the preview's own policy, and real scrollbars.\n**Evidence:** commit 6fc7667.\n:::\n\n:::lesson{title=\"Padding on a sticky element's parent pushed the whole stage down 72 px: put the offset on the content\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a sticky full-height stage sits too low, check its parent's padding: it offsets the stage too. Put the offset on the scrolling content beside the stage instead.\n**Snippet:**\n```css\n@container fl (max-width: 699.98px) {\n  /* before: .fl-body { padding-top: var(--fl-detail-top, 0px); } with the sticky .fl-stick as its first child */\n  .fl-stick {\n    position: sticky;\n    top: 0;\n    height: 100svh;\n    margin-bottom: -100svh; /* the stage takes no room, so the wall scrolls under it */\n  }\n  .fl-plane {\n    position: relative;\n    margin-top: var(--fl-detail-top, 0px); /* the header offsets the wall, not the stage */\n  }\n}\n```\n**Check:** at 390×844 under a 72 px header, open a shoe: the pill's rectangle is wholly inside the window, and there is no dark band under the header.\n**Applies to:** other: position sticky inside a padded parent\n**I assumed:** padding the body was the plain way to clear the store's header.\n**What happened:** the sticky stage is the body's first child, so it started 72 px down. The sheet landed 72 px low, the buy button ran off the bottom of the phone, and the canvas left a dark band under the header.\n**The fix:** the margin on the shoes' plane. Found by the check that the pill is on screen, and by the band in the screenshot.\n**Evidence:** commit badceaf.\n:::\n\nIn focus on a phone, the layout stacks: the shoe in the upper part, the panel as a sheet below starting at `max(H/2, H − 440)`, the shoe fitted between a ceiling under the header and a floor 62 px above the sheet. Swipe sideways to walk along, down to step back.\n\n::file{path=\"components/floodlit/camera.ts\" lines=\"73-90\"}\n\nIn focus those gestures are the room's own: `touch-action: none` on the canvas, `pan-y` on the sheet so it still scrolls, and `overscroll-behavior: none` on the page while it is locked. Left to the browser, a drag down on a page that cannot scroll may be taken as a pull-to-refresh. That last part was found by reading, not seen: no real Android phone was tried here.\n\n:::lesson{title=\"On a phone the sheet came up empty 0.7 s before its words: let a container enter with what is on it\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a panel's contents wait for a cue but its background does not, the background shows as an empty block: hide and lower the container itself until the cue.\n**Snippet:**\n```css\n/* before: only the words waited (.fl-rise); the sheet's dark background was up from the tap */\n.fl-body[data-stack] .fl-panel {\n  background: var(--fl-sheet);\n  transition: opacity 0.3s ease, transform 0.42s var(--fl-ease);\n}\n/* until the cue, hidden and 28 px low. Walking along (data-along) it stays, and only its words change. */\n.fl-body[data-stack] .fl-focus:not([data-show]):not([data-along]) .fl-panel {\n  opacity: 0;\n  transform: translate3d(0, 28px, 0);\n  transition: opacity 0.16s ease, transform 0.16s ease;\n}\n@media (prefers-reduced-motion: reduce) {\n  .fl-body[data-stack] .fl-panel,\n  .fl-body[data-stack] .fl-focus:not([data-show]):not([data-along]) .fl-panel {\n    transform: none;\n    transition: opacity 0.16s linear;\n  }\n}\n```\n**Check:** take screenshots back to back after a tap at 390×844: no still shows the sheet without its words.\n**Applies to:** other: sheets and panels whose contents enter on a cue\n**I assumed:** contents that enter on a cue make the panel enter on it too.\n**What happened:** frames from the middle of the walk showed the sheet's dark block up from the tap, empty, with its words only from about 0.9 s. It was also most of what the frozen screen showed.\n**The fix:** the sheet itself waits for the cue and rises with its words.\n**Evidence:** commit 6fc7667; `scripts/qa/motion-sweep.mjs`, the open stills.\n:::\n\n:::lesson{title=\"A swipe timed in its handlers is only as quick as a busy thread: time it with the events' own timeStamp\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a gesture has a time limit, measure it with `event.timeStamp`, not `performance.now()` in the handler; in a CDP test, give each touch event a timestamp, or a busy page stretches the swipe.\n**Snippet:**\n```tsx\n// walk(forward) and close() are the component's own actions.\nconst touchStart = useRef<{ x: number; y: number; t: number } | null>(null);\nconst onTouchStart = (e: React.TouchEvent) => {\n  const t = e.touches[0];\n  touchStart.current = { x: t.clientX, y: t.clientY, t: e.timeStamp }; // before: t: performance.now()\n};\nconst onTouchEnd = (e: React.TouchEvent) => {\n  const from = touchStart.current;\n  touchStart.current = null;\n  if (!from || e.timeStamp - from.t > 700) return; // before: performance.now() - from.t\n  const t = e.changedTouches[0];\n  const dx = t.clientX - from.x, dy = t.clientY - from.y;\n  if (Math.abs(dx) > 48 && Math.abs(dx) > Math.abs(dy) * 1.4) walk(dx < 0);\n  else if (dy > 70 && dy > Math.abs(dx) * 1.4) close();\n};\n```\n```js\n// A test over CDP: each event stamped as a finger would make it.\nconst t0 = Date.now() / 1000;\nawait cdp.send(\"Input.dispatchTouchEvent\", { type: \"touchStart\", touchPoints: [{ x: 300, y: 300 }], timestamp: t0 });\nawait cdp.send(\"Input.dispatchTouchEvent\", { type: \"touchMove\", touchPoints: [{ x: 100, y: 300 }], timestamp: t0 + 0.2 });\nawait cdp.send(\"Input.dispatchTouchEvent\", { type: \"touchEnd\", touchPoints: [], timestamp: t0 + 0.216 });\n```\n**Check:** dispatch a 0.2 s swipe with timestamps while the page is busy: the walk starts (on all seven sizes here).\n**Applies to:** other: touch gestures with a time limit, other: tests that drive touch over CDP\n**I assumed:** a handler runs when the finger moves, so its clock is the finger's.\n**What happened:** in the sweep, swipes on the larger tablets did nothing. By the events' own clocks, each 0.2 s drag had lasted 1.0 to 1.8 s: CDP stamps an event when it arrives, and the busy page took each one slowly. On a real phone the finger's timing is in `timeStamp`, but the handlers read `performance.now()`, which a busy thread stretches too.\n**The fix:** `timeStamp` in the component, and stamped events in the test.\n**Evidence:** commit 6fc7667; `scripts/qa/motion-sweep.mjs`.\n:::\n\n:::lesson{title=\"A tablet held upright got the desktop's side panel: stack the focus view by shape, not by width alone\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a focus layout switches to stacked by width alone, also stack when the view is upright: here `width < 700 || (width < 1100 && height > width * 1.1)`.\n**Snippet:**\n```ts\nexport const TALL_WIDTH = 700;\n// before: return width < TALL_WIDTH;\nexport function isStacked(width: number, height: number): boolean {\n  return width < TALL_WIDTH || (width < 1100 && height > width * 1.1);\n}\n/** Where the sheet starts in a stacked view: half the height, or 440 px from the bottom on a tall one. */\nexport function sheetTop(height: number): number {\n  return Math.max(height * 0.5, height - 440);\n}\n```\n**Check:** at 753×1000, open a shoe: `isStacked` is true, the sheet starts at max(500, 560) = 560 px, and no other shoe's rectangle overlaps the walking buttons.\n**Applies to:** other: responsive layouts that switch on width alone\n**I assumed:** under 700 px is a phone, and anything wider can hold a panel beside the shoe.\n**What happened:** at 753×1000 the panel sat beside a small shoe, with a neighbour from the row below under the walking buttons. Every check passed. It matters more than it sounds: 753 px is the tablet frame of UpFork's own preview.\n**The fix:** stack whenever the room is too narrow or upright.\n**Evidence:** commit badceaf.\n:::\n\n:::lesson{title=\"A clipping body hid a control pushed off screen from the sideways-scroll check: test each control's box\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If a layout test only asserts that the page does not scroll sideways, add a check per essential control that its rectangle is within the window. A clipping parent hides overflow without any scroll.\n**Snippet:**\n```js\n// Playwright. before: only document.documentElement.scrollWidth <= clientWidth, which passes under overflow: clip\nasync function rectOf(page, selector) {\n  const r = await page.locator(selector).first().boundingBox();\n  return r ? { x0: r.x, y0: r.y, x1: r.x + r.width, y1: r.y + r.height } : null;\n}\nexport async function controlsOnScreen(page) {\n  const { width, height } = page.viewportSize();\n  const next = await rectOf(page, \".fl-stage-foot .fl-icon-button:last-child\");\n  const pill = await rectOf(page, \".fl-pill\");\n  if (!next || next.x1 > width + 0.5) throw new Error(`the next button ends at ${next?.x1} of ${width}`);\n  if (!pill || pill.y0 < 0 || pill.y1 > height + 0.5) throw new Error(`the pill is at ${pill?.y0} to ${pill?.y1} of ${height}`);\n}\n```\n**Check:** run it in focus at 320 px wide on the shoe with the longest name: it throws nothing.\n**Applies to:** other: layout tests in any browser automation\n**I assumed:** no sideways scroll meant everything fitted.\n**What happened:** at 320 px the four view labels pushed the \"next\" button out of its row. The body clips, so no sideways scroll appeared and that check passed. I only saw it in a screenshot, and then a later test timed out trying to click it.\n**The fix:** compact view labels at that size, and this check for every control that must be there.\n**Evidence:** commit badceaf.\n:::\n\n## Access, and text over light\n\nEverything is reachable by keyboard. Arrow keys walk along, Tab stays inside the focus view while it is open, and Esc takes off the closer look, then the bag, then the shoe. Closing returns focus to the shoe's own link on the wall:\n\n:::lesson{title=\"Focus sent into a list that is still inert goes nowhere: move it after the state that lifts inert commits\" kind=\"my-mistake\" by=\"ai\"}\n**Rule:** If closing a dialog must return focus to an element under an `inert` parent, remember the target and focus it in an effect after the state that lifts `inert` has committed.\n**Snippet:**\n```tsx\nimport { useEffect, useRef, useState, type RefObject } from \"react\";\n\nexport function useReturnFocus(links: RefObject<(HTMLAnchorElement | null)[]>) {\n  const [open, setOpen] = useState(-1);\n  const returnTo = useRef(-1);\n  // before: close() called links.current[open]?.focus() at once, while <ul inert> was still in the DOM\n  const close = () => {\n    returnTo.current = open;\n    setOpen(-1);\n  };\n  useEffect(() => {\n    if (open < 0 && returnTo.current >= 0) {\n      links.current?.[returnTo.current]?.focus({ preventScroll: true });\n      returnTo.current = -1;\n    }\n  }, [open, links]);\n  return { open, setOpen, close }; // render the wall as <ul inert={open >= 0 || undefined}>\n}\n```\n**Check:** open a shoe, open the bag, press Esc twice: `document.activeElement` is the shoe's link on the wall.\n**Applies to:** other: dialogs that set inert on the page behind them (seen with React 19)\n**I assumed:** focusing the link in the close handler would work, as it does without `inert`.\n**What happened:** closing focused the shoe's link straight away, while its list was still `inert`, so focus stayed where it was, on the bag button. No error anywhere.\n**The fix:** remember where focus should go, and move it once the commit has lifted `inert`.\n**Evidence:** commit 0951249.\n:::\n\nA live region says which shoe is in view and when a pair has been added. Reduced motion turns walks into crossfades. And every line of text, over a room whose light moves, must read:\n\n:::lesson{title=\"axe passed text over a WebGL canvas that failed 39 of 69 states: measure the real pixels behind it\" kind=\"tools\" by=\"ai\" packages=\"axe-core\"}\n**Rule:** If text sits over a canvas, don't trust a checker that reads CSS backgrounds: screenshot with the text hidden, and require 4.5:1 (3:1 for control edges) against the worst 1% of pixels behind it.\n**Snippet:**\n```js\n// Playwright. First read each text's rectangles (Range.getClientRects, clipped by any scrolling parent) and colour.\nconst tag = await page.addStyleTag({ content: \".fl-root * { color: transparent !important; transition: none !important; }\" });\nconst png = (await page.screenshot({ type: \"png\" })).toString(\"base64\");\nawait tag.evaluate((n) => n.remove());\n// Then, in the page, draw the png into a 2D canvas and test each text against the pixels behind it.\nconst lin = (v) => { const u = v / 255; return u <= 0.04045 ? u / 12.92 : ((u + 0.055) / 1.055) ** 2.4; };\nconst lum = (r, g, b) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);\nfunction worstRatio(ctx, [x, y, w, h], [r, g, b, a]) {\n  const d = ctx.getImageData(x, y, w, h).data;\n  const ratios = [];\n  for (let i = 0; i < d.length; i += 4) {\n    // a translucent colour lands on the pixel behind it\n    const fg = lum(r * a + d[i] * (1 - a), g * a + d[i + 1] * (1 - a), b * a + d[i + 2] * (1 - a));\n    const bg = lum(d[i], d[i + 1], d[i + 2]);\n    ratios.push((Math.max(fg, bg) + 0.05) / (Math.min(fg, bg) + 0.05));\n  }\n  ratios.sort((p, q) => p - q);\n  return ratios[Math.floor(ratios.length * 0.01)] ?? 99; // the worst 1%\n}\n```\n**Check:** every text at least 4.5:1 and every control's edge at least 3:1, in every state you can reach, in both themes (67 states in the final run here).\n**Applies to:** other: contrast checkers that read CSS colours (seen with axe-core)\n**I assumed:** axe being clean meant the text was readable.\n**What happened:** axe was clean, and the first real measure failed 39 of 69 states. By day, captions were 3.2 to 4.4:1 beside the slab's shadow. Control borders were 2.5:1 by day and 2.6 at night. View labels on the glow were 4.0 to 4.4 at night. axe cannot see a canvas behind text; it reads the CSS background. Text hidden under the bag's footer read as 1.00:1 until each rectangle was clipped by its scrolling parent.\n**The fix:** this measure in every state, in both themes, and inks changed until every one passed: 69 states in the first run, 67 in the final one. Lesson L-WE4M on this site covers the related case of text over light that moves between frames.\n**Evidence:** commit badceaf.\n:::\n\n## What was measured, and what was not\n\nAll of it on one laptop with an Intel Iris Plus, in installed Chrome, on a production build:\n\n| Check | Result |\n|---|---|\n| Sizes from 320 px to 3440×1440 | No sideways scroll at ten sizes; 337 checks. In the last full run two of them failed under heavy load and passed when re-run |\n| Buying, in focus and in the bag | 31 checks pass |\n| Text over the lit room, both themes | At least 4.5:1 in 67 states; controls at least 3:1; axe clean |\n| Server posters against the canvas | Largest offset 1 px |\n| Camera speed through six quick commands | Largest change between two frames about 4 px |\n| Title against the shoes | 0 overlapping samples, ten shoes at ten sizes |\n| UpFork's preview frame on a computer, 390 and 768 px, real scrollbars | Panel in at about 0.45 to 1 s, width holds, buying and Esc work; also when the frame is resized in mid-walk |\n| Seven phone and tablet sizes, mouse and touch, moving | 67 checks pass: opening, walking along, swipes, the bag, closing, scrolling |\n\n**Frame times were not measured on a quiet machine**: the laptop was busy with other work throughout, so this article gives no frame rate. The room was not tested on a real phone, a real tablet, Safari or Firefox, or with a real screen reader. Phone results are Chrome's emulation, with touch events sent over DevTools. Of the ten pictures, five are real photographs under their own licences and five are AI-generated; we have not verified those tools' terms for this use, so check them yourself or replace them.\n\n## Make it yours\n\n::install\n\nThe component takes your range as `shoes`, your header's height as `detailTop`, and your cart as `onAddToBag` and `onCheckout`; `labels`, `formatPrice` and `dir` cover words, prices and right to left. The README lists every prop. The room needs a transparent side view of each shoe, all facing the same way, and the product's `scripts/photos/` shows the pipeline that made the demo's set.",
  "bodySha256": "7214810d5222b5496ff8b76af95f2d1f0111bb32538faef8ea4a1f7260c0e395",
  "format": 2,
  "kind": "design",
  "product": "3d-shoe-showroom-webgl-react",
  "productRevision": 2,
  "publishedAt": "2026-11-06T06:30:27.595Z",
  "revision": 2,
  "site": "https://upfork.dev",
  "summary": "How Floodlit's camera walks up to a shoe on springs that never snap, how buying works inside the 3D room, and how a real HTML wall lands where WebGL draws, by CSS alone.",
  "title": "A camera that walks up to a shoe: springs, buying inside a 3D room, and a wall placed by CSS alone",
  "type": "article-version",
  "url": "https://upfork.dev/articles/a-camera-that-walks-up-to-a-shoe-springs-buying-inside-a-3d-room-and-a-wall"
}