A camera that walks up to a shoe: springs, buying inside a 3D room, and a wall placed by CSS alone

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.

Ramin Valadan28 min read5 Nov 2026Updated 6 Nov 20261 view

Written with AI: Claude Opus 5.5, through Claude

23 lessons learned building it

No ratings yet

0 Save

The product

Floodlit — 3D Sneaker & Shoe Showroom for React with a WebGL Product Gallery

Free · Component

Get it

The product

Floodlit — 3D Sneaker & Shoe Showroom for React with a WebGL Product Gallery

Free · Component

A 3D night showroom for sneaker and shoe stores in React and raw WebGL2: pairs stand on lit acrylic shelves, the camera walks up to the shoe you click, and sizes, add to bag and the bag live in the room. No three.js.

npx shadcn@latest add https://upfork.dev/r/3d-shoe-showroom-webgl-react.json

Get it Live preview

On this page

What this one is about

Floodlit 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.

Live preview

Preview of Floodlit — 3D Sneaker & Shoe Showroom for React with a WebGL Product Gallery

Everything 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.

The walk up: anchored on the shoe

The 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.

So 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:

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;
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;
the camera is solved from those two: camera.x = anchor.x − (s.x − W/2 − shiftX·W/2) / k, with k = f / D(u).

Near 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.

components/floodlit/room.tslines 138–166Open in the code browser

  /**
   * A path towards a shoe or away from it, anchored on the shoe: it travels in a straight line across the screen
   * from wherever it is now to where it ends, while the distance eases. So it never swerves, and a command in
   * mid-walk just starts a new line from the present moment.
   */
  function anchoredPath(anchorX: number, anchorY: number, to: Goal, ease: (u: number) => number, rise: number, settle: number) {
    const from = currentGoal();
    const [sx0, sy0] = screenOf(anchorX, anchorY, from);
    const [sx1, sy1] = screenOf(anchorX, anchorY, to);
    const f = focalLength(cssW);
    return (u: number): Goal => {
      // The settle: past the target by a little, and back. Only the distance does it.
      const over = settle * Math.sin(Math.PI * Math.min(1, Math.max(0, (u - 0.7) / 0.3)));
      const e = ease(u);
      const logD = mix(from.logD, to.logD, e) - over * (from.logD - to.logD);
      const k = f / Math.exp(logD);
      const shiftX = mix(from.shiftX, to.shiftX, e);
      const shiftY = mix(from.shiftY, to.shiftY, e);
      const sx = mix(sx0, sx1, e);
      const sy = mix(sy0, sy1, e) + rise * Math.sin(Math.PI * e);
      return {
        x: anchorX - (sx - cssW / 2 - (shiftX * cssW) / 2) / k,
        y: anchorY - (sy - cssH / 2 + (shiftY * cssH) / 2) / k,
        logD,
        shiftX,
        shiftY,
      };
    };
  }

components/floodlit/room.tslines 307–340Open in the code browser

    const cx = slot.card.x + slot.card.w / 2;
    const cy = slot.slab.y - slot.card.h * 0.4;
    closer.zoom.x = 1;
    closerTarget = { zoom: 1, u: 0.5, v: 0.5, omega: 8 };
    startPath({
      t0: now(),
      delay: 60,
      duration: 1230,
      at: anchoredPath(cx, cy, to, walkEase, -14, 0.012),
      mark: { u: 0.55, done: false, run: () => options.onPanelClear?.() },
    });
  }

  /** On foot along the wall: a pan with a small step back in the middle. */
  function walkAlongTo(to: Goal) {
    const from = currentGoal();
    closerTarget = { zoom: 1, u: 0.5, v: 0.5, omega: 8 };
    startPath({
      t0: now(),
      delay: 0,
      duration: 700,
      mark: { u: 0.3, done: false, run: () => options.onPanelClear?.() },
      at: (u) => {
        const e = alongEase(u);
        return {
          x: mix(from.x, to.x, e),
          y: mix(from.y, to.y, e),
          logD: mix(from.logD, to.logD, e) + 0.06 * Math.sin(Math.PI * e),
          shiftX: mix(from.shiftX, to.shiftX, e),
          shiftY: mix(from.shiftY, to.shiftY, e),
        };
      },
    });
  }

Walking 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.

Closing has the opposite timing to get right. The wall's own HTML, its heading, names and prices, comes back on the way home:

LessonMy own mistakeL-CB7C Learned by the AI · Claude Opus 5.5

Walking back, the wall's words came back at once over the wrong shoes: wait until the camera is nearly home

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).
Snippet: import { useEffect, useState } from "react"; declare function whileVisible(ms: number, then: () => void): () => void; // before: the wall's words faded back on close, over 0.22 s, with the camera still close in export function useWordsWaitForHome(room: { close: () => void }) { const [returning, setReturning] = useState(false); const close = () => { setReturning(true); room.close(); // the room's walk back calls onHome at u = 0.82 of its 840 ms }; const onHome = () => setReturning(false); // passed to the room's events // If the word never comes: whileVisible, from the lesson on the panel's cue below, counts only while visible. useEffect(() => (returning ? whileVisible(1500, () => setReturning(false)) : undefined), [returning]); return { returning, close, onHome }; // <div className="fl-body" data-return={returning || undefined}> }

.fl-body[data-focus] .fl-plane, .fl-body[data-return] .fl-plane { opacity: 0; }
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.
Applies to: other: HTML labels over a moving 3D view
I assumed: words that fade in over 0.22 s would arrive with the room.
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.
The fix: a home event from the room, and the words wait for it.
Evidence: commit 6fc7667; scripts/qa/motion-sweep.mjs, the close stills.

LessonMy own mistakeL-G4M9 Learned by the AI · Claude Opus 5.5

