Portfolio/docs/redesign/round5.md

# Round 5: The Gantry

Brainstormed autonomously (Luca gave "100% leeway" and asked for the
brainstorming and frontend-design passes). This file records the
understanding, the options weighed and the decisions. Evidence is appended at
the end once the work is done.

## Understanding

What Luca said (round 4 feedback, desktop first, mobile must not break):

1. A cinematic outro that mirrors the intro.
2. Two red lights drift away from the car, faster than it, while scrolling.
   They must stay locked to the car.
3. Remove the white rectangles that flash on chapter changes. Nothing may
   flash more than 3 times a second; no large bright flashes at all.
4. The top bar feels unfinished. It should feel ready and distinctive.
5. and 6. The empty band between the bar and the content (kept clear for
   the 3D signs) is jarring. Keep the signs, make them better, kill the gap.
7. A lighter car on mobile, a cooler car on desktop (headless Blender only).
8. The soundtrack and settings buttons get in the way of content.
9. Card titles sit inside some cards and outside others. One rule.
10. Much more motion, fluid and professional, reduced motion respected.

Assumptions: the night-drive identity, the content and the copy stay. "Signs"
means the chapter exit signs, not the districts. "Professional" rules out
gimmicks such as cursor trails, and anything that slows reading.

## The big one: where do the signs live? (items 4, 5, 6, 8)

The band exists because the signs dock at the top of the frame, and the
content had to stay out of their way.

| Option | For | Against |
| --- | --- | --- |
| A. Signs pass at the screen edges | Real roadside feel | Content spans 1280 of 1440 px. Edges are covered for most chapters. Needs gutters, which is the same waste turned sideways. |
| B. Camera reframes so signs sit beside the content | No new UI | Every chapter layout differs (right rail, left timeline, full diagram). No side is free everywhere. |
| C. Content panels framed by the sign | Strong idea for openers | The sign is in the canvas, under the DOM. A frame has to be drawn twice and kept in sync on every scroll. Fragile. |
| D. Sign flies into the HUD (3D to 2D handoff) | Clear story, frees the band | On its own, the 2D twin is just a label. |
| **E. The top bar becomes an overhead gantry, the sign docks in its window (A + D)** | The bar and the signs become one object. Content gets the full height. The bar gains a reason to exist. | Needs a see-through window in the bar and a clipped reading viewport. |

**Decision: E, "The Gantry".**

- The top bar is redrawn as a steel overhead gantry spanning the road: a
  full-bleed beam with rivet rails, a route line and the exits.
- Its centre holds a **sign window**: a real cut-out the WebGL canvas shows
  through. The reading viewport is clipped at the beam's lower edge, so
  content never shows through the window, and content now starts directly
  under the beam. The gap is gone.
- On each chapter approach, the 3D sign rises out of the road on a small
  overhead truss, grows as it approaches, and locks into the window (the
  handoff). It holds, then passes overhead, out of the top of the frame,
  exactly like driving under a gantry.
- Between signs, the window shows its 2D twin: the current exit, the next
  exit, route progress and the Bucharest clock (the old bottom-right HUD).
- The window is interactive: hover tilts the docked sign toward the pointer.
  Clicking it, or pressing Enter, drives to the next exit.
- The soundtrack and settings controls move into the gantry's right bay as
  compact icon buttons. Nothing floats over the content any more.
- Mobile keeps its compact route bar and the screen-anchored shelf sign. The
  shelf now docks into the bar too, so mobile also loses its band.

## Other decisions

- **Car lights (2), root cause first.** See "Car light bug" below. Fixed at
  the cause, not by hiding symptoms.
- **Flashing (3).** The exit gates (nine near-white frames at about 4.5 Hz
  with a lens flash and a bloom lift) are deleted, along with the flash
  uniform. The chapter change is now carried by DOM motion: the plate
  entrance, the gantry plate swap and the palette drift. Every remaining
  blinking light is audited against the 3 Hz rule.
- **Outro (1).** It mirrors the intro. On arrival, the camera cranes up and
  back to the sun, a telephoto end shot. Letterbox bars close in on every
  tier (as CSS, so even the low tier gets them). A closing credit line made
  only of real facts runs in the lower bar. Leaving the destination reverses
  it. Under reduced motion, the bars appear without a crane.
