@rydr/game-sdk 8.13.0 → 8.15.0

package/dist/ui/rider-rig.js

@@ -60,7 +60,8 @@
  * The scale runs `0 → 1.5 × ftp`, so the rider's own threshold sits at two thirds of the way up with
  * headroom above it for a sprint, and it carries a labelled FTP reference mark. A 150 W rider and a
  * 350 W rider therefore see the same gauge do the same thing for the same effort — never hard-code a
- * raw-watt scale (the same rule as {@link createPowerRace}). Zone colours are computed from %FTP and
+ * raw-watt scale (the same rule as {@link createPowerRace}). The effort colour is a continuous ramp
+ * over %FTP — grey-blue, blue, violet, pink, red, with no band boundaries to jump at — and is
  * are **local to this component**: they are deliberately NOT `@rydr/game-sdk/difficulty`'s ramp, which
  * colours the rider's *chosen calibration level* and would be a different quantity wearing the same
  * paint.
@@ -89,11 +90,16 @@
  * Every gauge is a CONTINUOUS fill; what changes is the paint and the tooltip's orientation.
  *
  *   · `solid` (default) — flat opaque silhouette; a landscape tooltip with the figure beside the
- *     title and the bar under both. Most legible; start here.
- *   · `blueprint` — thin technical linework; a PORTRAIT tooltip whose bar runs vertically and which
- *     carries NO figure at all, only the title and a tall bar marked at FTP. On that variant the bar
- *     IS the reading: a rider glancing at a trainer screen reads a fill long before three digits, and
- *     a number beside it competes with the thing it annotates.
+ *     title and the bar under both. Most legible; start here. Its trainer's FLYWHEEL is the second
+ *     reading — white, haloed in the gauge's own zone colour at a strength the effort sets, so the
+ *     watts are legible from across a room without reading a number. The flywheel and not the front
+ *     wheel: that disc is the one the legs actually drive, while the front wheel is parked on the floor
+ *     driven by nothing.
+ *   · `blueprint` — thin technical linework; a PORTRAIT tooltip whose bar runs vertically, with the
+ *     caption above the figure and both stacked over a tall bar marked at FTP. On that variant the bar
+ *     is still the reading — a rider glancing at a trainer screen reads a fill long before three
+ *     digits — so the figure is set smaller than the landscape one: it answers "exactly how much",
+ *     which the fill cannot, without taking the headline off the bar.
  *   · `neon` — glowing outline; a landscape tooltip whose fill carries a bright leading edge.
  *
  * ## SVG for the drawing, CSS for the tooltip
@@ -112,11 +118,43 @@
  * is built once and a driver mutates cached nodes behind a dirty guard, exactly as `pad-svg.ts` does,
  * so an idle rig costs no DOM writes at 60 Hz.
  *
- * ── Sizing contract (same as the rest of the kit) ──────────────────────────────────────────────
- * Tuned for a trainer screen read from a few feet away while pedalling. Pick a `size` preset; don't
- * override the `.rrig-*` dimensions or wrap it in `transform: scale()`.
+ * ## In a game: a HUD piece
+ *
+ * The rig started as a panel for a page — an onboarding beat, a store page — and a game wants the same
+ * picture pinned into a corner of play while the rider rides. Two options cover that, and they are the
+ * only two a game needs:
+ *
+ * ```ts
+ * const rig = mountRiderRig(gameRoot, {
+ *   ftp: session.identity.ftp,
+ *   width: 300,                                   // any size, not just the three presets
+ *   place: { corner: "bottom-right", margin: 24 },// pinned, floating, click-through
+ *   renderer: createThreeRiderRig,                // optional: the 3D one
+ * });
+ * ```
+ *
+ * `place` is what turns it from a block in flow into a floating overlay; without it nothing about the
+ * component changes. Both are adjustable after mounting (`setWidth`, `setPlacement`) so a game can
+ * find the size and the corner by eye and paste the numbers back — `examples/ui/rig-hud.ts` is exactly
+ * that, a dev page over a fake game screen.
+ *
+ * **One 3D rig per screen.** `createThreeRiderRig` opens its own WebGL context beside the game's own
+ * scene. One HUD widget is a fair price for the picture; three is three contexts the game did not
+ * budget for. If the rig is decoration rather than the subject, the flat renderer is free — it is an
+ * `<svg>` — and it is the default for that reason.
+ *
+ * ── Sizing contract (same as the rest of the kit, with ONE exception) ──────────────────────────
+ * Tuned for a trainer screen read from a few feet away while pedalling. Don't override the `.rrig-*`
+ * dimensions or wrap it in `transform: scale()`.
+ *
+ * The exception is this component's own `width`, and it is narrow: the rig is a PICTURE, not a label,
+ * so it survives being re-sized in a way a keycap or a callout card does not — and a game pinning it
+ * into a corner genuinely cannot work from three fixed widths. `width` scales the tooltip's em base
+ * with the drawing rather than leaving the type behind, and it floors at 140px, below which the watts
+ * stop being readable. That is the whole exception: it licenses nothing elsewhere in the kit.
  * ────────────────────────────────────────────────────────────────────────────────────────────────
  */