A walk-up curve with a long slow start read as lag: check a filmstrip, not only the arrival time

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.
Snippet: // A cubic bezier from (0,0) to (1,1), as CSS cubic-bezier(), sampled once into a table. function sampledEase(x1: number, y1: number, x2: number, y2: number, n = 96) { const bez = (t: number, a: number, b: number) => 3 * (1 - t) * (1 - t) * t * a + 3 * (1 - t) * t * t * b + t * t * t; const table = new Float32Array(n + 1); for (let i = 0; i <= n; i++) { let lo = 0, hi = 1; for (let k = 0; k < 24; k++) { const t = (lo + hi) / 2; if (bez(t, x1, x2) < i / n) lo = t; else hi = t; } table[i] = bez((lo + hi) / 2, y1, y2); } return (u: number) => { const p = Math.min(1, Math.max(0, u)) * n, i = Math.min(n - 1, Math.floor(p)); return table[i] + (table[i + 1] - table[i]) * (p - i); }; } // before: sampledEase(0.5, 0, 0.14, 1) const walkEase = sampledEase(0.36, 0.04, 0.16, 1); // The walk up: u = (msSinceClick - 60) / 1230
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).
Applies to: other: eased camera or interface moves started by a click
I assumed: a slow start would read as the weight of a real camera.
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.
The fix: (0.36, 0.04, 0.16, 1). The filmstrip showed the camera moving by 84 ms, with the same arrival.
Evidence: commit 3a3a4b5.

Springs that never snap

Every 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:

e = exp(−ω·dt), tmp = (v + ω·(x − target))·dt, x' = target + (x − target + tmp)·e, v' = (v − ω·tmp)·e

The 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.

components/floodlit/spring.tslines 6–26Open in the code browser

/** Critically damped: reaches the target with no overshoot. */
export function critical(s: Spring, target: number, omega: number, dt: number): void {
  const e = Math.exp(-omega * dt);
  const delta = s.x - target;
  const tmp = (s.v + omega * delta) * dt;
  s.x = target + (delta + tmp) * e;
  s.v = (s.v - omega * tmp) * e;
}

/** Under-damped: a small overshoot, set by zeta below 1. */
export function underdamped(s: Spring, target: number, omega: number, zeta: number, dt: number): void {
  const wd = omega * Math.sqrt(1 - zeta * zeta);
  const e = Math.exp(-zeta * omega * dt);
  const c = Math.cos(wd * dt);
  const sn = Math.sin(wd * dt);
  const delta = s.x - target;
  const a = delta;
  const b = (s.v + zeta * omega * delta) / wd;
  s.x = target + e * (a * c + b * sn);
  s.v = e * ((-zeta * omega) * (a * c + b * sn) + wd * (-a * sn + b * c));
}

The 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.

LessonMy own mistakeL-N0M6 Learned by the AI · Claude Opus 5.5

Carrying only the speed into a new camera path still braked: carry the spring's lead as well

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.
Snippet: type Spring = { x: number; v: number }; const CARRY_SECONDS = 0.17; // Exact critically damped step. function critical(s: Spring, target: number, omega: number, dt: number) { const e = Math.exp(-omega * dt); const delta = s.x - target; const tmp = (s.v + omega * delta) * dt; s.x = target + (delta + tmp) * e; s.v = (s.v - omega * tmp) * e; } // One axis; the room does the same for x, y, log distance and both lens shifts. path(u) is the walk's own curve. // before: no carry, then the velocity alone ({ v: pose.v, lead: 0 }); the new path starts at the pose either way. let carry = { t0: 0, v: 0, lead: 0 }; function startPath(pose: Spring, goal: number, now: number) { carry = { t0: now, v: pose.v, lead: goal - pose.x }; } function goalAt(pathValue: number, now: number) { const tau = Math.max(0, now - carry.t0) / 1000; const e = Math.exp(-tau / CARRY_SECONDS); return pathValue + carry.v * tau * e + carry.lead * e; // at tau = 0 the goal has not moved at all } // each frame: critical(pose, goalAt(path(u), now), 34, dt), where path: (u: number) => number
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).
Applies to: other: spring-smoothed paths that can be interrupted
I assumed: a new path that started from where the camera was, with no jump in position, would feel continuous.
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.
The fix: carry both. The goal does not move at the moment of the command, and the old motion fades into the new path.
Evidence: commit 3a3a4b5; room.ts lines 180-202.

components/floodlit/room.tslines 180–202Open in the code browser

  function startPath(p: Path) {
    // The spring trails its goal a little. Keep that lead too, or the goal jumps back and the camera brakes hard.
    const lead = { x: goal.x - pose.x.x, y: goal.y - pose.y.x, logD: goal.logD - pose.logD.x, shiftX: goal.shiftX - pose.shiftX.x, shiftY: goal.shiftY - pose.shiftY.x };
    carry = { t0: p.t0, x: pose.x.v, y: pose.y.v, logD: pose.logD.v, shiftX: pose.shiftX.v, shiftY: pose.shiftY.v, lead };
    path = p;
    wake();
  }

  /** The present velocity fades into the new path. At the moment of the command the speed is unchanged. */
  function withCarry(g: Goal, t: number): Goal {
    const tau = Math.max(0, t - carry.t0) / 1000;
    if (tau > 1.4) return g;
    const e = Math.exp(-tau / CARRY_SECONDS);
    const f = tau * e;
    const l = carry.lead;
    return {
      x: g.x + carry.x * f + l.x * e,
      y: g.y + carry.y * f + l.y * e,
      logD: g.logD + carry.logD * f + l.logD * e,
      shiftX: g.shiftX + carry.shiftX * f + l.shiftX * e,
      shiftY: g.shiftY + carry.shiftY * f + l.shiftY * e,
    };
  }

Walks are timed against the clock, which brings one more case: a frame that comes very late.

LessonMy own mistakeL-1ZEB Learned by the AI · Claude Opus 5.5

A walk timed against the clock jumps to its end after a hidden tab: push its start forward by the gap

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.
Snippet: type Path = { t0: number; delay: number; duration: number }; let path: Path | null = null; let carryT0 = 0; // when the carried speed began to fade (the lesson above) let lastT = 0; // before: no gap handling, so u = (t - t0 - delay) / duration was 1 on the first frame back function frame(t: number) { const dtMs = lastT ? t - lastT : 16.7; lastT = t; if (dtMs > 120) { const paused = dtMs - 16.7; // keep one ordinary frame of progress if (path) path.t0 += paused; carryT0 += paused; } const u = path ? Math.min(1, Math.max(0, (t - path.t0 - path.delay) / path.duration)) : 1; // draw at u; springs step with dt = min(dtMs, 50) / 1000 }
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.
Applies to: other: requestAnimationFrame animations timed against the clock
I assumed: a walk that always lands where it should needed nothing for a stall.
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.
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.
Evidence: commit 0481bb3; room.ts lines 689-697.

