Hangline: a 3D clothing rail in pure CSS, with one camera, swinging hangers and an endless rail

How Hangline hangs garments on a steel rail in CSS 3D alone: one camera in numbers, one number per piece, wall shadows, hanger springs and an endless rail, with 19 lessons.

Ramin Valadan29 min read14 Nov 2026

Written with AI: Claude Opus 5.5, through Claude

19 lessons learned building it

No ratings yet

0 Save

The product

Hangline — 3D Clothing Store Product Carousel for React, with Sizes, Bag & Accessory Tray

Free · Component

Get it

The product

Hangline — 3D Clothing Store Product Carousel for React, with Sizes, Bag & Accessory Tray

Free · Component

An endless 3D clothing rail for fashion stores in React: garments hang in true perspective, the piece in front faces you, and sizes, add to bag, a detail view and an accessory tray sit beside it. CSS 3D, no 3D library, light and dark.

npx shadcn@latest add https://upfork.dev/r/clothing-store-product-carousel-react.json

Get it Live preview

On this page

What it is

Hangline is a clothing rail for fashion stores, as a React component. Garments hang on one steel rail in true perspective. The piece in front faces you from a short face-out arm, the rest wait along the rail edge on, and each casts its own soft shadow on the wall. Step, drag or flick, and the rail travels: the pieces swing a little on their hangers and settle. After the last piece comes the first again.

There is no 3D library and no canvas. The room is DOM elements and CSS transforms under one CSS camera, the pictures are plain <img> elements, and the component's JavaScript is 21.6 KB gzipped without React. This article is about the rail: the camera's maths, the one number that places every piece, the springs, the shadows, steel that Chrome would otherwise draw with stair steps, and an endless rail that never shows its seam. Each part comes with what surprised us while building it.

Live preview

Preview of Hangline — 3D Clothing Store Product Carousel for React, with Sizes, Bag & Accessory Tray

The demo rail holds 14 garments and a tray of 6 accessories. Every garment and accessory picture in the demo is AI-generated, and none of them is covered by the code's MIT licence. The companion article covers the pictures: how they were cut out so that they hang true, with their hook points, shadow masks and outlines.

One camera, in numbers

The whole room sits in one stage with CSS perspective. Inside it, a transform-style: preserve-3d world places every piece with translate3d and rotateY. The browser does the projection, but the component needs to know where anything lands on screen: the wall shadows, the hover tag, the steel, and the hit tests. So layout.ts repeats the browser's projection in plain numbers.

For a camera at distance P with its origin at (ox, oy), a point at depth z (positive towards the viewer) is drawn at scale s = P / (P − z), and its screen position is ox + (x − ox)·s, oy + (y − oy)·s. That is exactly what perspective: P with perspective-origin: ox oy does:

components/hangline/layout.tslines 40–51Open in the code browser

export function project(g: RoomGeometry, p: Vec3): { x: number; y: number; s: number } {
  const s = g.P / (g.P - p.z);
  return { x: g.ox + (p.x - g.ox) * s, y: g.oy + (p.y - g.oy) * s, s };
}

const rad = (d: number) => (d * Math.PI) / 180;

export function railPoint(g: RoomGeometry, t: number): Vec3 {
  // t along the rail from the arm root, positive towards the back right
  const a = rad(RAIL_ANGLE);
  return { x: g.armRoot.x + t * Math.cos(a), y: g.railY, z: g.armRoot.z - t * Math.sin(a) };
}

The choice that matters most is where z = 0 lies. It is the plane of the front piece, which hangs at scale 1. Every queued piece is further back, so it is drawn smaller than its layout size. The browser therefore only ever scales a picture down, and the front piece is never blurred by an upscale.

The rest of the room follows from the scene's height H. The camera sits 1.55 H away (1.7 H on a phone). A typical garment is 0.7 H tall. The rail runs 30° from the wall plane, and the face-out arm reaches 0.56 H towards you. A queued piece turns −70° on its hook, so it shows its front edge to the front left. The rail's front end is not a constant: the code walks forwards along the rail until the projected point is past the frame's left edge.

components/hangline/layout.tslines 63–99Open in the code browser

export function roomGeometry(W: number, H: number, mode: Mode, stageW = W, stageH = H, maxVisible = Infinity): RoomGeometry {
  const phone = mode === "phone";
  const P = (phone ? 1.7 : 1.55) * H;
  const frontHeight = (phone ? 0.7 : 0.7) * H; // a typical canvas, from the hook point to the hem
  const pxPerSource = frontHeight / REF_CANVAS;
  const hookH = 0.088 * frontHeight;
  const railY = (phone ? 0.075 : 0.085) * H;
  const frontX = (phone ? 0.38 : 0.36) * W;
  const arm = (phone ? 0.5 : 0.56) * H;
  const front = { x: frontX, y: railY, z: 0 };
  const armRoot = { x: frontX, y: railY, z: -arm };
  const g: RoomGeometry = {
    W, H, stageW, stageH, P,
    ox: (phone ? 0.46 : 0.44) * W,
    oy: (phone ? 0.34 : 0.36) * H,
    railY, hookH, pxPerSource, frontHeight, front, armRoot,
    railStart: armRoot, railEnd: armRoot,
    wallZ: 0,
    gap: (phone ? 0.085 : 0.078) * H,
    firstGap: (phone ? 0.2 : 0.17) * H,
    light: { x: 0.3, y: 0.2, z: -1 },
    visible: Math.min(phone ? 6 : 11, maxVisible),
  };
  // the wall bracket, a little past the last visible piece
  const endT = g.firstGap + g.gap * (g.visible + 0.9); // just past the last piece, which takes the wall's tone
  g.railEnd = railPoint(g, endT);
  g.wallZ = g.railEnd.z - 0.05 * H;
  // the front-left end: walk forwards until the rail is past the frame's left edge (or close to the camera)
  let t = 0;
  while (t > -4 * H) {
    const p = railPoint(g, t);
    if (project(g, p).x < -0.05 * W || p.z > 0.5 * P) break;
    t -= 0.01 * H;
  }
  g.railStart = railPoint(g, t);
  return g;
}

The stage and its worlds are a few lines of CSS. The stage is not preserve-3d itself, so each .hl-world is flattened into it in DOM order. That is what later lets a flat layer of steel sit between the wall's world and the pieces' world.

components/hangline/hangline.csslines 265–281Open in the code browser

.hl-stage {
  position: absolute;
  inset: 0;
}

.hl-world {
  position: absolute;
  inset: 0;
  transform-style: preserve-3d;
}

.hl-world > * {
  position: absolute;
  left: 0;
  top: 0;
  transform-origin: 0 0;
}

Every piece from one number

Pieces are never swapped, re-ordered or re-mounted. One number places each of them: u = index − railPosition. When the rail moves, the position changes, and every u changes with it:

components/hangline/rail.tslines 1–13Open in the code browser

// Where a piece hangs for any rail position. One number, u = (the piece's index) - (the rail's position),
// says where every piece is; the rail moves by changing the position, never by swapping pieces.
//
//   u >= 1         queued: slot u - 1 on the rail, turned on its hook
//   0.5 <= u < 1   sliding along the rail from the first slot to the arm's root
//   0 <= u < 0.5   out along the face-out arm, turning to face you (u = 0 is the front)
//   -0.25 <= u < 0 back along the arm to its root, turning back
//   -0.5 <= u < -0.25  along the rail to the front left, out of the frame
//   u < -0.5       gone (off the frame at the left)
//
// The incoming piece reaches the arm only after the outgoing one has left it (they are one unit of u apart,
// and the arm is used for u in [-0.25, 0.5)), so two hangers never share the arm. Every hook's curl rests on
// the rail or on the arm for every u, by construction.

The face-out arm is what makes this hard. The front piece leaves along the arm while the next one arrives along it. If both moved at once, two hangers would pass through each other on one bar.

The arm therefore belongs to u in [−0.25, 0.5). The outgoing piece holds it from 0 down to −0.25, and the incoming one from 0.5 down to 0. Pieces are exactly one unit of u apart and the arm's range is 0.75 long, so two pieces are never on the arm at once. For one instant in mid-step the front is empty, and it reads as a hand-over:

components/hangline/rail.tslines 36–58Open in the code browser