+import { applyHudPlacement, anchorHudHost } from "./hud-placement.js";
 const STYLE_ID = "rydr-rider-rig-styles";
 const NS = "http://www.w3.org/2000/svg";
 /**
@@ -132,6 +170,24 @@ const SIZES = {
     md: { w: 330, u: 10 },
     lg: { w: 440, u: 13 },
 };
+/** Narrowest the rig may be drawn. Below this the watts stop being readable and it is a logo, not a gauge. */
+const MIN_WIDTH = 140;
+/**
+ * The em base for a FREE width.
+ *
+ * The three presets are not on a straight line through the origin, but they are close (240/7.5 = 32,
+ * 330/10 = 33, 440/13 = 33.8), so one divisor reproduces all three within a fraction of a pixel and
+ * keeps a hand-picked width in the same family as the presets. Sizing the bubble off the width is the
+ * point: a tooltip pinned at 10px sits comfortably at `md` and covers half the machine at 180px.
+ *
+ * The FLOOR is the part that matters, and it is the kit's own rule rather than a tweak: type has a
+ * minimum physical size on a trainer screen read from a few feet away, and proportion does not get to
+ * override it. Left unclamped, a 170px HUD rig printed its watts at about 8px — present, legible to
+ * nobody, and the exact failure the sizing contract exists to prevent. So below the `sm` preset's base
+ * the bubble stops shrinking and simply takes up more of the picture, which is the right trade: a
+ * small rig whose number can still be read beats a smaller one whose number cannot.
+ */
+const emBase = (width) => Math.max(SIZES.sm.u, width / 33);
 /* ───────────────────────────── geometry ─────────────────────────────
  * One coordinate space, shared by all three designs, in a 200×200 viewBox.
  *
@@ -152,8 +208,20 @@ const WHEEL_R = 26;
  * flat rather than nose-up.
  */
 const AXLE = { x: 78, y: 152 };
-/** Front hub. Its tyre is on the ground (`y + WHEEL_R === GROUND`), and it never turns. */
-const FRONT = { x: 158, y: 152 };
+/**
+ * Front hub. Its tyre is on the ground (`y + WHEEL_R === GROUND`), and it never turns.
+ *
+ * x is 163 and not 158, and the five units are load-bearing. At 158 the hub sat exactly `WHEEL_R` from
+ * the fork crown (`HEADTUBE_BOT`), which put the crown ON the tyre: the fork appeared to start inside
+ * the rubber and the tube read as spearing the wheel — worst in 3D, where a solid blade crosses a
+ * solid tyre with no line-art convention to excuse it. Moving the hub forward opens ~2.3 units of
+ * clearance, so the crown sits above the tyre the way a real fork's does and the blades run down
+ * beside the wheel to the hub.
+ *
+ * It lengthens the wheelbase to ~1.63 wheel diameters, which is still a road bike's number (the
+ * proportion note above allows 1.55; a lowrider starts nearer 2).
+ */
+const FRONT = { x: 163, y: 152 };
 /** Bottom bracket — the crank's centre of rotation, and the anchor the whole rider hangs off. */
 const BB = { x: 112, y: 157 };
 const CRANK_R = 15;