Looking around without turning a photograph

The 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.

components/floodlit/room.tslines 630–656Open in the code browser

    const f = focalLength(cssW);
    const k = f / dist;
    const reach = Math.tan((LOOK_DEGREES * Math.PI) / 180) * dist * d;

    // Closer on the shoe: the same card, scaled about a chosen point. The camera comes forward; nothing is enlarged
    // beyond what the picture holds, because the caller sets the limit per shoe.
    if (closer.zoom.x > 1.0005 && focused >= 0 && layout) {
      const card = layout.slots[focused].card;
      const zoom = closer.zoom.x;
      const px = card.x + closer.u.x * card.w;
      const py = card.y + closer.v.x * card.h;
      const centreX = card.x + card.w / 2;
      const centreY = layout.slots[focused].slab.y - card.h * 0.42;
      const [sx, sy] = screenOf(centreX, centreY, g);
      const dist1 = dist / zoom;
      const k1 = f / dist1;
      p.z = SHOE_Z + dist1;
      p.x = px - (sx - cssW / 2 - (p.shiftX * cssW) / 2) / k1;
      p.y = py - (sy - cssH / 2 + (p.shiftY * cssH) / 2) / k1;
    }
    const dx = lookX.x * reach;
    const dy = lookY.x * reach * 0.6;
    p.x += dx;
    p.shiftX += (dx * k * 2) / cssW;
    p.y += dy;
    p.shiftY -= (dy * k * 2) / cssH;

Hover 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.

The wall is HTML, placed by CSS alone

Under 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.

LessonMy own mistakeL-SZZN Learned by the AI · Claude Opus 5.5

A poster wall placed through the camera in React was empty without script: make the 3D plane 1:1 with CSS

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.
Snippet: // before (P3): placed in React through the camera, hidden until the first effect had run // let cardStyle: React.CSSProperties = { visibility: "hidden" }; // if (slot && pose) { const [x0, y0] = screenAt(pose, W, H, slot.card.x, slot.card.y, SHOE_Z); ... } // after: the rest camera at the focal length from the shoes' plane, so k = f / (z - SHOE_Z) = 1 there. const restZ = (f: number) => f + SHOE_Z; // Each card gets its column and row per breakpoint as CSS variables, in the server's markup. function slotVars(index: number, count: number, columnsFor: (width: number, count: number) => number) { const out: Record<string, number> = {}; for (const [name, width] of [["lg", 1100], ["md", 700], ["sm", 320]] as const) { const cols = columnsFor(width, count); const rows = Math.ceil(count / cols); const row = Math.floor(index / cols); const inRow = row === rows - 1 ? count - cols * (rows - 1) : cols; out[`--c-${name}`] = index - row * cols; out[`--r-${name}`] = row; out[`--o-${name}`] = (cols - inRow) / 2; // a short last row is centred } return out; }

.fl-card { position: absolute; left: calc(var(--left) + (var(--col) + var(--off)) * (var(--w) + var(--gap))); top: calc(var(--first) + var(--row) * var(--pitch) - var(--w) / var(--aspect) * var(--baseline)); width: var(--w); }
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.
Applies to: other: HTML overlays that must match a WebGL perspective camera
I assumed: the cards could be placed by the room's own maths in React.
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.
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.
Evidence: commit badceaf; the hydration and jump checks.

The 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:

components/floodlit/floodlit.csslines 23–69Open in the code browser

/* The same maths as layout.ts, in CSS, so the server's markup lands exactly where the room will draw. A container
   cannot query itself (L-WN64), so everything hangs off .fl-body, its child. */
.fl-body {
  --cols: var(--n-lg);
  --rows: var(--rows-lg);
  --edge: max(16px, 4cqw);
  --gap: max(10px, 1.2cqw);
  --w: min(calc((100cqw - 2 * var(--edge) - var(--gap) * (var(--cols) - 1)) / var(--cols)), 340px);
  --left: calc((100cqw - (var(--w) * var(--cols) + var(--gap) * (var(--cols) - 1))) / 2);
  --head: max(96px, calc(var(--w) * 0.62));
  --pitch: calc(var(--w) * 1.24 + 8px);
  --first: calc(var(--head) + var(--w) * 0.62);
  --H: calc(var(--first) + (var(--rows) - 1) * var(--pitch) + 8px + var(--w) * 0.34);
  position: relative;
  height: 100svh;
  min-height: 520px;
  overflow: clip;
}
.fl-slot {
  --col: var(--c-lg);
  --row: var(--r-lg);
  --off: var(--o-lg);
}
@container fl (max-width: 1099.98px) {
  .fl-body {
    --cols: var(--n-md);
    --rows: var(--rows-md);
  }
  .fl-slot {
    --col: var(--c-md);
    --row: var(--r-md);
    --off: var(--o-md);
  }
}
@container fl (max-width: 699.98px) {
  .fl-body {
    --cols: var(--n-sm);
    --rows: var(--rows-sm);
    height: auto;
    min-height: 100svh;
  }
  .fl-slot {
    --col: var(--c-sm);
    --row: var(--r-sm);
    --off: var(--o-sm);
  }
}

components/floodlit/floodlit.tsxlines 64–79Open in the code browser

/** Where a shoe goes at each breakpoint, as CSS variables, so the server's markup places it with no script at all. */
function slotVars(index: number, count: number, rtl: boolean): Record<string, number> {
  const out: Record<string, number> = {};
  const at: [string, number][] = [["lg", 1100], ["md", 700], ["sm", 320]];
  for (const [name, width] of at) {
    const cols = columnsFor(width, count);
    const rows = Math.ceil(count / cols);
    const row = Math.floor(index / cols);
    const inRow = row === rows - 1 ? count - cols * (rows - 1) : cols;
    const col = index - row * cols;
    out[`--c-${name}`] = rtl ? inRow - 1 - col : col;
    out[`--r-${name}`] = row;
    out[`--o-${name}`] = (cols - inRow) / 2;
  }
  return out;
}

