@rydr/game-sdk 8.11.0 → 8.12.0

package/dist/ui/rider-rig.d.ts

@@ -0,0 +1,315 @@
+/**
+ * RIDER RIG — a rider on their trainer, pedalling, with their watts rising out of the machine.
+ *
+ * The one drawing in this kit whose subject is **the bike itself**. Everything else in
+ * `@rydr/game-sdk/ui` teaches the rider about the *pad* — which button, which combination, which
+ * lesson — and a game built from those pieces alone would tell a new player that the controller is
+ * the thing in their hands. It isn't, or not only: the trainer is half of it. This component is the
+ * picture that says so, and it exists to be put on the screens where that has to land — an
+ * onboarding beat, a "how this game works" panel, a store page, the pause screen of a game whose
+ * whole mechanic is effort.
+ *
+ * ```ts
+ * const rig = mountRiderRig(panel, { design: "solid", ftp: session.identity.ftp });
+ *
+ * // each frame:
+ * rig.setPower(session.hardware.current.power);
+ * rig.setCadence(session.hardware.current.cadence);
+ * rig.tick(dt);
+ * ```
+ *
+ * ⚠️ **Not to be confused with {@link mountControlTrainer}**, which lives one folder over in
+ * `./controller/`. English "trainer" means both the *turbo trainer* and the *coach*, and the SDK has
+ * one of each: `mountControlTrainer` is the COACH — a guided lesson that watches the rider perform a
+ * combination. This is the TURBO TRAINER — the physical machine, drawn. They share no code and
+ * answer different questions. If you want to teach a control, you want the other one.
+ *
+ * ## There is no rear wheel, and that is the point
+ *
+ * This is a **direct-drive** trainer, the kind RYDR runs on. The rear wheel comes OFF and the bike's
+ * dropouts bolt straight onto the trainer's own axle, so the chain drives the trainer's cassette
+ * directly — that junction is where the connection to the platform physically happens. Drawing a
+ * wheel-on trainer instead (a tyre pressed onto a spinning roller) would be a picture of a different,
+ * older machine, and would quietly teach a newcomer that the trainer is an accessory the bike sits on
+ * top of rather than a part of the drivetrain.
+ *
+ * It also settles what may move. **The bike is still.** It is bolted to a fixed machine: the frame
+ * does not sway, and the front wheel — parked on the floor, driven by nothing — does not turn. The
+ * only things that rotate are the ones the rider's legs actually drive: the crank, the trainer's
+ * cassette, and its flywheel. A drawing whose frame rocked or whose front wheel spun would be
+ * describing a bike going somewhere, which is the one thing this bike is not doing.
+ *
+ * ## Two engines, deliberately separate
+ *
+ * **Cadence turns the legs. Power fills the gauge.** Nothing crosses over, and that separation is the
+ * entire pedagogical content of the animation:
+ *
+ *   · `setCadence(rpm)` drives the crank, the legs, the cassette and the flywheel. It is the
+ *     *movement*.
+ *   · `setPower(watts)` drives the gauge and the rider's posture — the torso folding down onto the
+ *     bars, and past ~110% FTP a rise out of the saddle. It is the *effort*.
+ *
+ * Driving both from watts would be less code and would teach the opposite of the truth: that a rider
+ * spinning fast against no resistance is doing something. Two riders at 90 rpm, one at 100 W and one
+ * at 300 W, have identical legs and nothing else in common — and which of them the game is reading is
+ * exactly what a newcomer has to understand. So the legs say "you are pedalling" and only the gauge
+ * and the posture say "you are pushing".
+ *
+ * ## The gauge is FTP-relative, and it leaves the machine
+ *
+ * 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
+ * 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.
+ *
+ * It is presented as a **glass tooltip leaving the machine** — a bubble with a pointer into the
+ * trainer's shoulder, the watts printed large at the top and the bar below them. The bar's
+ * orientation drives the shape of the box: a landscape bubble where it fills left → right, a portrait
+ * one where it fills bottom → top. Two reasons, and
+ * neither is decoration. Where the number comes from is part of what the picture says: these watts
+ * are measured by *that* machine, not floating beside the bike. And the bubble is what gives every
+ * label somewhere to live: the number, its unit and the FTP mark all sit INSIDE the glass, so none of
+ * them is ever printed over the frame, the rider or the trainer. The version before it stood a bare
+ * column next to the machine and hung the FTP label off its side, where it landed on the gauge's own
+ * rungs.
+ *
+ * Feed it raw `power`, not `smoothedPower`. It keeps both: the numeric readout shows the true
+ * instantaneous value, while the bar itself follows an internal EMA so it climbs smoothly between the
+ * trainer's sparse (~1–4 Hz) updates. That is the split `HardwareSnapshot.power` documents, resolved
+ * here once so no caller has to hold two numbers.
+ *
+ * ## One geometry, three paints
+ *
+ * `design` picks the look; the skeleton, the joint solving and the timing are shared. Three art
+ * directions because a component this decorative has to sit inside games that look nothing alike:
+ *
+ * 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.
+ *   · `neon` — glowing outline; a landscape tooltip whose fill carries a bright leading edge.
+ *
+ * ## SVG for the drawing, CSS for the tooltip
+ *
+ * The rider, the bike and the trainer are one inline SVG: they are a picture, made of coordinates and
+ * joints. The watts tooltip is an HTML element positioned over it, because it is a box with rows of
+ * text — and that is the kit's own split, the one `controller-map.ts` already makes when it draws its
+ * callout cards in HTML and only the LINES between them in SVG. Boxes are CSS; shapes are SVG.
+ *
+ * The tooltip being CSS is what buys real `backdrop-filter` glass, and it removes a whole class of
+ * bug: its FTP label is placed off one custom property with a -50% translate, so it is centred on its
+ * own tick by construction rather than by a coordinate computed twice.
+ *
+ * Self-contained like the rest of the kit: it injects its own scoped `.rrig-*` stylesheet once into
+ * `<head>`, pulls in no three.js, and reads no global CSS. It also never renders per frame — the SVG
+ * 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()`.
+ * ────────────────────────────────────────────────────────────────────────────────────────────────
+ */
+/** The three art directions. See the module header for when to reach for which. */
+export type RiderRigDesign = "solid" | "blueprint" | "neon";
+export interface RiderRigOptions {
+    /** Which look. Default `"solid"` — the highest-contrast of the three. */
+    design?: RiderRigDesign;
+    /**
+     * The rider's FTP in watts, which is what the gauge is a proportion of. Default 200.
+     *
+     * Pass `session.identity.ftp`. Getting this wrong doesn't break the drawing, it just mis-scales the
+     * gauge — a 350 W rider against a 200 W scale would sit pinned at the top.
+     */
+    ftp?: number;
+    /** Width preset. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Show the numeric watts readout. Default `true`. */
+    readout?: boolean;
+    /** The caption under the readout. Default `"WATTS"`. */
+    label?: string;
+    /**
+     * Turn the legs before any cadence arrives, so a static screenshot or a page with no trainer still
+     * shows the idea rather than a frozen rider. Default 0 (still).
+     */
+    idleCadence?: number;
+    /**
+     * Override where the watts tooltip sits, when the renderer's own anchor is not what you want.
+     *
+     * Every field is optional and falls back to the anchor {@link RigRenderer.anchor} reports, so
+     * `{ y: 0.7 }` nudges it up without disturbing the rest. Positions are FRACTIONS of the drawing's
+     * box (x from the left, y from the top) and `arrow` is in em from the tooltip's own left edge — the
+     * same units the renderer answers in, so a value found by eye can be pasted straight in.
+     */
+    tip?: TipPlacement;
+    /**
+     * What DRAWS the rig. Default: the flat SVG drawing.
+     *
+     * Pass `createThreeRiderRig` from `@rydr/game-sdk/three` to render it in 3D. The component works
+     * against it unchanged, because it never draws the rig itself — see the renderer seam below.
+     */
+    renderer?: RigRendererFactory;
+}
+/** Where the watts tooltip sits. See {@link RiderRigOptions.tip}. */
+export interface TipPlacement {
+    /** Fraction of the width, from the left, where the pointer's tip should land. */
+    x?: number;
+    /** Fraction of the height, from the TOP, where the pointer's tip should land. */
+    y?: number;
+    /** How far along the tooltip's own bottom edge the pointer hangs, in em. */
+    arrow?: number;
+}
+export interface RiderRig {
+    readonly root: HTMLDivElement;
+    /**
+     * Move the tooltip after mounting — the same fields as {@link RiderRigOptions.tip}, merged over
+     * what is already set.
+     *
+     * Exists so a placement can be found by eye rather than by arithmetic: a dev panel drives this
+     * live, and the values it lands on are the values you pass to `tip`. See `examples/ui/rig3d.ts`.
+     */
+    setTipPlacement(next: TipPlacement): void;
+    /** Latest raw watts — drives the readout, the posture, and (smoothed) the gauge. */
+    setPower(watts: number): void;
+    /** Latest cadence in rpm — drives the crank, the legs, the cassette and the flywheel. */
+    setCadence(rpm: number): void;
+    /** Re-scale the gauge in place, for a rider who retunes their FTP mid-session. */
+    setFtp(ftp: number): void;
+    /** Advance the animation. `dt` in seconds. */
+    tick(dt: number): void;
+    dispose(): void;
+}
+/**
+ * The default renderer: the flat SVG drawing, which is exactly what the component did inline before
+ * the seam existed. Nothing about the flat rig changed.
+ *
+ * It keeps its OWN dirty guards. Skipping a DOM write is the cheap win here, so the guards belong
+ * next to the writes rather than in the component — and a WebGL renderer's idea of "nothing to do" is
+ * a different question entirely (whether to draw a frame at all), which is its business, not ours.
+ *
+ * Seeded to `-Infinity`, NOT `NaN`: every guard is a `Math.abs(next - last) > eps` test, and any
+ * comparison against `NaN` is false, so a `NaN` seed silently suppresses the FIRST paint — and with
+ * it every write that never becomes dirty again.
+ */
+export declare function createSvgRigRenderer({ design }: {
+    design: RiderRigDesign;
+}): RigRenderer;
+/** A point in the shared 200×200 drawing space, y DOWN. */
+export interface RigPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The drawing space every renderer works in: a 200×200 box with y pointing DOWN and the floor at
+ * `GROUND`. A 3D renderer maps it once (x − 100, GROUND − y) and is done.
+ */
+export declare const RIG_GEOMETRY: {
+    readonly VB_W: 200;
+    readonly VB_H: 200;
+    readonly GROUND: 178;
+    readonly WHEEL_R: 26;
+    readonly AXLE: {
+        x: number;
+        y: number;
+    };
+    readonly FRONT: {
+        x: number;
+        y: number;
+    };
+    readonly BB: {
+        x: number;
+        y: number;
+    };
+    readonly CRANK_R: 15;
+    readonly CHAINRING_R: 8;
+    readonly CASSETTE_R: 7;
+    readonly SEAT_CLUSTER: {
+        x: number;
+        y: number;
+    };
+    readonly SADDLE: {
+        x: number;
+        y: number;
+    };
+    readonly HEADTUBE_TOP: {
+        x: number;
+        y: number;
+    };
+    readonly HEADTUBE_BOT: {
+        x: number;
+        y: number;
+    };
+    readonly BAR: {
+        x: number;
+        y: number;
+    };
+    readonly FLY: {
+        x: number;
+        y: number;
+        r: number;
+    };
+    /** The rider's rest hip and shoulder — a renderer building a skeleton needs the spine's length. */
+    readonly HIP0: {
+        x: number;
+        y: number;
+    };
+    readonly SHOULDER0: {
+        x: number;
+        y: number;
+    };
+    /**
+     * The point on the trainer the watts tooltip points at — its top face, where the machine is tall
+     * enough for a pointer to meet it. Both renderers answer {@link RigRenderer.anchor} from this.
+     */
+    readonly TRAINER_ANCHOR: RigPoint;
+};
+/** One frame of the rig, fully solved. Everything a renderer needs and nothing it has to work out. */
+export interface RigPose {
+    hip: RigPoint;
+    shoulder: RigPoint;
+    head: RigPoint;
+    elbow: RigPoint;
+    kneeNear: RigPoint;
+    kneeFar: RigPoint;
+    pedalNear: RigPoint;
+    pedalFar: RigPoint;
+    /** Degrees. The crank, and the two things the chain turns. */
+    crankAngle: number;
+    cassetteAngle: number;
+    flyAngle: number;
+    /** 0→1 motion-blur strength for the spinning parts, from cadence. */
+    streak: number;
+    /** power / ftp, for anything a renderer wants to drive off effort. */
+    effort: number;
+}
+export interface RigRenderer {
+    /** The node to put in the rig's root: an `<svg>` for the default, a `<canvas>` for three.js. */
+    readonly node: Element;
+    setPose(pose: RigPose): void;
+    /**
+     * Where the tooltip's pointer should land, as fractions of the node's box (x from the left, y from
+     * the TOP). This is {@link RIG_GEOMETRY.TRAINER_ANCHOR} expressed in the renderer's own frame.
+     *
+     * It has to be the renderer's answer, not the component's: the flat drawing is an orthographic side
+     * view where the anchor is a fixed percentage, while a 3D renderer projects it through a camera and
+     * lands it somewhere else entirely. Hard-coding the flat percentages put the tooltip clean across
+     * the middle of the 3D machine. Same reason `PadRenderer.partRect` exists.
+     */
+    anchor(): {
+        x: number;
+        y: number;
+    };
+    dispose(): void;
+}
+export type RigRendererFactory = (opts: {
+    design: RiderRigDesign;
+}) => RigRenderer;
+export declare function mountRiderRig(host: HTMLElement, opts?: RiderRigOptions): RiderRig;
+//# sourceMappingURL=rider-rig.d.ts.map

package/dist/ui/rider-rig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rider-rig.d.ts","sourceRoot":"","sources":["../../src/ui/rider-rig.ts"],"names":[],"mappings":"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"}