export function pose(g: RoomGeometry, u: number, shift = 0, aside = 0): Pose {
  if (u >= 0.5) {
    let t = u >= 1 ? g.firstGap + g.gap * (u - 1) + shift : g.firstGap * ((u - 0.5) / 0.5) + shift;
    let visible = u <= g.visible + 0.25;
    if (aside > 0) {
      const far = g.firstGap + g.gap * (g.visible + 0.25);
      const end = exitT(g) * 1.08;
      t -= aside * (far - end);
      if (t <= end + 0.5) visible = false;
    }
    return { at: railPoint(g, t), turn: QUEUE_TURN, visible, onArm: false };
  }
  if (u >= 0) {
    const a = u / 0.5; // 1 at the root, 0 at the front
    return { at: lerp3(g.front, g.armRoot, a), turn: QUEUE_TURN * smooth(a), visible: true, onArm: true };
  }
  if (u >= -0.25) {
    const a = -u / 0.25;
    return { at: lerp3(g.front, g.armRoot, a), turn: QUEUE_TURN * smooth(a), visible: true, onArm: true };
  }
  const b = Math.min(1, (-u - 0.25) / 0.25);
  return { at: railPoint(g, exitT(g) * b), turn: QUEUE_TURN, visible: u >= -0.5, onArm: false };
}

Pieces further down the line take the wall's tone, by aerial perspective. They are never see-through, because an outgoing garment that fades shows as a ghost over the text. Over each picture lies a layer of the wall's colour, masked by the garment's own picture, and its opacity follows the depth. It reaches 1 at the far end of the line, where the piece is fully the wall and can be hidden without a pop:

components/hangline/room.tsxlines 142–152Open in the code browser

          if (vis) {
            el.style.transform = `translate3d(${p.at.x.toFixed(2)}px, ${p.at.y.toFixed(2)}px, ${p.at.z.toFixed(2)}px) rotateY(${turn.toFixed(3)}deg) rotateZ(${swing.toFixed(3)}deg)`;
            const depth = depthOf(g, u);
            // aerial perspective: up to about 10% of the wall's tone, and at the far end of the line the piece
            // takes the wall's tone completely, so it leaves the view without ever being see-through
            const tint = u <= 0.25 ? 0 : depth <= 1 ? 0.03 + 0.1 * depth : Math.min(1, 0.13 + (depth - 1) * 0.87 * 1.0001);
            const t = tintEls.current[i];
            if (t) t.style.setProperty("--hl-t", tint.toFixed(3));
            const c = contactEls.current[i];
            if (c) c.style.opacity = u > 0.7 ? "" : "0";
          }

None of this re-renders React. The room renders once, and on every animation frame paint() writes each piece's transform, tint and shadows straight to the DOM.

A callback that outlives its render

paint() is rebuilt whenever the geometry changes. A picture's decode, though, ends long after the render that started it, and the effect that waits for it runs once, when the picture mounts.

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

A mount-only effect waiting for an image decode kept the first render's callback: late images redrew from stale geometry

react@19.2

Rule: If late-loading images redraw a scene from stale sizes, a mount-only effect is holding an old callback. Make the callback stable, and have it call the latest function through a ref.
Snippet: // before: the image's decode effect runs once, so it keeps the onReady, and the paint, it saw at mount const onReady = useCallback((i: number) => { ready.current[i] = true; paint(lastMotion.current); }, [paint]); useEffect(() => { settle(img).then((ok) => ok && onReady()); }, []); // after: whichever onReady the effect kept, it calls the paint of the latest render const paintRef = useRef(paint); paintRef.current = paint; const onReady = useCallback((i: number) => { ready.current[i] = true; paintRef.current(lastMotion.current); }, []);
Check: Load at phone size with a slow network: when the pictures arrive, the pieces stand in their places, not all at one point.
Applies to: react@>=19.2 <20
I assumed: giving onReady its dependency on paint kept it current.
What happened: on a phone every piece was drawn at one point. Each picture's decode effect ran once, at mount, and kept the callback of that render, whose paint used a scene measured 0 px tall before the phone's layout applied. Each picture that decoded later repainted the whole rail from that geometry.
The fix: a callback handed to a mount-only effect never holds state. It calls the latest function through a ref that every render updates.
Evidence: commit 75897d9; room.tsx, onReady and paintRef.

components/hangline/room.tsxlines 211–220Open in the code browser

  // The decode of each photograph ends long after its first render, so the callback must reach the paint of
  // the room as it is then, not as it was: a stale paint from before the phone's layout (a scene 0 px tall)
  // drew every piece at one point when the pictures arrived.
  const paintRef = useRef(paint);
  paintRef.current = paint;
  const onReady = useCallback((i: number) => {
    if (ready.current[i]) return;
    ready.current[i] = true;
    if (lastMotion.current) paintRef.current(lastMotion.current);
  }, []);

Light on the wall

There is one light. Its direction is L = (0.3, 0.2, −1): it travels right, down and into the wall. A point's shadow is where the line along L from it meets the wall plane at wallZ: t = (wallZ − z) / L.z, and the shadow is p + t·L.

components/hangline/layout.tslines 106–110Open in the code browser

/** A point's shadow on the wall, along the light. */
export function onWall(g: RoomGeometry, p: Vec3): Vec3 {
  const t = (g.wallZ - p.z) / g.light.z;
  return { x: p.x + g.light.x * t, y: p.y + g.light.y * t, z: g.wallZ };
}

That direction was not the first one.

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

A wall shadow cast along the line of sight hides behind the object that casts it, once perspective shrinks it

other:CSS3Dperspectivescenes(anybrowser)

Rule: If the nearest object in a perspective scene seems to cast no shadow on the wall, the light runs too close to the view axis. Tilt it sideways and down until the shadow clears the object.
Snippet: // before: the light mostly travels into the wall light: { x: 0.11, y: 0.15, z: -1 }, // after: steeper, so the front piece's shadow falls down and to the right light: { x: 0.3, y: 0.2, z: -1 },
Check: A still of the scene at rest: the front piece's soft shadow shows below and right of it, and the queue's shadows stay tight.
Applies to: other: CSS 3D perspective scenes (any browser)
I assumed: a light travelling mostly into the wall, like a gallery spot behind the viewer, would give every piece a soft shadow.
What happened: the front piece's shadow landed almost straight behind it. Perspective then shrank the shadow towards the vanishing point, and it hid entirely behind the jacket. The one piece that most needed a shadow showed none.
Why: the front piece is the furthest from the wall, so its shadow travels the furthest along the light. A light along the view sends that travel straight back, where the piece itself covers it.
The fix: a steeper light, x 0.3 and y 0.2 per unit of depth. The queued pieces hang close to the wall, so their shadows barely move.
Evidence: commit a8babd6; stills at 1440 × 900 at 2×, before and after.

The shadow of a turned piece

A garment's shadow is its own alpha, blurred, drawn on the wall plane. It cannot just be moved, though, because a queued piece is turned −70°.

Take a point at local offset x across the picture. On a piece turned by θ it lands at x·cos θ across, and x·(−sin θ) towards the viewer. Cast onto the wall along L, that depth moves it a further (L.x / −L.z)·x·(−sin θ) across and (L.y / −L.z)·x·(−sin θ) down. So the shadow is the flat mask under a shear, matrix(a, b, 0, 1, 0, 0), where:

a = cos θ + (L.x / −L.z)·(−sin θ)
b = (L.y / −L.z)·(−sin θ)

The shear is taken about the shadow of the hook point.

Two masks are made per picture: a tight one (blurred by 1.2% of its height) for a piece near the wall, and a wide one (3.5%) for a piece pulled out from it. They cross over with the distance from the wall. A piece leaving through the frame's left edge takes its shadow with it, or a grey patch stays behind on the wall.

components/hangline/room.tsxlines 298–321Open in the code browser

  const s = onWall(g, { x: at.x, y: at.y + g.hookH, z: at.z });
  // A local x offset on the turned piece lands at x cos(turn) and moves -x sin(turn) towards the viewer; on
  // the wall that depth becomes a further shift along the light, so the shadow is the mask sheared about
  // the hook point's own shadow.
  const r = (turn * Math.PI) / 180;
  const towards = -Math.sin(r);
  const a = Math.cos(r) + (g.light.x / -g.light.z) * towards;
  const b = (g.light.y / -g.light.z) * towards;
  const left = -ph.hook[0] * w - pad * w + HOOK_STEM_OFFSET * g.hookH;
  const top = -ph.hook[1] * h - pad * w;
  const tf = `translate(${(s.x - wall.x0).toFixed(1)}px, ${(s.y - wall.y0).toFixed(1)}px) matrix(${a.toFixed(4)}, ${b.toFixed(4)}, 0, 1, 0, 0) translate(${left.toFixed(1)}px, ${top.toFixed(1)}px)`;
  const width = `${(w * (1 + 2 * pad)).toFixed(1)}px`;
  const height = `${(h + 2 * pad * w).toFixed(1)}px`;
  // far from the wall the shadow is the softer, wider mask; the two cross over with the distance
  const farShare = Math.max(0, Math.min(1, 1 - Math.max(0, u) / 0.6));
  // a piece leaving through the frame's left edge takes its shadow with it: without this its wide soft
  // shadow stayed on the wall as a grey patch after the piece had gone
  const leaving = u < -0.25 ? Math.max(0, 1 - (-u - 0.25) / 0.2) : 1;
  for (const [el, k] of [[near, (1 - farShare) * leaving], [far, farShare * leaving]] as const) {
    el.style.transform = tf;
    el.style.width = width;
    el.style.height = height;
    el.style.setProperty("--hl-k", k.toFixed(3));
  }