For 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.

Without 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.

The posters and the room's textures are the same pictures, so they should be the same files:

LessonMy own mistakeL-1B1R Learned by the AI · Claude Opus 5.5

Poster and texture in two sizes fetched every shoe twice: let the room read the poster's currentSrc

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.
Snippet: // before: sizes="(min-width: 1100px) 20vw, (min-width: 700px) 25vw, 50vw" chose the 480 file on a desktop, // while the room fetched the 960 for its texture: two downloads of every shoe. <img ref={(el) => { posters.current[i] = el; }} className="fl-poster" src={shoe.photo.src} // the 960 file srcSet={shoe.photo.srcSet} // "...-480.webp 480w, ...-960.webp 960w" sizes="(min-width: 700px) 481px, 50vw" // 481, one past the small file, so a 1x desktop still takes the 960 alt={shoe.photo.alt} /> // The room's texture: whichever file the poster chose. const texture = posters.current[i]?.currentSrc || shoe.photo.src;
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).
Applies to: other: pages that show one image as an img and as a WebGL texture
I assumed: small posters and larger textures were the lighter choice.
What happened: every shoe was fetched twice, and with the wall maps on top the first view came to 1028 KB against 900 allowed.
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.
Evidence: commit 0481bb3.

Buying inside the room

In 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.

LessonMy own mistakeL-W3KH Learned by the AI · Claude Opus 5.5

A walk cut short by a new layout never gave the panel its cue: a cancelled path must still run its marks

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.
Snippet: type Mark = { u: number; done: boolean; run: () => void }; type Path = { t0: number; duration: number; at: (u: number) => number; mark?: Mark }; let path: Path | null = null; // The room, when the layout changes (a dragged window, a turned phone, a scrollbar that went). function onLayoutChanged() { // before: path = null, and the panel's mark at u = 0.55 never ran if (path?.mark && !path.mark.done) { path.mark.done = true; path.mark.run(); } path = null; // the springs carry the camera to the new frame }

// The page: if the cue never comes, the panel comes anyway, after 1.8 s of the page being visible. function whileVisible(ms: number, then: () => void): () => void { let timer: ReturnType<typeof setTimeout> | undefined; const arm = () => { clearTimeout(timer); if (document.visibilityState !== "hidden") timer = setTimeout(then, ms); }; arm(); document.addEventListener("visibilitychange", arm); return () => { clearTimeout(timer); document.removeEventListener("visibilitychange", arm); }; } // useEffect(() => (focusIndex >= 0 && !panelShown ? whileVisible(1800, () => setPanelShown(true)) : undefined), [focusIndex, panelShown]);
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.
Applies to: other: animations that fire cues partway and can be cancelled
I assumed: a walk always reaches its marks, because only a new command ends it.
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.
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.
Evidence: commit 6fc7667; scripts/qa/site-frame.mjs, the resized case.

Size tiles

The 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.

LessonMy own mistakeL-EN2W Learned by the AI · Claude Opus 5.5

A key used to replay an animation remounted the size tiles and dropped keyboard focus: use element.animate()

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.
Snippet: import { useEffect, useRef } from "react"; // before: <SizeTiles key={pulse} ... /> to replay a CSS pulse, which remounted every tile under the focus export function useNudge(pulse: number) { const group = useRef<HTMLDivElement>(null); useEffect(() => { if (pulse <= 0) return; const a = group.current?.animate( [{ transform: "none" }, { transform: "translate3d(0,-2px,0) scale(1.012)", offset: 0.4 }, { transform: "none" }], { duration: 500, easing: "cubic-bezier(0.22,0.8,0.24,1)" }, ); return () => a?.cancel(); }, [pulse]); return group; // <div ref={group} role="radiogroup"> ...tiles... </div> }
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).
Applies to: other: React components that replay an animation by changing key
I assumed: a key was the simplest way to replay a CSS animation.
What happened: the click moved focus to a tile, then React remounted the tiles under it and focus fell to the page.
The fix: a one-off element.animate(). Nothing in React changes, so nothing loses its place.
Evidence: commit 0951249.

LessonMy own mistakeL-EW2W Learned by the AI · Claude Opus 5.5

A selected size tile ringed in the shoe's colour vanished on the day wall: ring it in the room's own ink

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.
Snippet: /* before (P3) */ .fl-tile[data-on] { background: var(--fl-led); border-color: var(--fl-led); color: var(--fl-led-ink); font-weight: 650; } /* after: the fill keeps the shoe's colour, the ring is the room's ink */ .fl-tile[data-on] { background: var(--fl-led); border-color: var(--fl-ink); box-shadow: inset 0 0 0 1px var(--fl-ink); color: var(--fl-led-ink); font-weight: 650; }
Check: measure the selected tile's edge against the pixels just outside it, for every shoe in both themes: at least 3:1.
Applies to: other: controls coloured from product data
I assumed: the shoe's colour would always stand out from the plaster.
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.
The fix: the ring in --fl-ink, the fill in the shoe's colour.
Evidence: commit badceaf, the contrast check.

The pill

The 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.

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.

components/floodlit/floodlit.tsxlines 603–648Open in the code browser

  const add = async () => {
    if (!focused) return;
    if (pill === "needs-size") {
      setTilePulse((n) => n + 1);
      setReserved({ kind: "hint", text: labels.chooseSizeFirst });
      roomRef.current?.pulse(focusIndex);
      tilesRef.current?.querySelector<HTMLButtonElement>('[tabindex="0"]')?.focus();
      return;
    }
    // Two clicks in one frame reach here before the state has changed: only the first counts.
    if (addingNow.current) return;
    addingNow.current = true;
    const size = focused.sizes.find((s) => s.eu === chosen) as ShoeSize;
    const token = ++addToken.current;
    setPill("adding");
    setReserved({ kind: "none" });
    const began = performance.now();
    let problem: string | null = null;
    try {
      await onAddToBag?.(focused, size);
    } catch (error) {
      problem = error instanceof Error && error.message ? error.message : labels.couldNotAdd;
    }
    const left = 500 - (performance.now() - began);
    if (left > 0) await new Promise((r) => setTimeout(r, left));
    addingNow.current = false;
    if (token !== addToken.current) return;
    if (problem) {
      setPill("error");
      setReserved({ kind: "error", text: problem });
      return;
    }
    const key = `${focused.id}:${size.eu}`;
    const existing = bag.find((l) => l.key === key);
    const label = `${labels.size} ${unit.toUpperCase()} ${sizeLabel(size, unit)}`;
    setBag(
      existing
        ? bag.map((l) => (l.key === key ? { ...l, qty: l.qty + 1 } : l))
        : [...bag, { key, shoeId: focused.id, name: focused.name, image: focused.photo.src, sizeLabel: label, eu: size.eu, variantId: size.variantId, price: focused.price, currency: focused.currency, ledColor: focusedColour, qty: 1 }],
    );
    setPill("added");
    setReserved({ kind: "added" });
    setLive(labels.addedLive(focused.name));
    roomRef.current?.pulse(focusIndex);
    addedTimer.current = setTimeout(() => setPill("another"), 2400);
  };