@@ -224,18 +292,63 @@ const FLY_GEAR = 2.1;
 /** Cadence at which the motion streaks reach full strength. */
 const STREAK_FULL_RPM = 95;
 /**
- * %FTP zone colours — LOCAL to this component. See the module header on why this is not
+ * %FTP effort colours — LOCAL to this component. See the module header on why this is not
  * `@rydr/game-sdk/difficulty`'s ramp.
+ *
+ * A CONTINUOUS ramp, not a table of zones. It was six discrete bands (recovery, endurance, tempo,
+ * threshold, VO2, anaerobic) and every boundary was a jump: the bar changed colour in one frame while
+ * the watts behind it had barely moved, which reads as a glitch rather than as a rider getting closer
+ * to their limit. Effort is not quantised, so its colour should not be either — and now that the same
+ * colour also lights the flywheel, a jump was a lamp being switched, not a fire being stoked.
+ *
+ * The path is grey-blue → blue → violet → pink → red: cold and unsaturated when nothing is being
+ * asked, then rising in both saturation and heat. It stays out of green and amber deliberately —
+ * those are the two hues a HUD spends on "healthy" and "warning" elsewhere, and this is neither.
+ *
+ * Interpolation is straight RGB, which is only safe because consecutive stops are close in hue and
+ * all of them are saturated: a lerp from blue to pink through violet never passes near grey, so there
+ * is no muddy midpoint to correct for.
  */