- **Car (7).** Mobile loads a decimated GLB, built by a headless
  `blender -b` script. Desktop gets better coachwork: clearcoat paint, a
  lit tail bar with a soft halo, and a stronger rim from the key light.
- **Cards (9).** One rule: *chapter titles sit outside, above their plate;
  every card title sits inside its card, first, under its mono plate label.*
- **Motion (10).** Chapter plates and cards rise and unmask on entry, with a
  stagger. Hover lifts cards with an accent rule. The gantry plate swaps on
  every chapter change, and the exits light in sequence. All of it is
  transform and opacity only, behind `prefers-reduced-motion:
  no-preference`. No cursor effects.

## Car light bug (systematic debugging record)

- **Symptom.** While scrolling, two red lights near the car move separately
  from it and faster, then drift away.
- **Evidence.** Frame bursts at 1440, both idle and scrolling, show bodiless
  red lamp pairs with trails and wet-road pools next to the car's flank, at
  the height of its rear diffuser. These are `world/traffic.ts` vehicles:
  they appear only where traffic lanes are, and their speed matches traffic,
  not the car.
- **Root cause.** Traffic was authored at 1x scale while the hero car renders
  at 2.78x (a half-width of about 2.6 units).
  - The fast lane at x = -2.6 puts one lamp at x = -1.8, inside the car's
    footprint. The truck lane at x = 4.9 runs along its flank.
  - Lamp heights (0.95 to 1.95) and lamp spacing match the car's own tail
    lamps.
  - Traffic moves at its relative speed, up to about 110 units/s while
    scrolling. So a bodiless pair of red lamps slides out of, or past, the
    car. It reads as the car's own taillights coming loose.
- **Fix.**
  - Lanes are moved clear of the car's envelope.
  - The car's near field (from 18 units ahead of its nose to behind the
    camera) is a hidden band. Traffic fades out before it and wraps inside
    it, so no light ever passes the car.
  - A unit test pins both rules.
  - The car's own lamps and the wake stay parented to the car, as before.

## Evidence

All captures are 1440x900 unless named otherwise, from the production
preview build on a headed GPU Chromium. They are in `docs/redesign/round5/`.

| Item | Before | After |
| --- | --- | --- |
| 4, 5, 6, 8 Gantry | `gantry-before-1440.webp` | `gantry-after-1440-incoming.webp`, `-docked.webp`, `-idle.webp`, `gantry-after-1024.webp`, `gantry-after-390.webp` |
| 1 Outro | `outro-before-1440.webp` | `outro-after-1440.webp` |
| 7 Car | left half of `car-before-after-desktop.webp` | right half; `car-lite-390.webp` |
| 9, 10 Cards and motion | `cards-before-1440.webp` | `cards-after-1440.webp` |

- **Gantry docking (headed run, clicking Profile).** idle at 300 ms,
  incoming at 700 ms, docked from 1000 to 2600 ms, passing at 3300 ms, idle
  at 3700 ms. The face lands within 2 px of the window at 1440x900,
  1920x1080, 1024x768, 390x844 and 844x390 (unit tests). Clicking the
  window, or Enter on it, drives to the next exit (Start to Profile, then
  Experience) at 1440 and 390.
- **A mask bug found on the way.** The window cut-out used `--window-x`
  as a `mask-position`. Percentages there resolve against the box minus the
  layer, so the hole sat 128 px left of the window and the beam hid half of
  the sign. The cut-out now has its own `--window-mask-x`.
- **Car.** Phones and the low tier load the lite model: 31,288 to 11,027
  faces, 1.19 MB to 0.50 MB raw. The transfer saving is small (149 KB to
  143 KB), because the geometry already compresses well. The real wins are
  parse time and GPU memory.
- **fps (same machine, same script, Intel Arc iGPU, headed).**

  | | start | infrastructure | builds | toolkit | contact |
  | --- | --- | --- | --- | --- | --- |
  | Before | 70.1 | 82.6 | 83.8 | 81.8 | 87.2 |
  | After | 68.7 | 83.5 | 79.7 | 83.7 | 95.1 |