LessonMy own mistakeL-GS38 Learned by the AI · Claude Opus 5.5

Both clicks of a fast double click got past a state check: guard async re-entry with a ref set at once

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.
Snippet: import { useRef, useState } from "react"; type PillState = "ready" | "adding" | "added" | "error"; export function useAddOnce(addToBag: () => Promise<void>) { const [pill, setPill] = useState<PillState>("ready"); const addingNow = useRef(false); const token = useRef(0); // choosing another size bumps it, so a late answer is ignored const add = async () => { // before: if (pill === "adding") return; if (addingNow.current) return; addingNow.current = true; const mine = ++token.current; setPill("adding"); try { await addToBag(); if (mine === token.current) setPill("added"); } catch { if (mine === token.current) setPill("error"); } finally { addingNow.current = false; } }; return { pill, add }; }
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.
Applies to: other: React click handlers that guard async work on state
I assumed: ignoring clicks while the state said "adding" would stop a second add.
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.
The fix: a ref, set synchronously. State is for what shows.
Evidence: commit 0951249, the buying check.

LessonMy own mistakeL-CSYK Learned by the AI · Claude Opus 5.5

A pill outline in a stretched viewBox went pointed at 1020 px wide: drop the viewBox

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.
Snippet: // before (P3) <svg className="fl-pill-line" aria-hidden="true" preserveAspectRatio="none" viewBox="0 0 300 56"> <rect x="0.75" y="0.75" width="298.5" height="54.5" rx="27.25" ry="27.25" vectorEffect="non-scaling-stroke" /> </svg> // after: no viewBox, so rx and ry are real pixels at any width <svg className="fl-pill-line" aria-hidden="true"> <rect width="100%" height="100%" rx="27.25" ry="27.25" /> </svg>

/* pulled in by half the stroke, so the whole line stays inside the 56 px pill */ .fl-pill-line { position: absolute; inset: 0.75px; width: calc(100% - 1.5px); height: calc(100% - 1.5px); overflow: visible; fill: none; stroke: var(--fl-line); stroke-width: 1.5; }
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.
Applies to: other: SVG shapes stretched with preserveAspectRatio none
I assumed: vector-effect: non-scaling-stroke would keep the outline true at any width.
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.
The fix: no viewBox, percentage sizes, and the svg inset by half the stroke.
Evidence: commit badceaf.

Why 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.

The title, the bag, and the host's header

The 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:

components/floodlit/floodlit.tsxlines 650–669Open in the code browser

  // The title fits by rule: it never overlaps the shoe and is never cut off.
  useLayoutEffect(() => {
    const el = titleRef.current;
    if (!el || !box || !focused) return;
    const margin = Math.max(16, size.w * 0.04);
    const roomW = rtl ? size.w - box.panelLeft : box.panelLeft;
    const forWidth = stacked ? size.w - margin * 2 - 48 : Math.max(180, roomW - margin - 24);
    // From below the back button to just above the top of the shoe's picture. A text line's box is about 1.1 em.
    const titleTop = detailTop + Math.min(28, Math.max(12, window.innerHeight * 0.03)) + 50;
    const forHeight = stacked ? 36 : Math.max(36, (box.y0 + (box.y1 - box.y0) * 0.06 - titleTop - 6) / 1.1);
    el.style.fontSize = "100px";
    el.style.whiteSpace = "nowrap";
    const width = el.scrollWidth;
    el.style.fontSize = "";
    el.style.whiteSpace = "";
    const oneLine = Math.min(84, (100 * forWidth) / Math.max(1, width), forHeight);
    // A name too long for one line at a readable size wraps instead of being cut.
    setTitleWrap(oneLine < 18);
    setTitleSize(Math.max(18, oneLine));
  }, [focused, box, size.w, detailTop, stacked, rtl]);

LessonMy own mistakeL-372K Learned by the AI · Claude Opus 5.5

A title that fit its width still touched a tall shoe: test it against the picture's own opaque pixels

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.
Snippet: // box: the shoe's picture on screen through the focus frame (y0 its top). detailTop: the host's header. // before (P3): const roomForHeight = Math.max(36, boxInfo.y0 + (boxInfo.y1 - boxInfo.y0) * 0.14 - detailTop - 92); export function titleSize(box: { y0: number; y1: number }, detailTop: number, viewportH: number, stacked: boolean, forWidth: number, widthAt100px: number) { const titleTop = detailTop + Math.min(28, Math.max(12, viewportH * 0.03)) + 50; // below the back button // 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. const forHeight = stacked ? 36 : Math.max(36, (box.y0 + (box.y1 - box.y0) * 0.06 - titleTop - 6) / 1.1); const oneLine = Math.min(84, (100 * forWidth) / Math.max(1, widthAt100px), forHeight); return { fontSize: Math.max(18, oneLine), wrap: oneLine < 18 }; // too long for one readable line: wrap }
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).
Applies to: other: text laid out above cut-out images of varying height
I assumed: allowing for the empty top 14% of the picture's frame would keep the title clear.
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.
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.
Evidence: commit badceaf.

The 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.

LessonMy own mistakeL-SH6W Learned by the AI · Claude Opus 5.5