Pointing at a piece in 3D

Hovering a queued piece turns it 16° towards you and parts the line behind it. At first, no queued piece answered the pointer at all.

LessonNot in the docsL-MA04 Learned by the AI · Claude Opus 5.5

In a CSS 3D scene an empty preserve-3d box at z = 0 sits in front of everything behind it and catches the pointer

other:Chrome156onWindows;CSStransform-stylepreserve-3d

Rule: If elements placed behind z = 0 in a preserve-3d scene ignore hover and clicks, an empty container at z = 0 is hit first. Give the containers pointer-events: none, and auto only on what should answer.
Snippet: /* before: nothing; the world's box and the wall plane took every pointer */ /* after */ .hl-world, .hl-wall, .hl-world > div, .hl-piece, .hl-hook { pointer-events: none; } .hl-piece .hl-photo { pointer-events: auto; }
Check: Hover a piece that hangs behind the scene's plane: it turns, and a click brings it to the front.
Applies to: other: Chrome 156 on Windows; CSS transform-style preserve-3d
I assumed: hit testing follows DOM order, as it does on a flat page, and an empty container that draws nothing is no obstacle.
What happened: hovering or clicking a queued piece did nothing. The pieces hang behind z = 0, and the .hl-world box and the wall plane at z = 0 were in front of them for hit testing, although they drew nothing.
Why: inside a 3D rendering context, hit testing follows depth, and a box hits wherever it is, whether or not it paints.
The fix: pointer-events: none on the world, the wall, the piece links and the hooks; auto only on the pictures.
Evidence: commit 75897d9; the touch test "a tap on a queued piece brings it to the front".

components/hangline/hangline.csslines 2702–2726Open in the code browser

/* Hit testing in the 3D room: the world's own box sits at z = 0, in front of every queued piece (they hang
   further back), and caught every pointer meant for them. Only the pictures take the pointer. */
.hl-world,
.hl-wall,
.hl-world > div,
.hl-piece,
.hl-hook {
  pointer-events: none;
}

.hl-piece .hl-photo {
  pointer-events: auto;
}

/* With an outline, only the garment's own shape answers, never the photo's clear margin: the front piece's
   margin lies over the queued pieces beside it. */
.hl-piece .hl-photo[data-hit] {
  pointer-events: none;
}

.hl-hit {
  position: absolute;
  inset: 0;
  pointer-events: auto;
}

That was not all. The front piece's picture is a rectangle with a clear margin round the garment, and that margin lay over the visible edges of the next three pieces. Only the garment's own outline may answer, and the companion article shows how that outline is made.

Steel without stair steps

The rail and the arm began as thin boxes turned with rotateY, like everything else in the room. At device pixel ratios 1 to 1.5 they showed stair steps along both edges.

LessonNot in the docsL-QGWQ Learned by the AI · Claude Opus 5.5

Chrome draws the edges of a 3D-turned box without anti-aliasing: draw thin bars flat, as projected shapes

other:Chrome156onWindows(ANGLED3D11)atdevicepixelratio1to1.5

Rule: If a thin bar turned with rotateY shows stair steps at DPR 1 to 1.5 in Chrome, smoothing will not reach it. Project the bar yourself and draw it flat, with a clip-path or an SVG polygon.
Snippet: // before: a thin box placed and turned in the 3D world <div className="hl-bar-steel hl-rail" style={{ width: len, height: t, transform: `translate3d(${g.railStart.x}px, ${g.railY}px, ${g.railStart.z}px) rotateY(${RAIL_ANGLE}deg)` }} /> // after: both ends projected by the scene's own camera, drawn as a flat shape outside the 3D world const pa = project(g, a), pb = project(g, b); <div className={`hl-steel ${className}`} style={{ left: x0, top: y0, width: w, height: h, clipPath: clip }}><svg>{bands}</svg></div>
Check: Screenshot the bar at DPR 1, 1.25 and 1.5 and look at 400%: both edges are smooth, with no steps.
Applies to: other: Chrome 156 on Windows (ANGLE D3D11) at device pixel ratio 1 to 1.5
I assumed: a thin bar turned with rotateY would be anti-aliased like any other drawing, or at least once it had a 3D world of its own or a clear margin inside its box.
What happened: at 400% the rail and the arm stepped along both edges at DPR 1 to 1.5; at 2 and 3 the steps are too small to see. Three tries did not change it:

a 3 px clear margin with the steel painted inside the box: slightly softer at 1.25×, the arm unchanged, and dark specks where the arm's two faces overlapped;

the bars in a world of their own: the same steps;

a conic gradient centred on the bar's vanishing point to shade a flat tube: Chrome resolves a span of a quarter of a degree to one flat colour.
Why: the steps are the edge of the turned layer itself, which the compositor draws unsmoothed. Smoothing applies where a shape is painted, not where a turned layer is placed.
The fix: draw the steel flat, from the same geometry: a round tube projected by the scene's camera, its outline cut by one clip-path.
Evidence: commit b4f0d84; Chrome, day and night, DPR 1, 1.25, 1.5, 2 and 3, the same places at 400% before and after. Also smooth after in Edge and Firefox 141.

The projected tube

A round bar seen from anywhere is, on screen, a band between two straight edges. Those edges meet at the bar's vanishing point, because the bar's radius is drawn at the projection's scale at every point along it.

So Tube projects the two ends with the scene's own project() and takes the screen normal n, turned towards the light (which comes from the upper left). It offsets each end by r·s along n, so the two edges converge exactly as the bar would. f runs across the tube, from 0 on the lit edge to 1 on the shaded edge.

Shading a round bar takes bands, and how they meet matters:

Bands that share an edge harden it, because each one adds its own partial pixel of anti-aliasing.
Bands that only touch leave a hairline of wall between them.

So the bands are stacked from the shaded side to the lit side. Each band is drawn from beyond the lit edge (f = −0.5) to its own far edge, the next one is painted over it, and a single clip-path cuts the outline once:

components/hangline/room.tsxlines 480–522Open in the code browser

const STEEL_BANDS: [number, string][] = [
  // [far edge of the band across the tube, 0 = lit edge, 1 = shaded edge; its colour]
  [1.5, "var(--hl-steel-dark)"],
  [0.9, "color-mix(in srgb, var(--hl-steel-mid) 22%, var(--hl-steel-dark))"],
  [0.78, "color-mix(in srgb, var(--hl-steel-mid) 48%, var(--hl-steel-dark))"],
  [0.66, "color-mix(in srgb, var(--hl-steel-mid) 74%, var(--hl-steel-dark))"],
  [0.54, "var(--hl-steel-mid)"],
  [0.42, "color-mix(in srgb, var(--hl-steel-light) 40%, var(--hl-steel-mid))"],
  [0.31, "color-mix(in srgb, var(--hl-steel-light) 72%, var(--hl-steel-mid))"],
  [0.2, "var(--hl-steel-light)"],
  [0.09, "color-mix(in srgb, var(--hl-steel-light) 45%, var(--hl-steel-mid))"],
];

type Pt = { x: number; y: number };