-const ZONES = [
-    { max: 0.55, color: "#6b7f9e", glow: "#9fb4d4" }, // recovery
-    { max: 0.75, color: "#38bdf8", glow: "#7dd3fc" }, // endurance
-    { max: 0.9, color: "#22c55e", glow: "#6ee7a2" }, // tempo
-    { max: 1.05, color: "#eab308", glow: "#fde047" }, // threshold
-    { max: 1.2, color: "#f97316", glow: "#fdba74" }, // vo2
-    { max: Infinity, color: "#ef4444", glow: "#fca5a5" }, // anaerobic
+const EFFORT_RAMP = [
+    { at: 0, rgb: [107, 127, 158] }, // #6b7f9e — soft pedalling: cold, barely there
+    { at: 0.45, rgb: [59, 130, 246] }, // #3b82f6 — blue: working
+    { at: 0.75, rgb: [139, 92, 246] }, // #8b5cf6 — violet
+    { at: 1, rgb: [236, 72, 153] }, // #ec4899 — pink: threshold, where the FTP mark sits
+    { at: 1.3, rgb: [239, 68, 68] }, // #ef4444 — red: over the top, and it should look like it
 ];
-const zoneFor = (ftpPct) => ZONES.find((z) => ftpPct < z.max);
+const hex = (r, g, b) => `#${[r, g, b].map((v) => Math.round(clamp(v, 0, 255)).toString(16).padStart(2, "0")).join("")}`;
+/**
+ * The effort's colour, and the lighter one that goes with it.
+ *
+ * The `glow` half is DERIVED — the base mixed 45% toward white — rather than authored per stop. A
+ * second hand-written table would be a second thing to keep in step for no gain: the light variant is
+ * only ever used as the hot core of a bloom or the outer edge of a shadow, and "the same colour, paler"
+ * is exactly what that wants.
+ *
+ * The input is quantised to 1/100 FTP before anything is computed. Without it the colour is a new
+ * string every frame, and every frame writes two custom properties on the root and invalidates style
+ * for the whole rig — for a difference no eye can see. 150 distinct colours across the scale is
+ * already far finer than the gradient it paints.
+ */
+function zoneFor(ftpPct) {
+    const t = Math.round(clamp(ftpPct, 0, 1.5) * 100) / 100;
+    let lo = EFFORT_RAMP[0];
+    let hi = EFFORT_RAMP[EFFORT_RAMP.length - 1];
+    for (let i = 0; i < EFFORT_RAMP.length - 1; i++) {
+        if (t >= EFFORT_RAMP[i].at && t <= EFFORT_RAMP[i + 1].at) {
+            lo = EFFORT_RAMP[i];
+            hi = EFFORT_RAMP[i + 1];
+            break;
+        }
+    }
+    const span = hi.at - lo.at;
+    const k = span <= 0 ? 0 : clamp((t - lo.at) / span, 0, 1);
+    const c = [0, 1, 2].map((i) => lerp(lo.rgb[i], hi.rgb[i], k));
+    return {
+        color: hex(c[0], c[1], c[2]),
+        glow: hex(lerp(c[0], 255, 0.45), lerp(c[1], 255, 0.45), lerp(c[2], 255, 0.45)),
+    };
+}
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 const lerp = (a, b, t) => a + (b - a) * t;
 const rad = (deg) => (deg * Math.PI) / 180;
@@ -395,7 +508,10 @@ export const RIG_GEOMETRY = {
 export function mountRiderRig(host, opts = {}) {
     ensureStyles();
     const design = opts.design ?? "solid";
-    const { shape, orient } = GAUGE_SPEC[design];
+    const { shape } = GAUGE_SPEC[design];
+    // The SHAPE of the fill stays the design's (a `neon` gauge keeps its leading edge whichever way it
+    // runs); only the direction is overridable.
+    const orient = opts.gauge == null ? GAUGE_SPEC[design].orient : opts.gauge === "portrait" ? "vertical" : "horizontal";
     const preset = SIZES[opts.size ?? "md"];
     const showReadout = opts.readout !== false;
     let ftp = Math.max(1, opts.ftp ?? 200);
@@ -409,8 +525,25 @@ export function mountRiderRig(host, opts = {}) {
     const reduceMotion = typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
     const root = document.createElement("div");
     root.className = `rrig rrig--${design}`;
-    root.style.width = `${preset.w}px`;
-    root.style.setProperty("--rrig-u", `${preset.u}px`);
+    /**
+     * Width and the em base that goes with it, in one place so the two cannot drift.
+     *
+     * A preset keeps its own hand-tuned em base; a free width derives one. Both write the same two
+     * properties, so `setWidth` is just this called again.
+     */
+    function applyWidth(px) {
+        const w = px == null ? preset.w : Math.max(MIN_WIDTH, px);
+        const u = px == null ? preset.u : emBase(w);
+        root.style.width = `${w}px`;
+        root.style.setProperty("--rrig-u", `${u}px`);
+    }
+    applyWidth(opts.width);
+    let placement = opts.place ? { ...opts.place } : undefined;
+    if (placement) {
+        root.classList.add("rrig--placed");
+        applyHudPlacement(root, placement);
+        anchorHudHost(host, placement);
+    }
     const renderer = (opts.renderer ?? createSvgRigRenderer)({ design });
     root.appendChild(renderer.node);
     const anchor = renderer.anchor();
@@ -419,10 +552,11 @@ export function mountRiderRig(host, opts = {}) {
     placeTip(n.tipRoot, orient, anchor, tipOver);
     host.appendChild(root);
     /** Dirty guards for the TOOLTIP. The renderer keeps its own for the drawing. */
-    const last = { frac: -Infinity, zone: "", readout: -Infinity };
+    const last = { frac: -Infinity, zone: "", readout: -Infinity, effort: -Infinity };
     /** Repaint everything the CURRENT state implies. Cheap: every write is guarded. */
     function paint() {
         const effort = smoothPower / ftp;
+        const zone = zoneFor(effort);
         // ── the pose: solved HERE, once, for whatever is drawing ──────────────
         // Nothing that moves is the bike: it is bolted to a fixed machine. Only the crank and the two
         // things the chain turns rotate at all — see the module header.
@@ -458,14 +592,25 @@ export function mountRiderRig(host, opts = {}) {
             // Streaks stand in for the speed the spokes can't show without strobing.
             streak: clamp(smoothCadence / STREAK_FULL_RPM, 0, 1),
             effort,
+            zone,
         });
         // ── the gauge ─────────────────────────────────────────────────────────
         const frac = clamp(smoothPower / (ftp * GAUGE_MAX_FTP_PCT), 0, 1);
-        const zone = zoneFor(smoothPower / ftp);
         if (zone.color !== last.zone) {
             last.zone = zone.color;
-            n.tipRoot.style.setProperty("--rrig-zone", zone.color);
-            n.tipRoot.style.setProperty("--rrig-zone-glow", zone.glow);
+            // On the ROOT, not the tooltip: the tooltip inherits them from here exactly as it did when they
+            // were its own, and the drawing — which is the tooltip's sibling — can now read the same pair.
+            // That is what lets the solid wheel glow in the gauge's colour with no second colour table.
+            root.style.setProperty("--rrig-zone", zone.color);
+            root.style.setProperty("--rrig-zone-glow", zone.glow);
+        }
+        // Effort as a bare number, for a stylesheet to multiply into a length. Quantised: it feeds a glow
+        // whose size nobody can read to the percent, and an unguarded write here would be a style
+        // invalidation every frame for nothing.
+        const effortStep = Math.round(clamp(effort, 0, 1.5) * 20) / 20;
+        if (effortStep !== last.effort) {
+            last.effort = effortStep;
+            root.style.setProperty("--rrig-effort", effortStep.toFixed(2));
         }
         if (Math.abs(frac - last.frac) > 0.002) {
             last.frac = frac;
@@ -500,6 +645,16 @@ export function mountRiderRig(host, opts = {}) {
             tipOver = { ...tipOver, ...next };
             placeTip(n.tipRoot, orient, anchor, tipOver);
         },
+        setWidth(px) {
+            if (Number.isFinite(px))
+                applyWidth(px);
+        },
+        setPlacement(next) {
+            placement = { ...placement, ...next };
+            root.classList.add("rrig--placed"); // a rig mounted in flow can be pinned later
+            applyHudPlacement(root, placement);
+            anchorHudHost(host, placement);
+        },
         setPower(watts) {
             rawPower = Number.isFinite(watts) ? Math.max(0, watts) : 0;
         },
@@ -535,8 +690,11 @@ export function mountRiderRig(host, opts = {}) {
 }
 /* ───────────────────────────── the drawing ───────────────────────────── */
 /** The flat drawing. Everything here is the rig itself; the tooltip is built separately. */
+/** Per-instance suffix for the gradient ids. Two rigs on one page must not share a `<defs>` entry. */
+let uid = 0;
 function buildSvg(design) {
     const svg = svgNode("svg", { viewBox: `0 0 ${VB_W} ${VB_H}`, class: "rrig-svg", role: "img" });
+    const glowId = `rrig-flyglow-${++uid}`;
     svg.setAttribute("aria-label", "A rider pedalling on a direct-drive indoor trainer, with a live watts gauge");
     svg.classList.add(`rrig-svg--${design}`);
     // Ground line first — everything else sits on it.
@@ -569,6 +727,38 @@ function buildSvg(design) {
             y2: FLY.y + (FLY.r - 2) * Math.sin(a),
         }));
     }
+    /**
+     * The neon bloom BEHIND the flywheel.
+     *
+     * A `drop-shadow` was the first attempt and it is the wrong tool: it hugs the shape's own edge, so it
+     * reads as a rim light on the disc rather than as light coming OFF the machine. This is a real
+     * radial fade — bright at the disc, gone by two and a half radii out — which is what a neon glow
+     * actually looks like, and it lets the disc itself stay plain white and crisp in front of it.
+     *
+     * The stops take their colour from the SAME custom properties the gauge is painted from (the root
+     * carries them, see paint()), and the disc's opacity rides on `--rrig-effort`. So the bloom is the
+     * watts, in the drawing, and it cannot disagree with the bar.
+     */
+    // The bloom peaks at the DISC'S EDGE — 38% out, which is where the flywheel's own rim falls in a
+    // circle 2.6 radii wide — and falls away from there. Peaking at the centre (the obvious reading of a
+    // radial gradient) puts the brightest part behind the disc, where it is hidden, and leaves the rim
+    // sitting on the dimmest ring of its own halo. Light comes OFF the wheel; it is brightest where it
+    // leaves it.
+    const glowGrad = svgNode("radialGradient", { id: glowId });
+    glowGrad.appendChild(svgNode("stop", { offset: "0%", class: "rrig-flyglow-mid" }));
+    glowGrad.appendChild(svgNode("stop", { offset: "38%", class: "rrig-flyglow-core" }));
+    glowGrad.appendChild(svgNode("stop", { offset: "62%", class: "rrig-flyglow-mid" }));
+    glowGrad.appendChild(svgNode("stop", { offset: "100%", class: "rrig-flyglow-edge" }));
+    const defs = svgNode("defs");
+    defs.appendChild(glowGrad);
+    svg.appendChild(defs);
+    trainer.appendChild(svgNode("circle", {
+        class: "rrig-fly-glow",
+        cx: FLY.x,
+        cy: FLY.y,
+        r: FLY.r * 2.6,
+        fill: `url(#${glowId})`,
+    }));
     trainer.appendChild(svgNode("circle", { class: "rrig-fly", cx: FLY.x, cy: FLY.y, r: FLY.r }));
     trainer.appendChild(flySpokes);
     trainer.appendChild(flyStreaks);
@@ -695,22 +885,24 @@ function buildTooltip(root, cfg) {
     const panel = document.createElement("div");
     panel.className = "rrig-tip-panel";
     tipRoot.appendChild(panel);
-    // The PORTRAIT variant carries no figure at all — only the title and the bar.
+    // BOTH layouts print the figure; what differs is where it sits and how loud it is.
+    //
+    // Landscape puts it beside the title, on its own row. Portrait stacks it ABOVE the bar — the caption
+    // on top, the number under it — and sets it smaller, because on that variant the bar is still the
+    // reading: it is tall, continuous and marked at FTP, and it answers "how hard am I working" before
+    // any digit is read. The figure is the exact value for when the fill is not enough, not the headline.
     //
-    // On that layout the bar is the reading: it is tall, continuous, and marked at FTP, which answers
-    // "how hard am I working" without a number. Printing the watts beside it competes with the thing it
-    // is annotating, and a rider glancing at a trainer screen reads the fill long before they read
-    // three digits. The landscape variants keep the figure, where there is a row for it.
+    // The portrait variant shipped with no figure at all for exactly that reason, and it went too far:
+    // a rider who wants to know what they are pushing right now had nowhere to look, and the bar cannot
+    // answer that question to the watt. Restored deliberately, sized so it annotates rather than shouts.
     let readoutValue;
     if (cfg.showReadout) {
         const head = document.createElement("div");
         head.className = "rrig-tip-head";
-        if (cfg.orient === "horizontal") {
-            readoutValue = document.createElement("span");
-            readoutValue.className = "rrig-tip-num";
-            readoutValue.textContent = "0";
-            head.appendChild(readoutValue);
-        }
+        readoutValue = document.createElement("span");
+        readoutValue.className = "rrig-tip-num";
+        readoutValue.textContent = "0";
+        head.appendChild(readoutValue);
         const unit = document.createElement("span");
         unit.className = "rrig-tip-unit";
         unit.textContent = cfg.label;
@@ -720,15 +912,30 @@ function buildTooltip(root, cfg) {
     const track = document.createElement("div");
     track.className = "rrig-tip-track";
     panel.appendChild(track);
+    /**
+     * A clipping well inside the track, holding everything that FILLS it.
+     *
+     * The fill is a full-width rectangle pinned to one end, and the track is a rounded well — so at the
+     * rounded end the fill's square corners poked outside the track's silhouette. Worst when the fill is
+     * short, which is exactly when it is most looked at.
+     *
+     * `overflow: hidden` on the TRACK itself would have been the one-liner, and it is wrong here: the
+     * FTP marker is a child of the track and overhangs it on purpose — the tick sticks out 0.4em each
+     * side and the label sits entirely outside it. Clipping the track would clip the label away. So the
+     * clip gets its own box and the marker stays out of it.
+     */
+    const well = document.createElement("div");
+    well.className = "rrig-tip-well";
+    track.appendChild(well);
     const gaugeFill = document.createElement("div");
     gaugeFill.className = "rrig-tip-fill";
-    track.appendChild(gaugeFill);
+    well.appendChild(gaugeFill);
     let tip;
     if (cfg.shape === "tube") {
         tip = document.createElement("i");
         tip.className = "rrig-tip-lead";
         tip.style.opacity = "0";
-        track.appendChild(tip);
+        well.appendChild(tip);
     }
     // The FTP reference. Positioned off `--rrig-ftp` with a -50% translate, so the tick and its label
     // are centred on the same point by construction rather than by two hand-computed coordinates.
@@ -758,6 +965,12 @@ function ensureStyles() {
 const CSS = `
 .rrig { display: block; max-width: 100%; position: relative;
         --rrig-zone: #6b7f9e; --rrig-zone-glow: #9fb4d4; }
+/* Pinned to the game's screen. Click-through in full: it is a picture the game draws over itself, and
+   a HUD piece that ate a click on what is underneath is a bug in every game that mounts one. The
+   position, the offsets and the transform are written inline by applyHudPlacement — only what is true of
+   EVERY placement lives here. max-width is dropped with it: a pinned rig is sized by its own width,
+   and inheriting the host's width would shrink it in a narrow column. */
+.rrig--placed { pointer-events: none; max-width: none; }
 .rrig-svg { display: block; width: 100%; height: auto; overflow: visible; }
 .rrig-svg * { vector-effect: non-scaling-stroke; }
 
@@ -828,9 +1041,15 @@ const CSS = `
    order puts the caption on top without reordering the markup.) Side by side the pair would also
    set the bubble's width from the text rather than from the bar, and the point of the portrait box is
    to be narrow. */
-.rrig-tip--vertical .rrig-tip-panel > .rrig-tip-head { flex-direction: column-reverse; align-items: center; gap: 0.15em; }
-.rrig-tip--vertical .rrig-tip-num { font-size: 1.55em; font-weight: 700; }
-.rrig-tip--vertical .rrig-tip-unit { font-size: 1.7em; letter-spacing: 0.14em; }
+/* Portrait stacks them in DOM order — the figure on top, its unit under it — which is how a reading is
+   written down: the number first, the word that qualifies it second and smaller. (It ran the other way
+   at first, caption over figure; that makes the box announce its own title before it says anything,
+   and the title is the least interesting line in it.) */
+.rrig-tip--vertical .rrig-tip-panel > .rrig-tip-head { flex-direction: column; align-items: center; gap: 0.05em; }
+/* The figure leads and is the larger of the two, while staying clearly under the landscape figure's
+   size — the BAR is still the reading on this variant, and the number annotates it. */
+.rrig-tip--vertical .rrig-tip-num { font-size: 2.8em; font-weight: 800; line-height: 1; }
+.rrig-tip--vertical .rrig-tip-unit { font-size: 1.75em; letter-spacing: 0.12em; }
 
 /* The well is a translucent WHITE, not black.
    Black was the instinct — a recessed groove — but the panel behind it is already dark glass, so a
@@ -842,13 +1061,21 @@ const CSS = `
                   box-shadow: inset 0 1px 2.5px rgba(0,0,0,0.55),
                               inset 0 0 0 1px rgba(255,255,255,0.13); }
 .rrig-tip--horizontal .rrig-tip-track { width: 8.4em; height: 0.9em; }
-/* Portrait: a deliberately BIG bar. With no figure beside it, it has to carry the reading on its own,
+/* Portrait: a deliberately BIG bar. It carries the reading, the figure above it only annotates,
    and the extra height is what makes a change of a few percent visible at a glance. It is nudged off
    centre so the bar and its FTP label sit optically centred as a pair, rather than the bar alone. */
 .rrig-tip--vertical   .rrig-tip-track { width: 1.75em; height: 13em;
                                         align-self: flex-start; margin-left: 0.7em; }
 
-/* continuous fill */
+/* The well: clips the fill to the track's rounded shape. See the note in build() on why the clip is
+   not on the track itself. */
+.rrig-tip-well { position: absolute; inset: 0; overflow: hidden; border-radius: inherit; }
+
+/* continuous fill
+   Its own radius is now decoration rather than structure — the well's curve is what shapes the ends.
+   That also settles the near-empty case: a browser clamps a radius to half the smaller side, so at a
+   height of a pixel this collapsed to a flat sliver. Clipped, the same sliver reads as a thin lens
+   hugging the bottom of the well, which is the truth at 3 W and looks deliberate rather than broken. */
 .rrig-tip-fill { position: absolute; border-radius: 99px; background: var(--rrig-zone);
                  transition: width 90ms linear, height 90ms linear; }
 .rrig-tip--horizontal .rrig-tip-fill { left: 0; top: 0; height: 100%; width: 0; }
@@ -881,7 +1108,11 @@ const CSS = `
 .rrig-tip--horizontal .rrig-tip-ftp b { top: calc(100% + 0.85em); left: 50%; transform: translateX(-50%); }
 .rrig-tip--vertical   .rrig-tip-ftp { bottom: var(--rrig-ftp); left: 0; width: 100%; }
 .rrig-tip--vertical   .rrig-tip-ftp i { top: -1px; left: -0.4em; height: 0; width: calc(100% + 0.8em); }
-.rrig-tip--vertical   .rrig-tip-ftp b { left: calc(100% + 1.1em); top: 50%; transform: translateY(-50%); }
+/* Portrait prints it LARGER, and only portrait. It hangs off the side of the bar, where there is room;
+   the landscape label sits UNDER the track inside the panel's bottom padding, and growing it there
+   pushed it through the bubble's own edge. Same mark, two layouts, one of which has the space. */
+.rrig-tip--vertical   .rrig-tip-ftp b { left: calc(100% + 1.1em); top: 50%; transform: translateY(-50%);
+                                        font-size: 1.5em; }
 /* Portrait needs no bottom gutter: its label sits beside the bar, not under it. */
 .rrig-tip--vertical .rrig-tip-panel { padding: 1em 1.2em 1.3em; min-width: 10em; }
 
@@ -894,6 +1125,16 @@ const CSS = `
 
 /* ── shared skeleton defaults — the designs override the paint, never the shapes ─────────── */
 .rrig-tyre, .rrig-fly, .rrig-cassette, .rrig-chainring { fill: none; }
+
+/* The flywheel's neon bloom. Off everywhere by default: only the design that makes the disc a reading
+   turns it on, and the others keep their own art direction. The three stops are the fade — a hot core
+   in the light zone colour, the saturated one through the middle, nothing at the edge. */
+.rrig-fly-glow { opacity: 0; transition: opacity 140ms linear; }
+.rrig-flyglow-core { stop-color: var(--rrig-zone-glow, #9fb4d4); stop-opacity: 0.9; }
+.rrig-flyglow-mid  { stop-color: var(--rrig-zone, #6b7f9e); stop-opacity: 0.45; }
+.rrig-flyglow-edge { stop-color: var(--rrig-zone, #6b7f9e); stop-opacity: 0; }
+/* Never fully off — a dark machine at rest still reads as switched on — and never fully saturating. */
+.rrig--solid .rrig-fly-glow { opacity: calc(0.12 + var(--rrig-effort, 0) * 0.62); }
 .rrig-frame, .rrig-chain, .rrig-saddle, .rrig-bar, .rrig-crank-arm,
 .rrig-limb, .rrig-torso, .rrig-neck, .rrig-spoke, .rrig-streak { fill: none; }
 .rrig-limb, .rrig-torso, .rrig-neck { stroke-linecap: round; stroke-linejoin: round; }
@@ -916,8 +1157,18 @@ const CSS = `
 .rrig--solid .rrig-pedal { fill: #e6edf9; }
 .rrig--solid .rrig-trainer-body { fill: #2b374e; stroke: #4a5a79; stroke-width: 2; }
 .rrig--solid .rrig-foot { fill: #4a5a79; }
-.rrig--solid .rrig-fly { stroke: #566b90; stroke-width: 4; fill: #1b2434; }
-.rrig--solid .rrig-fly-hub { fill: #7c8fb3; }
+/* The FLYWHEEL is the rig's effort reading, in the drawing itself.
+   It is the right part to carry it and not the front wheel: this disc is the one the rider's legs
+   actually drive, it is the machine's resistance made visible, and it is already spinning with the
+   cadence — so lighting it says "this is what your watts are going into". The front wheel is parked on
+   the floor doing nothing, and glowing it would have said the opposite.
+   White rim and hub, haloed in the gauge's own zone colour, inherited from the root (see paint()) so
+   there is no second colour table. The halo rides on --rrig-effort: barely there at rest, hot at
+   threshold, burning in a sprint. Two shadows — a tight core that keeps the disc crisp, a wide bloom that
+   carries the colour; one big shadow alone washes the spokes out. */
+.rrig--solid .rrig-fly { stroke: #ffffff; stroke-width: 4; fill: #1b2434; }
+.rrig--solid .rrig-fly-spokes .rrig-spoke { stroke: #ffffff; }
+.rrig--solid .rrig-fly-hub { fill: #ffffff; }
 .rrig--solid .rrig-limb { stroke: #f0b429; stroke-width: 8; }
 .rrig--solid .rrig-limb--far { stroke: #a8791b; stroke-width: 7; }
 .rrig--solid .rrig-limb--arm { stroke: #ff7a45; stroke-width: 7; }