Glass shows what is under it: step the page back when the bag opens, and keep a phone's sheet solid

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.
Snippet: /* before: the bag in glass over a panel that stayed as it was, and on phones the sheet in the same glass: .fl-body[data-stack] .fl-panel { background: var(--fl-glass); } with --fl-glass: rgb(22 21 25 / 0.94) */ /* after: the page steps back with the room when the bag opens */ .fl-focus { transition: opacity 0.32s ease; } .fl-body[data-bag] .fl-focus { opacity: 0.32; } .fl-body[data-bag] .fl-panel { opacity: 0; transition: opacity 0.2s ease; pointer-events: none; } /* and a phone's sheet, over a room that stays lit, is solid */ .fl-body[data-stack] .fl-panel { background: var(--fl-sheet); } /* #18171b at night, #e9e5dd by day */
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.
Applies to: other: translucent drawers and sheets over live content
I assumed: glass over the panel would look rich and stay readable.
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.
The fix: the bag can be glass because the world dims behind it; the sheet sits on a lit room, so it is solid.
Evidence: commits 0951249 and badceaf.

LessonMy own mistakeL-14XP Learned by the AI · Claude Opus 5.5

The store's header sat on the focus view's corners: pass the host's header height and look at the whole page

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.
Snippet: // before: the demo store had a 72 px header and did not say so // <Floodlit shoes={shoes} /> <Floodlit shoes={shoes} detailTop={72} />

/* Inside, everything at the top starts below the host's header. */ .fl-stage-top { position: absolute; top: calc(var(--fl-detail-top, 0px) + clamp(12px, 3vh, 28px)); }
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.
Applies to: other: components that fill the window under a host's header
I assumed: the demo's header and the component's controls would not meet.
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.
The fix: pass it, and look at a screenshot of the whole page, not only at what tests can read.
Evidence: commit 0951249.

Phones: ordinary scrolling moves the camera

On 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:

components/floodlit/floodlit.tsxlines 297–328Open in the code browser

  // On a phone the wall is taller than the window. The page scrolls as usual, and the camera follows it: the
  // distance between the sticky stage and the shoes' plane is exactly how far down the wall we are.
  useEffect(() => {
    if (!tall) return;
    const onScroll = () => {
      const stage = stickRef.current?.getBoundingClientRect().top ?? 0;
      const plane = planeRef.current?.getBoundingClientRect().top ?? 0;
      roomRef.current?.setScroll(stage - plane);
    };
    onScroll();
    window.addEventListener("scroll", onScroll, { passive: true });
    return () => window.removeEventListener("scroll", onScroll);
  }, [tall, gl, size.h]);

  // While a shoe is open on a phone, the page behind stays still. Where the page has a classic scrollbar (a computer,
  // or the site's preview at phone width on one), locking it would take the scrollbar away and make the page wider:
  // the room would lay out again in mid-walk. So its gutter stays.
  useEffect(() => {
    if (!tall || focusIndex < 0) return;
    const html = document.documentElement;
    const before = { overflow: html.style.overflow, gutter: html.style.scrollbarGutter, overscroll: html.style.overscrollBehavior };
    const bar = window.innerWidth - html.clientWidth;
    html.style.overflow = "hidden";
    // A drag down steps back here; on a page that cannot scroll it would otherwise be a pull-to-refresh.
    html.style.overscrollBehavior = "none";
    if (bar > 0) html.style.scrollbarGutter = "stable";
    return () => {
      html.style.overflow = before.overflow;
      html.style.scrollbarGutter = before.gutter;
      html.style.overscrollBehavior = before.overscroll;
    };
  }, [tall, focusIndex]);

The 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.

LessonMy own mistakeL-VVST Learned by the AI · Claude Opus 5.5

Locking a page's scroll took its scrollbar away and widened the page: the 3D room laid out again in mid-walk

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.
Snippet: import { useEffect } from "react"; // before: html.style.overflow = "hidden" alone; with a classic 15 px scrollbar the wall grew from 373 to 388 px export function usePageLock(locked: boolean) { useEffect(() => { if (!locked) return; const html = document.documentElement; const before = { overflow: html.style.overflow, gutter: html.style.scrollbarGutter, overscroll: html.style.overscrollBehavior }; const bar = window.innerWidth - html.clientWidth; // 0 where scrollbars overlay, as on phones html.style.overflow = "hidden"; html.style.overscrollBehavior = "none"; if (bar > 0) html.style.scrollbarGutter = "stable"; // only where there was a bar, or a gutter would appear return () => { html.style.overflow = before.overflow; html.style.scrollbarGutter = before.gutter; html.style.overscrollBehavior = before.overscroll; }; }, [locked]); }
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).
Applies to: other: scroll locks with overflow hidden on pages with classic scrollbars
I assumed: locking the page's scroll changes nothing about its layout.
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).
The fix: the gutter stays while the page is locked, set only where there was a bar to begin with.
Evidence: commit 6fc7667; scripts/qa/site-frame.mjs: the width held at 373 px through opening and closing.

LessonThe tools and the machineL-2R25 Learned by the AI · Claude Opus 5.5

Headless Chrome hides scrollbars, so no test saw the phone preview freeze: test the host's frame with real ones

playwright-core

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.
Snippet: import { chromium } from "playwright-core"; // before: chromium.launch({ channel: "chrome", headless: true }), which adds --hide-scrollbars const browser = await chromium.launch({ channel: "chrome", headless: true, ignoreDefaultArgs: ["--hide-scrollbars"] }); try { const page = await browser.newPage({ viewport: { width: 1280, height: 1000 } }); // The host's preview: the built page in a sandboxed frame at the phone width it offers. await page.setContent(`<iframe id="f" sandbox="allow-scripts" src="http://localhost:6702/preview.html" style="width:390px;height:765px;border:0"></iframe>`); const frame = await (await page.waitForSelector("#f")).contentFrame(); await frame.waitForSelector('.fl-body[data-gl="ready"]'); const bar = await frame.evaluate(() => innerWidth - document.documentElement.clientWidth); console.log("scrollbar", bar); // 15 here on Windows; always 0 with the default launch } finally { await browser.close(); }
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.
Applies to: other: headless Chromium from Playwright (seen with playwright-core 1.64)
I assumed: a headless page at a phone's width shows what the site's phone-width preview shows.
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.
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.
Evidence: commit 6fc7667.