function Tube({ g, a, b, r, className }: { g: RoomGeometry; a: Vec3; b: Vec3; r: number; className: string }) {
  const pa = project(g, a);
  const pb = project(g, b);
  const len = Math.hypot(pb.x - pa.x, pb.y - pa.y) || 1;
  // across the tube in the picture, towards the light (it comes from the upper left)
  let n = { x: -(pb.y - pa.y) / len, y: (pb.x - pa.x) / len };
  if (n.x + n.y > 0) n = { x: -n.x, y: -n.y };
  const at = (p: { x: number; y: number; s: number }, f: number): Pt => ({ x: p.x + n.x * r * p.s * (1 - 2 * f), y: p.y + n.y * r * p.s * (1 - 2 * f) });
  const outline = [at(pa, 0), at(pb, 0), at(pb, 1), at(pa, 1)];
  const xs = outline.map((p) => p.x);
  const ys = outline.map((p) => p.y);
  const pad = 2 + r * Math.max(pa.s, pb.s);
  const x0 = Math.floor(Math.min(...xs) - pad);
  const y0 = Math.floor(Math.min(...ys) - pad);
  const w = Math.ceil(Math.max(...xs) + pad) - x0;
  const h = Math.ceil(Math.max(...ys) + pad) - y0;
  const pt = (p: Pt) => `${(p.x - x0).toFixed(2)} ${(p.y - y0).toFixed(2)}`;
  const clip = `polygon(${outline.map((p) => `${(p.x - x0).toFixed(2)}px ${(p.y - y0).toFixed(2)}px`).join(", ")})`;
  return (
    <div className={`hl-steel ${className}`} style={{ left: x0, top: y0, width: w, height: h, clipPath: clip }} aria-hidden="true">
      <svg width={w} height={h} viewBox={`0 0 ${w} ${h}`} focusable="false">
        {STEEL_BANDS.map(([f, fill]) => (
          <polygon key={f} points={[at(pa, -0.5), at(pb, -0.5), at(pb, f), at(pa, f)].map(pt).join(" ")} style={{ fill }} />
        ))}
      </svg>
    </div>
  );
}

The stub to the wall bracket, the rail and the arm are three tubes. The rail runs one radius past its bracket, so its end covers the joint:

components/hangline/room.tsxlines 524–540Open in the code browser

function Steel({ g }: { g: RoomGeometry }) {
  const t = RAIL_T * g.H;
  const r = t / 2;
  const y = g.railY + r;
  const capOut = 0.012 * g.H;
  const d = { x: g.railEnd.x - g.railStart.x, z: g.railEnd.z - g.railStart.z };
  const dl = Math.hypot(d.x, d.z);
  // the rail runs a radius past its bracket, so its end covers the bracket's joint
  const past = { x: g.railEnd.x + (d.x / dl) * r, y, z: g.railEnd.z + (d.z / dl) * r };
  return (
    <>
      <Tube g={g} className="hl-stub" r={r} a={{ x: g.railEnd.x, y, z: g.railEnd.z }} b={{ x: g.railEnd.x, y, z: g.wallZ }} />
      <Tube g={g} className="hl-rail" r={r} a={{ x: g.railStart.x, y, z: g.railStart.z }} b={past} />
      <Tube g={g} className="hl-arm" r={r} a={{ x: g.front.x, y, z: g.front.z + capOut }} b={{ x: g.armRoot.x, y, z: g.armRoot.z }} />
    </>
  );
}

The steel is now one flat layer between the wall's world and the pieces' world, so every hook is drawn in front of it. A real hook's curl passes behind the bar, so the drawn curl stops at the bar's top edge, where it would go behind:

components/hangline/hook.tsxlines 37–46Open in the code browser

      {/* stem from the neck up and the curl over the bar. The steel is drawn behind every piece (room.tsx), so the
          curl stops at the bar's top edge, where it would pass behind the bar: the first half of the curl's far
          side, split at its middle. */}
      <path
        d={`M ${HOOK_STEM_X} 100 L ${HOOK_STEM_X} 30 C ${HOOK_STEM_X} 19 ${HOOK_STEM_X - 3} 14.5 ${HOOK_STEM_X - 9} 14.5 C ${HOOK_STEM_X - 12} 14.5 ${HOOK_STEM_X - 14.375} 15.625 ${HOOK_STEM_X - 16} 17.5`}
        fill="none"
        stroke={`url(#${id}-steel)`}
        strokeWidth="3.4"
        strokeLinecap="butt"
      />

Checking the new rod in Firefox found something else.

LessonNot in the docsL-KEP8 Learned by the AI · Claude Opus 5.5

Firefox draws no SVG that sits untransformed inside a preserve-3d element: give it a transform of its own

other:Firefox141onWindows

Rule: If an inline SVG inside a preserve-3d parent is missing in Firefox only, give the SVG its own transform (translateZ(0)), scoped to Firefox so other browsers make no extra layers.
Snippet: /* before: the hook's SVG, untransformed, inside a preserve-3d piece */ .hl-hook { position: absolute; overflow: visible; } /* after */ @supports (-moz-appearance: none) { .hl-hook { transform: translateZ(0); } }
Check: Open the scene in Firefox: every hanger has its hook, the front piece and the queue.
Applies to: other: Firefox 141 on Windows
I assumed: the rail looked the same in Firefox, since every check ran in Chrome and nothing failed.
What happened: Firefox showed no hook on any hanger, on the new code and on the code from before the rod's change. The hook's SVG was in the page, visible, 7 × 45 px, with its stroke resolved. A flat stroke in place of the gradient did not bring it back.
The fix: a transform of its own on the SVG brings it back. The rule sits under @supports (-moz-appearance: none), so Chrome does not make a layer for each of the 28 hooks.
Evidence: commit b4f0d84; Firefox screenshots with and without the transform.

components/hangline/hangline.csslines 427–433Open in the code browser

/* Firefox draws no SVG that sits untransformed inside a preserve-3d piece: the hooks were missing there.
   A transform of its own brings them back. Firefox only, so Chrome gets no layer per hook. */
@supports (-moz-appearance: none) {
  .hl-hook {
    transform: translateZ(0);
  }
}

The motion: one spring for the rail, a pendulum for each piece

The rail's position x follows a critically damped spring towards its target x*:

ẍ = ω²(x* − x) − 2ω·ẋ, with ω = 7.6 rad/s

A command only moves x*. Position and speed carry on, so a second tap mid-move chains into one move, and nothing ever snaps. The simulation steps at 240 Hz inside each frame (semi-implicit Euler), and a long frame is cut to 50 ms, so a stalled tab does not leap. While nothing moves, no animation frame runs.

Each piece has its own pendulum, pushed by the rail's acceleration a:

θ̈ = −ωs²·(θ + k·a(t − d·u)) − 2ζ·ωs·θ̇

The terms:

ωs = 9.2 rad/s and ζ = 0.42: it settles in about 900 ms.
k = 0.085° per index/s² of acceleration.
The push arrives d = 0.028 s later for every place down the queue, so the swing travels along the line like a wave. The acceleration history is kept for half a second for that delay.

components/hangline/motion.tslines 223–253Open in the code browser

  advance(dt: number): boolean {
    let busy = false;
    const steps = Math.max(1, Math.ceil(dt / (1 / 240)));
    const h = dt / steps;
    for (let s = 0; s < steps; s++) {
      this.clock += h;
      const prevVel = this.vel;
      if (!this.dragging) {
        const w = this.omega;
        const acc = w * w * (this.target - this.pos) - 2 * w * this.vel;
        this.vel += acc * h;
        this.pos += this.vel * h;
      }
      const a = (this.vel - prevVel) / h;
      this.accHistory.push({ t: this.clock, a });
      // pendulums, each pushed by the rail's acceleration a little later down the queue
      for (let i = 0; i < this.count; i++) {
        const u = this.uOf(i);
        const delay = Math.max(0, u) * SWING_DELAY;
        const drive = this.reduced ? 0 : this.accAt(this.clock - delay);
        const sw = this.swing[i];
        const sv = this.swingVel[i];
        const sa = -SWING_OMEGA * SWING_OMEGA * (sw + SWING_GAIN * drive) - 2 * SWING_ZETA * SWING_OMEGA * sv;
        this.swingVel[i] = sv + sa * h;
        this.swing[i] = Math.max(-3 * SWING_MAX, Math.min(3 * SWING_MAX, sw + this.swingVel[i] * h));
        const hv = this.hoverVel[i];
        const ha = HOVER_OMEGA * HOVER_OMEGA * (this.hoverTarget[i] - this.hover[i]) - 2 * HOVER_OMEGA * hv;
        this.hoverVel[i] = hv + ha * h;
        this.hover[i] += this.hoverVel[i] * h;
      }
    }

The swing is not drawn as computed.

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

A hard clamp on a spring-driven swing shows as a flat top when the push is big: draw max · tanh(θ / max)

other:springandpendulumanimationinJavaScript

Rule: If a spring-driven angle rides its limit for several frames and stops dead on big pushes, stop clamping it. Keep the spring's state free and draw max · tanh(angle / max).
Snippet: // before const drawn = Math.max(-3, Math.min(3, this.swing[i])); // after: the state is free, the drawing approaches 3° smoothly swingOf(i: number) { return SWING_MAX * Math.tanh(this.swing[i] / SWING_MAX); }
Check: Pick a piece four places ahead, then reverse mid-move: on a frame-by-frame filmstrip the angle rounds over near 3° and never holds flat.
Applies to: other: spring and pendulum animation in JavaScript
I assumed: clamping the hanger's swing at 3° would only cut the rare extreme.
What happened: a pick four places ahead, or a reversal mid-move, pushes the pendulums much harder than a step. Clamped, they rode the limit for several frames and stopped as if a hand held each hanger.
The fix: the pendulum's state is free (with a wide guard at 9°), and the drawn angle is soft-limited by tanh. One step draws about 1.2°, a chain of three 2.5°, and a big pick 2.8°.
Evidence: commit a8f83e4; the motion check's largest swing per scenario.

components/hangline/motion.tslines 311–314Open in the code browser

  /** The swing as drawn: soft-limited to about 3 degrees, so a big push never shows a flat top. */
  swingOf(i: number) {
    return SWING_MAX * Math.tanh(this.swing[i] / SWING_MAX);
  }

A drag sets the position directly, at the pointer's own speed. On release, the throw has a cap.

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

A carousel thrown by touch velocity alone runs on six items from a quick flick: cap the throw in items

other:touch-drivencarousels(PointerEvents)

Rule: If a flick makes the carousel lose the item the user was on, cap the throw: add speed × a time, but never more than a few items past where the finger let go.
Snippet: // before: thrown by speed alone const throwTo = this.pos + vel * 0.22; // after: at most three pieces past the release point const throwTo = this.pos + Math.max(-3, Math.min(3, vel * 0.22));
Check: A quick sideways swipe on a phone moves the rail on by three pieces at most, and lands on a piece.
Applies to: other: touch-driven carousels (Pointer Events)
I assumed: velocity from the touch events' own timestamps is honest, so throwing by it would feel natural.
What happened: it is honest, and a quick flick is fast. The test's flick ran the rail on by six pieces, and the shopper lost the one they were looking at.
The fix: the throw adds speed × 0.22 s, capped at three pieces past the release point. The spring then lands it on a whole piece.
Evidence: commit 75897d9; the touch test "a sideways swipe on the scene moves the rail".

components/hangline/motion.tslines 158–166Open in the code browser

  /** Release: a flick throws the rail on, and the spring lands it on a piece. */
  release(vel: number) {
    this.dragging = false;
    this.vel = vel;
    // a flick throws the rail on by its speed, but never more than three pieces past where the finger let go
    const throwTo = this.pos + Math.max(-3, Math.min(3, vel * 0.22));
    this.target = this.loop ? Math.round(throwTo) : this.clamp(Math.round(throwTo));
    this.wake();
  }

The line parts behind a hovered piece

A hovered piece turns towards you, and each piece behind it moves back along the rail by its share of the hover, 0.06 H at most.

At first, that shift ran to the end of the line. It now closes again towards the far end. The paint walks the pieces in the order they hang, front first, and for each one it scales the shift by how far it still is from the end:

components/hangline/room.tsxlines 108–127Open in the code browser

      // the line parts behind a hovered piece: each piece moves back by the hover of every piece ahead of it.
      // The parting closes again towards the far end, so the last piece never moves: moved back, a wide
      // piece's shadow reached the panel's words.
      let ahead = 0;
      let aheadU = 0;
      const end = g.visible + 0.25;
      let tag = -1;
      let tagHover = 0;
      let upgrade = false;
      // pieces in the order they hang along the rail, front first: on an endless rail that is not index order
      const us = garments.map((_, i) => m.uOf(i));
      const order = us.map((_, i) => i).sort((a, b) => us[a] - us[b]);
      const painted: PaintedPiece[] = new Array(garments.length);
      for (const i of order) {
        const u = us[i];
        const hv = u > 0.6 ? m.hover[i] : 0;
        const from = ahead > 0 ? aheadU / ahead + 1 : u;
        const close = ahead > 0 ? Math.min(1, Math.max(0, (end - u) / Math.max(0.5, end - from))) : 0;
        const p = pose(g, u, ahead * HOVER_ROOM * g.H * close, m.aside);
        ahead += hv;

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

Pushing a whole queue back on hover spends the layout's margin at the far end: let the shift close before the last item

other:hovereffectson3Dorperspectivequeues

Rule: If a hover that parts a queue makes its far end cross nearby text, shrink the shift to zero at the last drawn place, and check every item at the far end, not only the first.
Snippet: // before: every piece behind the hovered one moves back by the full amount const p = pose(g, u, ahead * HOVER_ROOM * g.H, m.aside); // after: the shift closes again towards the end of the line const close = ahead > 0 ? Math.min(1, Math.max(0, (end - u) / Math.max(0.5, end - from))) : 0; const p = pose(g, u, ahead * HOVER_ROOM * g.H * close, m.aside);
Check: Measure text contrast with the pointer on each queued item, at every rail position: no shadow reaches the panel's words.
Applies to: other: hover effects on 3D or perspective queues
I assumed: a hover parting checked against the panel with one set of pictures was safe with any other.
What happened: with wider pictures, one state of 22 failed contrast (1440 × 900, light, the pointer on the third queued piece). The twelfth piece, one of the widest fronts (1016 px of 1088), was pushed back, and its wall shadow fell over the first letters of the description: 3.27:1 against the 4.5 needed. At rest the same words measured 6.01:1.
Why: the far end is what comes near the panel, and how far it reaches depends on whichever piece happens to be last. A fixed shift spends the margin the layout left at rest.
The fix: the piece just behind the hovered one moves back in full, and the shift shrinks to nothing at the last drawn place. The line opens where the pointer is, and its end never moves.
Evidence: commit 361f23d; a contrast sweep of all 14 rail positions at 1440, 1280, 1920 and 1366 wide, rest and hover: 0 failures, lowest 5.95:1.

An endless rail with no copies

The rail must never run out. Next after the last piece is the first, the queue is always full, and no piece may pop in, jump or show twice.

The usual way is to clone the list. That would double every pendulum, picture and shadow here. Instead, the rail position runs on past the ends, and each piece's place is its u wrapped onto one turn, [−SEAM, count − SEAM):

components/hangline/motion.tslines 28–37Open in the code browser

/** Where an endless rail's seam lies, in steps behind the front: just past the left exit, where a leaving piece
 * is already gone (u < -0.5). Its other side, count - SEAM, lies past the far end, where a piece has taken the
 * wall's tone. So a piece that leaves at the left rejoins the rail in the depth behind the last one, and comes
 * forward out of the wall's tone: never two places, never seen jumping. */
export const SEAM = 0.55;

/** u wrapped onto one turn of an endless rail: [-SEAM, count - SEAM). */
export function wrapU(u: number, count: number) {
  return ((((u + SEAM) % count) + count) % count) - SEAM;
}

SEAM = 0.55 puts both sides of the seam where nothing is seen:

The near side, u = −0.55, is just past the left exit. A leaving piece is already hidden from u < −0.5.
The far side, count − 0.55, lies past the last place drawn. With 14 pieces it is at 13.45. The line is drawn to visible + 0.25 = 11.25, and a piece has fully taken the wall's tone at visible + 0.4.

A piece that leaves at the front therefore rejoins the rail in the depth behind the last one. It comes forward out of the wall's tone with the rail's own perspective, and no frame can draw it twice. It only holds while the line drawn is shorter than the rail, so a small rail of 8 draws 6 places: maxVisible is the piece count minus two.

Everything that walked pieces by index now has to walk them by place:

the hover parting sorts the pieces by u;
each pendulum's delay down the queue uses the wrapped place;
a tap brings a piece forward by its place (bring);
Home, End, a deep link and Back take the shorter way round (goTo), so End from the first piece is one step back;
the counter rolls the way the rail went: 14 to 1 is a step on.

components/hangline/motion.tslines 102–115Open in the code browser

  /** Bring piece i to the front. On an endless rail by the shorter way round: End from the first piece is one
   * step back, not thirteen on. */
  goTo(i: number) {
    if (!this.loop) return this.moveTo(i);
    const cur = Math.round(this.target);
    let d = (((i - cur) % this.count) + this.count) % this.count;
    if (d > this.count / 2) d -= this.count;
    this.moveTo(cur + d);
  }

  /** Bring piece i to the front from where it hangs now: a tap on a queued piece moves the rail on by its place. */
  bring(i: number) {
    this.moveTo(Math.round(this.pos + this.uOf(i)));
  }

The check that proves it needed a fix of its own.

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

A no-pop-in check for a wrapping carousel must let an item cross its exit between two frames

other:frame-by-frameanimationchecks(Playwright)

Rule: If a pop-in check flags fast carousel moves that look fine, it judges by the last drawn place: let an item appear only from past an edge, and vanish only past one.
Snippet: // past an edge: off the frame at the left, or past the last place drawn, in the wall's tone const beyond = (u) => u < -0.5 + 1e-6 || u > g.visible + 0.25 - 1e-6; // before: a piece that stopped being drawn was judged by its last drawn place (q, the frame before) if (!p.visible && q.visible && !beyond(q.u)) bad.push(`pop out: piece ${p.i}`); // after: by where it is now; it may vanish only past an edge, and appear only from past one if (!p.visible && q.visible && !beyond(p.u)) bad.push(`pop out: piece ${p.i}`); if (p.visible && !q.visible && !beyond(q.u)) bad.push(`pop in: piece ${p.i}`);
Check: Run the fast scenarios (30 taps each way, a fling across the seam each way): 0 problems, and the counter cycles 13, 0, 1.
Applies to: other: frame-by-frame animation checks (Playwright)
I assumed: a piece is popping if, on its last drawn frame, it was not yet at the exit.
What happened: in a fast move a piece crosses the exit between two frames, from u −0.43 to −0.53, which is not a pop. The first rule flagged it.
The fix: judge appearing and vanishing by where the piece is when it changes, not where it was last drawn.
Evidence: commit 4ce2ce1; the motion check, 11 scenarios at 1440 × 900 with no pop, no jump and a full queue at rest: 0 problems. The queue is 11 at every rest and never under 10 in a move.

Loading the rest of an endless rail

On a rail with ends, the pieces past the far end can wait until the rail comes close. On an endless rail every piece comes round, from either side. A fast run of steps once found a piece entering before its picture was decoded, and it appeared mid-rail. So the rest of the rail has to load at some point, and when that point comes is a budget decision.

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

Preloading the rest of an endless carousel after page load costs every phone visitor: load it on the first move there

other:imageloadingbudgetsonphones

Rule: If a carousel's off-screen images load after page load "to be ready", count that on a phone at 3×: load them on its first move, with a short reach ahead.
Snippet: // before: every screen loads the rest once the page has loaded const later = () => { t = window.setTimeout(() => setSeam(true), 1200); }; window.addEventListener("load", later, { once: true }); // after: a phone (rest = "move") skips that, and the paint loads the rest on the rail's first move if (rest === "move" && !review) return; if (loop && !seamRef.current && (m.dragging || m.target !== start || Math.abs(m.pos - start) > 0.001)) { seamRef.current = true; setSeam(true); }
Check: On the production build at 390 × 844 at 3×, the network panel shows nothing more for several seconds untouched. The first step brings the rest.
Applies to: other: image loading budgets on phones
I assumed: loading the rest of the rail after the page's load was free, since it sits outside the first view.
What happened: on a wide screen the rest is 200 KB. On a phone at 3× it is 786 KB, paid by every visitor, including those who only look.
The fix: a wide screen still loads it after the page's load. A phone loads it when the rail first moves: a drag, a step or a tap. The first step keeps its own reach of 0.75 of a step past the last place drawn, to cover its first frames. Review pages load it at once, so the motion check starts from a loaded rail.
Evidence: commit 7892616; production build at 390 × 844 at 3×: nothing more loaded in 3.5 s untouched, 786 KB with the first step. The loop's motion check on a phone: 0 problems in 4 scenarios.

components/hangline/room.tsxlines 79–101Open in the code browser

  const n = garments.length;
  const inReach = (u: number) => u >= -1 && u <= g.visible + REACH;
  const [load, setLoad] = useState<boolean[]>(() => garments.map((_, i) => inReach(loop ? wrapU(i - start, n) : i - start)));
  const [full, setFull] = useState<boolean[]>(() => garments.map((_, i) => i - start >= -1 && i - start <= 0));
  const loadNow = useRef(load);
  const fullNow = useRef(full);
  const [seam, setSeam] = useState(false);
  useEffect(() => {
    if (!loop) return;
    // review pages (motion.mjs and the other checks) load it at once, as if the shopper had already moved
    const review = (window as unknown as { __HL_REVIEW__?: boolean }).__HL_REVIEW__;
    if (rest === "move" && !review) return;
    let t = 0;
    const later = () => {
      t = window.setTimeout(() => setSeam(true), review ? 0 : 1200);
    };
    if (document.readyState === "complete") later();
    else window.addEventListener("load", later, { once: true });
    return () => {
      window.removeEventListener("load", later);
      window.clearTimeout(t);
    };
  }, [loop, rest]);

components/hangline/room.tsxlines 155–164Open in the code browser

        // the rail's first move (a phone) brings the rest of an endless rail in
        if (loop && !seamRef.current && (m.dragging || m.target !== start || Math.abs(m.pos - start) > 0.001)) {
          seamRef.current = true;
          setSeam(true);
        }
        if (!loadNow.current[i] && (inReach(u) || (loop && seamRef.current))) {
          loadNow.current = loadNow.current.slice();
          loadNow.current[i] = true;
          upgrade = true;
        }

What the first view costs

The budget for the first view's pictures at 1440 × 900 is 900 KB. It now measures 853 KB.

The first time all 14 distinct pieces were in place, it measured nearly twice that.

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

Turned, distant items in a 3D queue asked for full-width images: request the width they are drawn at, none past the end

other:imgsrcsetandsizesinCSS3Dscenes

Rule: If a 3D queue's first view weighs far more than its pixels need, give turned, distant items a fraction of their width, the full size near the front, nothing before they are drawn.
Snippet: // before: every piece asks for the width it has facing you <PhotoLayers ph={ph} w={w} /> // after: a queued piece asks for 0.75 of it until it starts towards the front <PhotoLayers ph={ph} w={full ? w : w * QUEUE_SIZES} /> const inReach = (u: number) => u >= -1 && u <= g.visible + REACH;
Check: Measure the first view in a new browser context, by kind of file: the queue's fronts come in at the small size, and pieces beyond the line load nothing.
Applies to: other: img srcset and sizes in CSS 3D scenes
I assumed: the first view would stay near 583 KB when stand-in pictures were replaced, since each place still shows one picture.
What happened: it went to 1,660 KB. With 4 real pictures repeated, the browser fetched each of them once. With 12 different garments in view, each asked for its picture at the width it has facing you (469 to 548 px), which at 1× picks the 946 to 1050 px file. The two pieces past the far end, not drawn at all, loaded too.
Why: a queued piece is turned 70° and stands back, at about 0.7 of its size at the first place. The 480 px file already gives it more than a pixel of picture per pixel of screen.
The fix: a queued piece asks for 0.75 of its width, and for its full size once it starts towards the front. A piece more than three quarters of a step past the last place drawn loads nothing, its shadows included. Each switch only ever turns on, so nothing loads twice.
Evidence: commit 361f23d; 1,660 KB before, 1,100 KB with the smaller queue, 854 KB with the far pieces waiting (wall 193, fronts 464, near shadows 75, far shadows 123).

components/hangline/room.tsxlines 17–23Open in the code browser

// What a piece's picture costs the first view. A queued piece is turned edge on and stands back
// (about 0.7 of its size at the first place), so its picture is asked for at 0.75 of its width: at 1x that is the
// 480 px file, still sharper than the screen there. It asks for its full size once it starts towards the front,
// and keeps it. A piece beyond the far end of the line loads nothing until it is half a step from coming into
// view, where it is still nearly the wall's tone.
const QUEUE_SIZES = 0.75;
const REACH = 0.75; // past the last place drawn (visible + 0.25), in steps

What a move costs the GPU

Every frame of a move rewrites the transforms of 14 pieces, their tints and 28 shadows. That is cheap only if the compositor can do it without painting.

LessonNot in the docsL-G737 Learned by the AI · Claude Opus 5.5

Chrome re-rasters a moving 3D element when a child changes opacity every frame: give the child its own layer

other:Chrome156onWindows

Rule: If a CSS 3D animation shows thousands of GPU raster jobs for few paints, look for a child whose opacity changes every frame: will-change: opacity on that child, not on the moving element.
Snippet: /* before: the tint's opacity changed every frame as part of the piece's layer */ .hl-tint { opacity: calc(var(--hl-t) * var(--hl-tint-k, 1)); } /* after */ .hl-tint { opacity: calc(var(--hl-t) * var(--hl-tint-k, 1)); will-change: opacity; } .hl-wall-shadow { will-change: transform, opacity; }
Check: Record a performance trace of the same moves: GPU raster jobs fall by about ten times, and the front piece is as sharp as before.
Applies to: other: Chrome 156 on Windows
I assumed: an opacity change is the compositor's job, wherever it sits.
What happened: during the rail's moves the GPU ran about 3,180 raster jobs (1.0 to 1.3 s of GPU time) for only some 230 paints. Each queued piece's tint changes its opacity every frame, and as part of the piece's layer every change meant a new raster of the piece, picture and all.
The fix: will-change: opacity on the tint, and will-change: transform, opacity on the wall shadows. The hint on the pieces themselves added nothing and can pin a layer's raster scale, so it is left off.
Evidence: commit 2861979; an A/B on the same moves: about 336 raster jobs and 120 to 180 ms of GPU raster after. Front piece sharpness (Laplacian variance) 576, against 443 for a piece that had travelled from the queue.

components/hangline/hangline.csslines 393–404Open in the code browser

.hl-tint {
  position: absolute;
  inset: 0;
  opacity: calc(var(--hl-t) * var(--hl-tint-k, 1));
  background: var(--hl-wall);
  -webkit-mask-size: 100% 100%;
  mask-size: 100% 100%;
  pointer-events: none;
  /* its opacity changes every frame of a move: on its own layer that is the compositor's job, not a new
     raster of the piece's photo (about ten times fewer GPU rasters) */
  will-change: opacity;
}

The room has two stations, the rail and the accessory tray, and the view pans between them.

LessonNot in the docsL-SWG5 Learned by the AI · Claude Opus 5.5

Chrome frees the layers of an element waiting wholly off screen with a static transform: will-change keeps them

other:Chrome156onWindows

Rule: If panning back to an off-screen panel stutters, Chrome freed its layers while it waited. Put will-change: transform on each panel that pans in and out.
Snippet: /* before */ .hl-station { position: absolute; inset: 0; transition: transform var(--hl-pan-ms, 820ms) cubic-bezier(0.65, 0, 0.35, 1); } /* after */ .hl-station { position: absolute; inset: 0; transition: transform var(--hl-pan-ms, 820ms) cubic-bezier(0.65, 0, 0.35, 1); will-change: transform; }
Check: Count the layers that are created and painted during the pan back in a DevTools trace: a few repaints, not a full new set, and no frame over 20 ms when warm.
Applies to: other: Chrome 156 on Windows
I assumed: an off-screen station keeps its layers until it comes back.
What happened: while the tray was shown, the page had 5 layers instead of 130. The rail station sat wholly off screen with a static transform, outside the area Chrome keeps painted, so its layers were freed. The pan back created and rastered 69 layers again, among them a 2805 × 1629 px wall plane, with frames up to 100 ms. The other way round, the tray could not be rastered before its pan.
The fix: will-change: transform on both stations. Chrome then keeps a station's layers while it is away, and rasters one that is about to come in ahead of time.
Evidence: commit 2861979; the pan back went from 69 new layers to 18 repainted ones, and its longest frame from 83 to 17 ms (warm).

components/hangline/hangline.csslines 1628–1636Open in the code browser

.hl-station {
  position: absolute;
  inset: 0;
  transition: transform var(--hl-pan-ms, 820ms) cubic-bezier(0.65, 0, 0.35, 1);
  /* Chrome keeps the layers of a station that waits off screen only while its transform is hinted: without
     it, the rail's hundred layers were freed while the tray was shown and rastered again on the way back,
     and the tray, mounted on intent, could not be rastered before its pan */
  will-change: transform;
}

A phone breaks that hint. There the card that opens a piece is position: fixed, and a hinted transform makes the station the box a fixed child is placed in, so the phone layout sets will-change: auto on the stations.

Choosing an accessory on the tray lifts it, softens its shadow and dims the others. Those transitions needed hints as well, and one of them was not obvious.

LessonNot in the docsL-0XWG Learned by the AI · Claude Opus 5.5

Chrome re-rasters a layer at the end of its scale transition: will-change: transform keeps the raster it has

other:Chrome156onWindows

Rule: If one long frame lands at the end of a CSS scale transition on a large textured element, hint will-change: transform on it, so Chrome keeps the raster instead of redoing it at the final scale.
Snippet: /* before: the tray sets back to 0.96 when a piece is chosen */ .hl-station-tray .hl-tray-wrap { transition: transform 0.6s cubic-bezier(0.2, 0.7, 0.2, 1); } /* after */ .hl-station-tray .hl-tray-wrap { transition: transform 0.6s cubic-bezier(0.2, 0.7, 0.2, 1); will-change: transform; }
Check: Trace the same interaction four times: no frame over 50 ms at the transition's end.
Applies to: other: Chrome 156 on Windows
I assumed: with the lift, the blur and the dimming already on their own layers, choosing an accessory was fully on the compositor.
What happened: one long frame of 50 to 133 ms was left in about half the runs, at the end of the tray's 0.96 scale transition. Chrome rastered the tray layer again at its new scale, oak surface included.
The fix: will-change: transform on the tray's wrapper keeps the raster it has, and the look is unchanged. Earlier, the same interaction had frames of 80 to 150 ms because the filter and blur transitions had no layers: will-change on the links, the shadows (transform, opacity, filter) and the pictures (filter).
Evidence: commit 2861979; 4 of 4 clean with the hint, against 2 long frames in 4 without it.

components/hangline/hangline.csslines 2163–2168Open in the code browser

.hl-station-tray .hl-tray-wrap {
  transition: transform 0.6s cubic-bezier(0.2, 0.7, 0.2, 1);
  /* the tray sets back to 0.96 when a piece is chosen: hinted, its layer keeps the raster it has, instead of
     a new raster of the oak surface at the end of the move (50 to 133 ms frames) */
  will-change: transform;
}

Measuring all this had a trap of its own.

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

A fresh Chrome compiles GPU shaders the first time a kind of drawing appears: warm up every move before timing it

other:Chrome156headlessonWindows;Playwright

Rule: If one interaction's first frame takes 80 to 330 ms in some runs and 17 ms in others with no long CPU task, the GPU is compiling shaders: run every move once untimed first.
Snippet: // before: one page loaded untimed as the warm-up, then the timed moves // after: the warm-up runs the whole move set once, untimed, unless --cold asks for the first-use cost const cold = args.includes("--cold"); if (!cold) await moveSet(p, async (name, act, settle = 1400) => { await act(); await wait(settle); }); // ...then each budget is measured in a new context, whose cache starts empty const ctx = await browser.newContext({ viewport: { width, height }, ...rest });
Check: Time the same drag in three fresh pages of one browser after the warm-up: the same frame time every run.
Applies to: other: Chrome 156 headless on Windows; Playwright
I assumed: loading the page once before timing was enough of a warm-up.
What happened: the drag's first frame took 83 to 333 ms in some runs and 17 ms in others. With no CPU task over 25 ms, the trace showed the GPU process busy for up to 130 ms. Three fresh pages of one browser measured 83, 17 and 17 ms, and 17 ms every time with the hover tag hidden. The first time the tag's text and blurred shadow are drawn, the GPU compiles their shaders, and the warm-up page had never shown the tag.
The fix: the warm-up runs the whole move set once, then each budget is measured in a fresh context, with cold numbers reported apart. A visitor's Chrome keeps its shader cache across sites and sessions, so cold is the worst case, not the common one.
Evidence: commit 2861979; the warm and cold logs of the performance check.

The phone, and the server's layout

The component lays itself out from its own size: wide (the room on the left, a panel on the right), stacked, or a phone page. A landscape phone counts as a short wide screen, not a narrow one. On the server there is no size, so the server renders the wide layout.

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

On a phone the first size is measured in the server's wide layout: lay out only from a size measured in its own layout

react@19.2next@16.4

Rule: If a phone renders a heavy scene twice on load, the first used a size measured in the server's default layout: store each size with its layout, and render only on a match.
Snippet: // before: any measured size lays out the room const g = useMemo(() => (scene && scene.w > 0 ? roomBox(scene.w, scene.h, mode) : null), [scene, mode]); // after: each measurement carries the layout it was taken in; only a match lays out the room const layoutKey = `${mode}|${short ? "true" : ""}`; const g = useMemo(() => (scene && scene.w > 0 && scene.layout === layoutKey ? roomBox(scene.w, scene.h, mode) : null), [scene, mode, layoutKey]); useIsoLayoutEffect(() => { if (scene && scene.layout !== layoutKey) measureRef.current(); }, [scene, layoutKey]);
Check: Trace a phone load with the CPU slowed four times: one render of the scene, not two.
Applies to: react@>=19.2 <20, next@>=16.4 <17
I assumed: the first measurement after hydration is the phone's own.
What happened: with the CPU slowed four times, two full renders of the room took 342 and 319 ms. The first was drawn from the scene's size in the wide layout, the only one the server can render. It was thrown away as soon as the phone layout applied, and it also asked for pictures at the wide layout's sizes.
The fix: the scene's size is stored with the layout it was measured in. The room is laid out only when that matches, and a layout effect measures again as soon as the new layout is in the page, before it paints.
Evidence: commit 2861979; the phone's first-view pictures fell from 815 to 627 KB.

components/hangline/hangline.tsxlines 139–147Open in the code browser

  // The room is laid out only from a scene measured in the layout it will be drawn in. The first measurement
  // of a phone is made in the server's wide layout: drawing the room from it cost a whole render of every
  // piece, thrown away a moment later (about 330 ms with a 4x slower CPU). Instead the scene is measured
  // again as soon as the measured mode is in the page, before it paints.
  const layoutKey = `${mode}|${short ? "true" : ""}`;
  const g = useMemo(() => (scene && scene.w > 0 && scene.layout === layoutKey ? roomBox(scene.w, scene.h, mode, loop ? garments.length - 2 : Infinity) : null), [scene, mode, layoutKey, loop, garments.length]);
  useIsoLayoutEffect(() => {
    if (scene && scene.layout !== layoutKey) measureRef.current();
  }, [scene, layoutKey]);

Proving motion, frame by frame

Every claim above was checked on every frame of a move, not on a sample of screenshots. The tools fight you there.

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

Screenshots during a CSS 3D animation hold the page to about 30 fps: advance the animation by hand for filmstrips

playwright-core@1.64

Rule: If a filmstrip of a JavaScript animation shows the motion stretched or uneven, the captures slow the page: stop its frame loop and advance it by a fixed step per capture.
Snippet: // before: capture in real time while the animation runs for (let k = 0; k < 60; k++) shots.push(await page.screenshot()); // after: the engine's frame loop stopped; each frame advanced by hand (1/60 s), checked, then captured await page.evaluate(() => { const m = window.__hl; m.stop(); m.manual = true; }); for (let k = 0; k < 60; k++) { await page.evaluate(() => window.__hl.frame(1 / 60)); shots.push(await page.screenshot()); }
Check: Run the filmstrip twice: the two runs give identical frame data.
Applies to: playwright-core@>=1.64 <2, other: Chrome 156 headless on Windows
I assumed: screenshots taken back to back during an animation sample it fairly.
What happened: each capture took about 110 ms on an integrated GPU, and the captures held the page to about 30 animation frames a second, so the filmstrip measured the camera, not the component. Recorded video does not block, but it drops frames under load. Also, the first 3D page in a fresh browser stalled for 1.3 to 4.7 s, and a second page did not.
The fix: the engine exposes frame(dt), which advances the springs and paints with no animation frame. Checks read the DOM on every frame in virtual time; a video is kept only for the eye. Load the page once, untimed, before any timing.
Evidence: commits a8f83e4 and c5a68cb; two runs of the motion check gave identical frame data.

components/hangline/motion.tslines 215–220Open in the code browser

  /** Review only: advance by dt seconds and paint, with no animation frame (filmstrips use it). */
  frame(dt: number): boolean {
    const busy = this.advance(dt);
    this.opts.onFrame(this);
    return busy;
  }

Checking that no text moves by layout during a move meant comparing every text box from one frame to the next.

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

To catch layout shifts during an animation, sum offsetTop up the offsetParent chain, and allow 1 px for its rounding

other:DOMoffsetLeftandoffsetTopinChrome

Rule: If a frame-by-frame layout check reports text jumping during an animation, use offsets summed up the offsetParent chain, not a single offsetTop, and treat 1 px as rounding.
Snippet: // before: relative to an offsetParent that itself changes during the move const top = el.offsetTop; // after: the position against the page, transforms excluded let top = 0; for (let e = el; e; e = e.offsetParent) top += e.offsetTop; const moved = Math.abs(top - lastTop) > 1;
Check: Run the check over a step that moves nothing in the text: 0 reports. Then add a 2 px shift on purpose: it is reported.
Applies to: other: DOM offsetLeft and offsetTop in Chrome
I assumed: offsetTop compares across frames, and has no transforms in it.
What happened: offsetLeft and offsetTop are relative to the offsetParent, which changed while a parent animated, so at first every step looked like a 300 px jump. Summed up the chain, the boxes held still, but each level is rounded to a whole pixel: every height stayed exactly the same while the summed top went from 605 to 606 and back.
The fix: sum the offsets up the chain, and count a move of 1 px or less as rounding.
Evidence: commit 783ff91; the reflow check, 24 of 24 at 1440 and 390.

Shipping it to UpFork

UpFork's importer lists the files a product's registry/ folder uses: the component, its stylesheet, the demo store's data and its pictures. Hangline's demo store keeps its page styles in a stylesheet of its own beside the component.

The import found no warnings, the code scan was clean, and the preview built, yet the save refused the product.

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

UpFork refuses html or body rules in any product stylesheet, demo-only ones too, after a clean import and preview

other:UpForkproductsave(November2026)

Rule: If UpFork's save says a selector "styles every page of the buyer's site" (styles-global), scope it to a class of the product's own, or move page styles to the demo app's layout.
Snippet: /* before: the demo store's stylesheet, a demo-only file */ html, body { margin: 0; background: #eee8de; } /* after: the page's background on the demo's own class; the margin on the demo app's <body> */ .ell-page { height: 100svh; background: #eee8de; }
Check: Save the product in UpFork's editor: no styles-global problem, and the preview's posters look as before.
Applies to: other: UpFork product save (November 2026)
I assumed: a clean import (no warnings), a clean code scan and a preview that builds meant the save would pass, and a demo-only stylesheet could style the page.
What happened: the save refused it: components/ellund/ellund.css:10:1 "html" styles every page of the buyer's site, not just your component. The import's planner, the scan and the preview build do not run the save's stylesheet check.
Why: the save checks every stylesheet, demo-only ones included. It refuses any selector without a class, id or attribute of the product's own, unless the rule holds only custom properties. So :root { --hl-display: … } passes, and so does :where(.dark) .hl[data-theme="auto"], which carries the product's own class. This refines L-0GKH, which met the same check on :root and .dark rules with real properties.
The fix: the page's margin and background live on the demo app's own <body>, which UpFork does not import, and the demo's outer element carries its own background.
Evidence: commit eaceeb0; the save's check run on every file of the old ZIP found exactly that one problem, and 0 on the new one. The posters were compared before and after: no pixel differs.

Make it yours

Install it, then give it your own pictures and data:

npx shadcn@latest add https://upfork.dev/r/clothing-store-product-carousel-react.json

Free: no account or token needed.

garments is the rail: each garment has colourways, and each colourway has a hanger photo with its hook, size, shadow masks and optional outline.
loop (default true) is the endless rail; set it to false for a rail that stops at its ends.
wheel="rail" lets a vertical wheel move the rail instead of scrolling the page.
syncUrl keeps the open piece in the address.

The room's proportions are all in roomGeometry (layout.ts): the camera distance, the rail's angle, the arm's reach and the light's direction. Change them there, and every shadow, hook, tube and hit test follows, because all of them come from the same projection.

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 #763, so anyone can check it hasn’t changed since it was published. Check it.

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

Hangline: a 3D clothing rail in pure CSS, with one camera, swinging hangers and an endless rail

Hangline — 3D Clothing Store Product Carousel for React, with Sizes, Bag & Accessory Tray

What it is

One camera, in numbers

Every piece from one number

A callback that outlives its render

Light on the wall

The shadow of a turned piece

Pointing at a piece in 3D

Steel without stair steps

The projected tube

The motion: one spring for the rail, a pendulum for each piece

The line parts behind a hovered piece

An endless rail with no copies

Loading the rest of an endless rail

What the first view costs

What a move costs the GPU

The phone, and the server's layout

Proving motion, frame by frame

Shipping it to UpFork

Make it yours

Comments

Read next

Cutting AI garment pictures so they hang true: a signed key, hook points and shadows for a CSS rail

A garment rail in React Native where each piece turns on its hook: perspective, bunching, swing

OrbitGallery: a React Three Fiber carousel, a glide that always lands, and nine WebGL traps