LessonMy own mistakeL-JREP Learned by the AI · Claude Opus 5.5

Padding on a sticky element's parent pushed the whole stage down 72 px: put the offset on the content

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.
Snippet: @container fl (max-width: 699.98px) { /* before: .fl-body { padding-top: var(--fl-detail-top, 0px); } with the sticky .fl-stick as its first child */ .fl-stick { position: sticky; top: 0; height: 100svh; margin-bottom: -100svh; /* the stage takes no room, so the wall scrolls under it */ } .fl-plane { position: relative; margin-top: var(--fl-detail-top, 0px); /* the header offsets the wall, not the stage */ } }
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.
Applies to: other: position sticky inside a padded parent
I assumed: padding the body was the plain way to clear the store's header.
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.
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.
Evidence: commit badceaf.

In 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.

components/floodlit/camera.tslines 73–90Open in the code browser

export function focusFrame(slot: Slot, width: number, height: number, rtl = false, top = 0): FocusFrame {
  const f = focalLength(width);
  const { card } = slot;
  if (isStacked(width, height)) {
    // The shoe in the upper part, the panel as a sheet below. Neighbours may show at the sides.
    // Clear of the host's header and the row with the back button, and above the walking buttons.
    const visible = card.h * 0.9;
    // The slab's thickness and its front edge count too: the buttons sit under the slab, not on it.
    const under = 26;
    const ceiling = Math.max(height * 0.1, top + 52);
    const floor = sheetTop(height) - 62;
    const scale = Math.min((width * 0.9) / card.w, Math.max(height * 0.2, floor - ceiling) / (visible + under));
    const spare = Math.max(0, floor - ceiling - (visible + under) * scale);
    const baseY = slot.slab.y;
    const screenY = ceiling + spare * 0.5 + visible * scale;
    const z = SHOE_Z + f / scale;
    const y = baseY - (visible * scale * 0.5) / scale;
    const screenCamY = screenY - (baseY - y) * scale;

In 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.

LessonMy own mistakeL-KEX9 Learned by the AI · Claude Opus 5.5

On a phone the sheet came up empty 0.7 s before its words: let a container enter with what is on it

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.
Snippet: /* before: only the words waited (.fl-rise); the sheet's dark background was up from the tap */ .fl-body[data-stack] .fl-panel { background: var(--fl-sheet); transition: opacity 0.3s ease, transform 0.42s var(--fl-ease); } /* until the cue, hidden and 28 px low. Walking along (data-along) it stays, and only its words change. */ .fl-body[data-stack] .fl-focus:not([data-show]):not([data-along]) .fl-panel { opacity: 0; transform: translate3d(0, 28px, 0); transition: opacity 0.16s ease, transform 0.16s ease; } @media (prefers-reduced-motion: reduce) { .fl-body[data-stack] .fl-panel, .fl-body[data-stack] .fl-focus:not([data-show]):not([data-along]) .fl-panel { transform: none; transition: opacity 0.16s linear; } }
Check: take screenshots back to back after a tap at 390×844: no still shows the sheet without its words.
Applies to: other: sheets and panels whose contents enter on a cue
I assumed: contents that enter on a cue make the panel enter on it too.
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.
The fix: the sheet itself waits for the cue and rises with its words.
Evidence: commit 6fc7667; scripts/qa/motion-sweep.mjs, the open stills.

LessonMy own mistakeL-MSWM Learned by the AI · Claude Opus 5.5

A swipe timed in its handlers is only as quick as a busy thread: time it with the events' own timeStamp

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.
Snippet: // walk(forward) and close() are the component's own actions. const touchStart = useRef<{ x: number; y: number; t: number } | null>(null); const onTouchStart = (e: React.TouchEvent) => { const t = e.touches[0]; touchStart.current = { x: t.clientX, y: t.clientY, t: e.timeStamp }; // before: t: performance.now() }; const onTouchEnd = (e: React.TouchEvent) => { const from = touchStart.current; touchStart.current = null; if (!from || e.timeStamp - from.t > 700) return; // before: performance.now() - from.t const t = e.changedTouches[0]; const dx = t.clientX - from.x, dy = t.clientY - from.y; if (Math.abs(dx) > 48 && Math.abs(dx) > Math.abs(dy) * 1.4) walk(dx < 0); else if (dy > 70 && dy > Math.abs(dx) * 1.4) close(); };

// A test over CDP: each event stamped as a finger would make it. const t0 = Date.now() / 1000; await cdp.send("Input.dispatchTouchEvent", { type: "touchStart", touchPoints: [{ x: 300, y: 300 }], timestamp: t0 }); await cdp.send("Input.dispatchTouchEvent", { type: "touchMove", touchPoints: [{ x: 100, y: 300 }], timestamp: t0 + 0.2 }); await cdp.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [], timestamp: t0 + 0.216 });
Check: dispatch a 0.2 s swipe with timestamps while the page is busy: the walk starts (on all seven sizes here).
Applies to: other: touch gestures with a time limit, other: tests that drive touch over CDP
I assumed: a handler runs when the finger moves, so its clock is the finger's.
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.
The fix: timeStamp in the component, and stamped events in the test.
Evidence: commit 6fc7667; scripts/qa/motion-sweep.mjs.

LessonMy own mistakeL-KWNT Learned by the AI · Claude Opus 5.5

A tablet held upright got the desktop's side panel: stack the focus view by shape, not by width alone

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).
Snippet: export const TALL_WIDTH = 700; // before: return width < TALL_WIDTH; export function isStacked(width: number, height: number): boolean { return width < TALL_WIDTH || (width < 1100 && height > width * 1.1); } /** Where the sheet starts in a stacked view: half the height, or 440 px from the bottom on a tall one. */ export function sheetTop(height: number): number { return Math.max(height * 0.5, height - 440); }
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.
Applies to: other: responsive layouts that switch on width alone
I assumed: under 700 px is a phone, and anything wider can hold a panel beside the shoe.
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.
The fix: stack whenever the room is too narrow or upright.
Evidence: commit badceaf.

LessonMy own mistakeL-0TMG Learned by the AI · Claude Opus 5.5

A clipping body hid a control pushed off screen from the sideways-scroll check: test each control's box

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.
Snippet: // Playwright. before: only document.documentElement.scrollWidth <= clientWidth, which passes under overflow: clip async function rectOf(page, selector) { const r = await page.locator(selector).first().boundingBox(); return r ? { x0: r.x, y0: r.y, x1: r.x + r.width, y1: r.y + r.height } : null; } export async function controlsOnScreen(page) { const { width, height } = page.viewportSize(); const next = await rectOf(page, ".fl-stage-foot .fl-icon-button:last-child"); const pill = await rectOf(page, ".fl-pill"); if (!next || next.x1 > width + 0.5) throw new Error(`the next button ends at ${next?.x1} of ${width}`); if (!pill || pill.y0 < 0 || pill.y1 > height + 0.5) throw new Error(`the pill is at ${pill?.y0} to ${pill?.y1} of ${height}`); }
Check: run it in focus at 320 px wide on the shoe with the longest name: it throws nothing.
Applies to: other: layout tests in any browser automation
I assumed: no sideways scroll meant everything fitted.
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.
The fix: compact view labels at that size, and this check for every control that must be there.
Evidence: commit badceaf.

Access, and text over light

Everything 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:

LessonMy own mistakeL-CTFN Learned by the AI · Claude Opus 5.5

Focus sent into a list that is still inert goes nowhere: move it after the state that lifts inert commits

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.
Snippet: import { useEffect, useRef, useState, type RefObject } from "react"; export function useReturnFocus(links: RefObject<(HTMLAnchorElement | null)[]>) { const [open, setOpen] = useState(-1); const returnTo = useRef(-1); // before: close() called links.current[open]?.focus() at once, while <ul inert> was still in the DOM const close = () => { returnTo.current = open; setOpen(-1); }; useEffect(() => { if (open < 0 && returnTo.current >= 0) { links.current?.[returnTo.current]?.focus({ preventScroll: true }); returnTo.current = -1; } }, [open, links]); return { open, setOpen, close }; // render the wall as <ul inert={open >= 0 || undefined}> }
Check: open a shoe, open the bag, press Esc twice: document.activeElement is the shoe's link on the wall.
Applies to: other: dialogs that set inert on the page behind them (seen with React 19)
I assumed: focusing the link in the close handler would work, as it does without inert.
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.
The fix: remember where focus should go, and move it once the commit has lifted inert.
Evidence: commit 0951249.

A 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:

LessonThe tools and the machineL-SB37 Learned by the AI · Claude Opus 5.5

axe passed text over a WebGL canvas that failed 39 of 69 states: measure the real pixels behind it

axe-core

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.
Snippet: // Playwright. First read each text's rectangles (Range.getClientRects, clipped by any scrolling parent) and colour. const tag = await page.addStyleTag({ content: ".fl-root * { color: transparent !important; transition: none !important; }" }); const png = (await page.screenshot({ type: "png" })).toString("base64"); await tag.evaluate((n) => n.remove()); // Then, in the page, draw the png into a 2D canvas and test each text against the pixels behind it. const lin = (v) => { const u = v / 255; return u <= 0.04045 ? u / 12.92 : ((u + 0.055) / 1.055) ** 2.4; }; const lum = (r, g, b) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b); function worstRatio(ctx, [x, y, w, h], [r, g, b, a]) { const d = ctx.getImageData(x, y, w, h).data; const ratios = []; for (let i = 0; i < d.length; i += 4) { // a translucent colour lands on the pixel behind it const fg = lum(r * a + d[i] * (1 - a), g * a + d[i + 1] * (1 - a), b * a + d[i + 2] * (1 - a)); const bg = lum(d[i], d[i + 1], d[i + 2]); ratios.push((Math.max(fg, bg) + 0.05) / (Math.min(fg, bg) + 0.05)); } ratios.sort((p, q) => p - q); return ratios[Math.floor(ratios.length * 0.01)] ?? 99; // the worst 1% }
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).
Applies to: other: contrast checkers that read CSS colours (seen with axe-core)
I assumed: axe being clean meant the text was readable.
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.
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.
Evidence: commit badceaf.

What was measured, and what was not

All of it on one laptop with an Intel Iris Plus, in installed Chrome, on a production build:

Check	Result
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
Buying, in focus and in the bag	31 checks pass
Text over the lit room, both themes	At least 4.5:1 in 67 states; controls at least 3:1; axe clean
Server posters against the canvas	Largest offset 1 px
Camera speed through six quick commands	Largest change between two frames about 4 px
Title against the shoes	0 overlapping samples, ten shoes at ten sizes
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
Seven phone and tablet sizes, mouse and touch, moving	67 checks pass: opening, walking along, swipes, the bag, closing, scrolling

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.

Make it yours

npx shadcn@latest add https://upfork.dev/r/3d-shoe-showroom-webgl-react.json

Free: no account or token needed.

The 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.

Written by

Ramin ValadanProved GitHub account and website, confirmed e-mail: checked by UpFork

Full-stack developer and founder of UpFork · .NET, React/Next.js and WebGL

Follow Their page and products

Did it help? Like it, or rate it.

No ratings yet

Comments

0 comments

No comments yet. Questions, what you built with it, what could be better: its developer reads them.

This version is signed in UpFork’s ledger as entry #731, so anyone can check it hasn’t changed since it was published. Check it.

Something wrong in it, or against the rules? Report it.

A camera that walks up to a shoe: springs, buying inside a 3D room, and a wall placed by CSS alone

Floodlit — 3D Sneaker & Shoe Showroom for React with a WebGL Product Gallery

What this one is about

The walk up: anchored on the shoe

Springs that never snap

Looking around without turning a photograph

The wall is HTML, placed by CSS alone

Buying inside the room

Size tiles

The pill

The title, the bag, and the host's header

Phones: ordinary scrolling moves the camera

Access, and text over light

What was measured, and what was not

Make it yours

Comments

Read next

A 3D shoe showroom in raw WebGL2: line lights, clear acrylic, soft shadows and a worker

Cut shoes out of photos so they stand exactly on a shelf: a background removal pipeline and traps

How to make a product fly from a grid to its detail view in React, with no animation library