@rydr/game-sdk 7.0.1 → 8.0.0

package/dist/ui/controller/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Pad layout descriptors — the DATA behind the controller drawing.
+ *
+ * One renderer ({@link buildPadSvg}) draws every controller from one of these. The alternative, a
+ * hand-drawn SVG per brand, would duplicate the `data-part` contract, the press/idle CSS, the stick
+ * group structure and the per-part titles once per brand — and every new part would have to be added
+ * everywhere.
+ *
+ * **Parts are keyed by POSITION, never by letter.** That is load-bearing, and it is the whole reason a
+ * game can hand us one action list and get a correct drawing on every controller: the canonical
+ * {@link ButtonName} vocabulary is positional (`DIAMOND_DOWN` *is* "the bottom button" on every
+ * device), but a Switch Pro prints `A` on the right and `B` on the bottom — the mirror of an Xbox pad.
+ * Keying by position lets the renderer stay brand-agnostic while every letter comes from
+ * `buttonLabel()` in `protocol/glyphs.ts`, the only module allowed to contain one.
+ *
+ * Ported from the platform shell's `pad-layouts/`, which is where this geometry was first tuned. The
+ * coordinate tables are deliberately unchanged so the two stay interchangeable — see the note on
+ * {@link PAD_BODY_PATH} about the usable interior.
+ */
+import type { GlyphSet } from "../../protocol/glyphs.js";
+/**
+ * Which silhouette to draw.
+ *
+ * A {@link GlyphSet} plus the shapes that need their own drawing regardless of lettering: a Joy-Con
+ * pair is a Nintendo device but is two slim halves rather than one shell, so `"joycon"` is a *drawing*
+ * key rather than a glyph family — reachable only by asking for it explicitly.
+ */
+export type PadBrandKey = GlyphSet | "joycon";
+/** Every drawable, highlightable part of a controller. Positional names only. */
+export type PadPart = "dpadUp" | "dpadDown" | "dpadLeft" | "dpadRight" | "faceTop" | "faceRight" | "faceBottom" | "faceLeft" | "lb" | "rb" | "lt" | "rt" | "lstickPress" | "rstickPress" | "start" | "select" | "home";
+export type PartGeom = {
+    kind: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    kind: "rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rx?: number;
+} | {
+    kind: "path";
+    d: string;
+};
+export interface PartSpec {
+    geom: PartGeom;
+    /** Text glyph centred on the part. Omitted for parts the brand leaves blank. */
+    glyph?: string;
+    /** Vector glyph instead of text — PlayStation's ✕ ◯ ▢ △. Drawn centred on the part. */
+    glyphPath?: string;
+    /** Accessible / tooltip name, e.g. "A button (bottom)". */
+    label: string;
+}
+export interface StickSpec {
+    cx: number;
+    cy: number;
+    /** Recess radius and thumb-cap radius, in viewBox units. */
+    well: number;
+    cap: number;
+    /** Cap travel at full deflection, viewBox units. */
+    travel: number;
+    label: string;
+}
+export interface TriggerSpec {
+    geom: PartGeom;
+    /**
+     * Travel meter, filled bottom-up as the value goes 0 → 1.
+     *
+     * The platform drives this from real analog trigger travel. In *this* protocol `LT`/`RT` are plain
+     * clicks — `buttons.ts` says so explicitly, and protocol 27 removed the trigger axes — so the SDK
+     * drives it `0`/`1` from button state. The rect stays because a filled meter still reads as "held",
+     * and keeping the geometry identical is what lets the two sides share these tables.
+     */
+    meter: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        rx?: number;
+    };
+    glyph: string;
+    label: string;
+}
+export interface PadLayout {
+    brand: PadBrandKey;
+    /** Used in the drawing's accessible name, e.g. "Xbox-style controller". */
+    displayName: string;
+    /** SHARED across every layout so host CSS never varies and swapping brands can't reflow. */
+    viewBox: readonly [number, number, number, number];
+    body: {
+        d: string;
+    };
+    /**
+     * Everything below the face buttons is OPTIONAL, because not every controller has it and drawing a
+     * control the rider cannot press is worse than drawing nothing. The Zwift family is the case that
+     * forced this: it reports a d-pad and the four face buttons and *nothing else* — no sticks, no
+     * triggers, no stick clicks, no system buttons (see `layouts/zwift.ts`). The renderer skips whatever
+     * is absent, and `PadDriver` no-ops on it.
+     */
+    dpad?: Record<"up" | "down" | "left" | "right", PartSpec>;
+    face: Record<"top" | "right" | "bottom" | "left", PartSpec>;
+    bumpers?: {
+        l: PartSpec;
+        r: PartSpec;
+    };
+    triggers?: {
+        l: TriggerSpec;
+        r: TriggerSpec;
+    };
+    sticks?: {
+        l: StickSpec;
+        r: StickSpec;
+    };
+    system?: {
+        start?: PartSpec;
+        select?: PartSpec;
+        home?: PartSpec;
+    };
+    /** Non-interactive brand furniture (DualSense touchpad, Switch capture bar, Zwift handlebar). */
+    decor?: readonly {
+        geom: PartGeom;
+        opacity?: number;
+    }[];
+}
+/**
+ * Shared canvas for all layouts: `[minX, minY, width, height]`.
+ *
+ * The origin starts at **y −20**, above the shell's top edge, purely to give the shoulder row room.
+ * Triggers and bumpers are the only parts drawn off the body — stacked flush they read as one
+ * four-line block, so the negative band lets each sit clear of the other and of the shell, the way
+ * they're separated on the hardware.
+ */
+export declare const PAD_VIEWBOX: readonly [number, number, number, number];
+/**
+ * The gamepad silhouette, shared by every gamepad-shaped layout.
+ *
+ * One body, not four: the meaningful difference between brands is where the CONTROLS sit (Xbox offsets
+ * its sticks diagonally, DualSense puts both low and symmetric, Switch mirrors Xbox), not the outline
+ * — and separately hand-tuned outlines are separate chances for a control to end up drawn outside the
+ * shell. The two-piece devices (Joy-Con, Zwift) carry their own body path because their shape, not
+ * just their control placement, is genuinely different.
+ *
+ * Its usable interior, which every control must stay inside:
+ *   top edge      x  58 → 182 at y 22 — bumpers must fit within THIS, not the wider waist below
+ *   waist         x  28 → 212 around y 54 (where the face diamond and sticks sit)
+ *   central mass  down to y 98; below that only the grips, under x 30–80 and x 160–210
+ * Triggers are the one deliberate exception: they sit ABOVE the top edge, as on the hardware.
+ */
+export declare const PAD_BODY_PATH: string;
+/** Centre of a part, for placing its glyph and for anchoring a callout line at it. */
+export declare function partCentre(g: PartGeom): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/ui/controller/types.d.ts.map

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

package/dist/ui/controller/types.js

@@ -0,0 +1,61 @@
+/**
+ * Pad layout descriptors — the DATA behind the controller drawing.
+ *
+ * One renderer ({@link buildPadSvg}) draws every controller from one of these. The alternative, a
+ * hand-drawn SVG per brand, would duplicate the `data-part` contract, the press/idle CSS, the stick
+ * group structure and the per-part titles once per brand — and every new part would have to be added
+ * everywhere.
+ *
+ * **Parts are keyed by POSITION, never by letter.** That is load-bearing, and it is the whole reason a
+ * game can hand us one action list and get a correct drawing on every controller: the canonical
+ * {@link ButtonName} vocabulary is positional (`DIAMOND_DOWN` *is* "the bottom button" on every
+ * device), but a Switch Pro prints `A` on the right and `B` on the bottom — the mirror of an Xbox pad.
+ * Keying by position lets the renderer stay brand-agnostic while every letter comes from
+ * `buttonLabel()` in `protocol/glyphs.ts`, the only module allowed to contain one.
+ *
+ * Ported from the platform shell's `pad-layouts/`, which is where this geometry was first tuned. The
+ * coordinate tables are deliberately unchanged so the two stay interchangeable — see the note on
+ * {@link PAD_BODY_PATH} about the usable interior.
+ */
+/**
+ * Shared canvas for all layouts: `[minX, minY, width, height]`.
+ *
+ * The origin starts at **y −20**, above the shell's top edge, purely to give the shoulder row room.
+ * Triggers and bumpers are the only parts drawn off the body — stacked flush they read as one
+ * four-line block, so the negative band lets each sit clear of the other and of the shell, the way
+ * they're separated on the hardware.
+ */
+export const PAD_VIEWBOX = [0, -20, 240, 180];
+/**
+ * The gamepad silhouette, shared by every gamepad-shaped layout.
+ *
+ * One body, not four: the meaningful difference between brands is where the CONTROLS sit (Xbox offsets
+ * its sticks diagonally, DualSense puts both low and symmetric, Switch mirrors Xbox), not the outline
+ * — and separately hand-tuned outlines are separate chances for a control to end up drawn outside the
+ * shell. The two-piece devices (Joy-Con, Zwift) carry their own body path because their shape, not
+ * just their control placement, is genuinely different.
+ *
+ * Its usable interior, which every control must stay inside:
+ *   top edge      x  58 → 182 at y 22 — bumpers must fit within THIS, not the wider waist below
+ *   waist         x  28 → 212 around y 54 (where the face diamond and sticks sit)
+ *   central mass  down to y 98; below that only the grips, under x 30–80 and x 160–210
+ * Triggers are the one deliberate exception: they sit ABOVE the top edge, as on the hardware.
+ */
+export const PAD_BODY_PATH = "M 58 22 L 182 22 C 200 22 210 34 212 52 L 220 94 C 226 122 214 146 192 146 " +
+    "C 178 146 167 137 162 124 L 156 110 C 152 102 145 98 137 98 L 103 98 " +
+    "C 95 98 88 102 84 110 L 78 124 C 73 137 62 146 48 146 C 26 146 14 122 20 94 " +
+    "L 28 52 C 30 34 40 22 58 22 Z";
+/** Centre of a part, for placing its glyph and for anchoring a callout line at it. */
+export function partCentre(g) {
+    switch (g.kind) {
+        case "circle":
+            return { x: g.cx, y: g.cy };
+        case "rect":
+            return { x: g.x + g.w / 2, y: g.y + g.h / 2 };
+        case "path":
+            // Paths carry their own glyph placement; none do today. Callers that need a real centre for a
+            // path part should measure the rendered node instead (the map view does exactly that).
+            return { x: 0, y: 0 };
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/ui/controller/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/ui/controller/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAsFH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAA8C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAEzF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,6EAA6E;IAC7E,uEAAuE;IACvE,8EAA8E;IAC9E,+BAA+B,CAAC;AAElC,sFAAsF;AACtF,MAAM,UAAU,UAAU,CAAC,CAAW;IACpC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;QAC9B,KAAK,MAAM;YACT,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,KAAK,MAAM;YACT,8FAA8F;YAC9F,uFAAuF;YACvF,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/ui/index.d.ts

@@ -9,6 +9,13 @@
  * overlay, and the pre-assembled bar that composes both — so every game with a heat mechanic shares
  * one look and can take just the pieces it needs (a game drawing its own bar takes only the cues).
  *
+ * …and the **controller family** (`./controller/`), for showing a rider their whole control scheme:
+ * `mountControllerPad` draws the controller in their hands and lights it as they press;
+ * `mountControllerMap` surrounds it with action callouts joined by lines to their buttons; and
+ * `mountComboDemo` animates the combination one action needs. A game describes its controls once as a
+ * declarative `ControlAction[]` and the SDK owns the rest — which physical button that is on the
+ * rider's pad, the letter printed on it, the layout, and the animation.
+ *
  * Self-contained, like `@rydr/game-sdk/three`'s perf-overlay: it injects its own scoped `.rydr-ui-*`
  * CSS once into `<head>`, depends on no global styles or CSS variables, and pulls in no three.js — so
  * a game gets the look just by constructing a component. Wire any keycap to real input by passing the
@@ -26,6 +33,7 @@
  * ──────────────────────────────────────────────────────────────────────────────────────────────
  */
 export * from "./keycap.js";
+export * from "./controller/index.js";
 export * from "./card.js";
 export * from "./action-card.js";
 export * from "./action-diamond.js";
@@ -35,7 +43,7 @@ export * from "./choice-card.js";
 export * from "./labeled-diamond.js";
 export * from "./solo-labeled-diamond.js";
 export * from "./rarity-card.js";
-export * from "./pause-menu.js";
+export * from "./option-menu.js";
 export * from "./power-race.js";
 export * from "./admin-nav.js";
 export * from "./heat-vignette.js";

package/dist/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/dist/ui/index.js

@@ -9,6 +9,13 @@
  * overlay, and the pre-assembled bar that composes both — so every game with a heat mechanic shares
  * one look and can take just the pieces it needs (a game drawing its own bar takes only the cues).
  *
+ * …and the **controller family** (`./controller/`), for showing a rider their whole control scheme:
+ * `mountControllerPad` draws the controller in their hands and lights it as they press;
+ * `mountControllerMap` surrounds it with action callouts joined by lines to their buttons; and
+ * `mountComboDemo` animates the combination one action needs. A game describes its controls once as a
+ * declarative `ControlAction[]` and the SDK owns the rest — which physical button that is on the
+ * rider's pad, the letter printed on it, the layout, and the animation.
+ *
  * Self-contained, like `@rydr/game-sdk/three`'s perf-overlay: it injects its own scoped `.rydr-ui-*`
  * CSS once into `<head>`, depends on no global styles or CSS variables, and pulls in no three.js — so
  * a game gets the look just by constructing a component. Wire any keycap to real input by passing the
@@ -26,6 +33,7 @@
  * ──────────────────────────────────────────────────────────────────────────────────────────────
  */
 export * from "./keycap.js";
+export * from "./controller/index.js";
 export * from "./card.js";
 export * from "./action-card.js";
 export * from "./action-diamond.js";
@@ -35,7 +43,7 @@ export * from "./choice-card.js";
 export * from "./labeled-diamond.js";
 export * from "./solo-labeled-diamond.js";
 export * from "./rarity-card.js";
-export * from "./pause-menu.js";
+export * from "./option-menu.js";
 export * from "./power-race.js";
 export * from "./admin-nav.js";
 export * from "./heat-vignette.js";

package/dist/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/dist/ui/keycap.d.ts

@@ -2,20 +2,26 @@
  * KEYCAP — a DOM/CSS keycap of the controller face buttons (zero dependencies), so a game can show
  * "which button to press" in a consistent visual language. Two shapes:
  *
- *   • "full" — the classic diamond: the active button enlarged + coloured, the other three small + grey.
+ *   • "full" — the classic diamond: the active button enlarged, the other three small + grey.
  *   • "solo" — light variation: JUST the active button (the idle siblings removed).
  *
  * The keycap is a small STATE MACHINE: it can pulse (the bouncing attract animation), show a pressed
- * sink, run a depleting COOLDOWN ring + countdown, render colored or neutral ("mono"), and hide.
+ * sink, run a depleting COOLDOWN ring + countdown, and hide.
+ *
+ * **Mono by default** — a white face with a dark letter, which is the RYDR look everywhere (the shell
+ * draws all of its own chrome that way). The per-button role hues still exist behind
+ * `colored: true`, for a deliberately loud isolated affordance or to show the palette itself.
  *
  * Two button families share that machine: `createKeycap` for the A/B/Y/Z face buttons (a letter on
  * the active pip) and `createDpadKeycap` for the UP/DOWN/LEFT/RIGHT directional buttons (a white
  * chevron on a steel-grey pip, rotated per direction). They differ ONLY in the face drawn and the
  * button name the press-wiring listens for; everything else is identical.
  *
- * A third factory, `createLabelKeycap`, covers the buttons whose printed name is a WORD rather than a
- * letter — the system/options button, the shoulder triggers, the stick clicks — as a PILL instead of a
- * circle, since "Options" cannot fit in a pip sized for one glyph.
+ * A third factory, `createButtonKeycap`, covers what's left — the system/options button, the shoulder
+ * triggers, the stick clicks — and draws each the way the pad does: `OPTIONS` as a round pip with the
+ * pad's ICON (`☰` on Xbox/DualSense, `+` on a Switch Pro), since it's a small round key like the
+ * others; the triggers and stick clicks as a text PILL, since those are printed with a word ("LT",
+ * "L2", "LS") that no pip sized for one glyph could hold.
  */
 import type { ButtonName, ButtonEdge } from "../protocol/index.js";
 import { type GlyphSet } from "../protocol/glyphs.js";
@@ -40,7 +46,12 @@ export interface ButtonSource {
 export interface KeycapOptions {
     /** "solo" (default) shows only the active button; "full" shows the 4-button diamond. */
     variant?: KeycapVariant;
-    /** Per-button hue (default true). `false` → a neutral palette (full colour can be too loud). */
+    /**
+     * Per-button hue. **Default `false` — mono** (a white face with a dark letter), which is the RYDR
+     * look: the shell draws every keycap in its chrome that way, so a coloured cap is the one loud key
+     * on the screen. Pass `true` only for a deliberately loud, isolated affordance (or to show the
+     * palette itself, as the showcase does).
+     */
     colored?: boolean;
     /** Run the bouncing pulse on the active button (default true). */
     animate?: boolean;
@@ -55,6 +66,20 @@ export interface KeycapOptions {
      * a settings screen, a showcase, a screenshot.
      */
     glyphSet?: GlyphSet;
+    /**
+     * Size multiplier for the whole keycap — pip diameter, letter, glyph and (on the pill shape) its
+     * height, padding and type. Default `1`.
+     *
+     * **This is the ONLY sanctioned way to make a keycap smaller.** The kit's rule against restyling
+     * stands: don't override the `.rydr-ui-*` sizes and never wrap a cap in `transform: scale()`, which
+     * leaves a full-size layout box, blurs the text and breaks any positioning done against it. This
+     * option resizes the real geometry instead, so layout stays honest.
+     *
+     * For **secondary** emphasis only — a hint the rider *may* use (the option menu's `Shortcut` caps ride
+     * at `0.65`), never a primary prompt. A prompt telling the rider what to press now stays at `1`: full
+     * size is what keeps it legible from a few feet away on a trainer.
+     */
+    scale?: number;
 }
 /** A bare keycap with its state setters. */
 export interface Keycap {
@@ -71,6 +96,20 @@ export interface Keycap {
     setCooldown(frac: number | null, label?: string | number): void;
     /** Per-button hue on/off. */
     setColored(on: boolean): void;
+    /**
+     * Override the pip's colour outright. `null` restores whatever {@link setColored} would give.
+     *
+     * The pip's face and its 3D shadow are both derived from one `--c` custom property, set inline — so a
+     * caller that needs a colour outside the per-role palette has to go through here rather than a
+     * stylesheet rule, which an inline value would beat. Used by the guided-lesson states in
+     * `controller/input-chip.ts` (whitish "do this", accent "doing it", green "done").
+     *
+     * **Optional deliberately.** `createKeycap` always provides it, but consumers WRAP this interface —
+     * the shell's `shellKeycaps` re-letters keycaps by rebuilding them behind a handle of this shape —
+     * and making it required would break every such wrapper at compile time for a method they have no
+     * need of. Callers must therefore treat it as absent-safe.
+     */
+    setAccent?(color: string | null): void;
     /** Disabled = the action is unavailable: flat grey, inert (no pulse/press), letter dimmed. */
     setDisabled(on: boolean): void;
     /** Hide/show the keycap. */
@@ -87,24 +126,30 @@ export interface Keycap {
  */
 export declare function createKeycap(button: DiamondButton, opts?: KeycapOptions): Keycap;
 /**
- * Build a keycap for a button whose printed name is a **word, not a letter** — the system/options
- * button (`OPTIONS` → "Menu" / "Options" / "+"), the shoulder triggers (`LT`/`RT` → "LT" / "L2" / "ZL")
- * and the stick clicks (`LSTICK_PRESS`/`RSTICK_PRESS` → "LS" / "L3" / "L").
+ * Build a keycap for the buttons that carry neither a face letter nor a direction — the system/options
+ * button (`OPTIONS`), the shoulder triggers (`LT`/`RT`) and the stick clicks
+ * (`LSTICK_PRESS`/`RSTICK_PRESS`) — drawn the way the rider's pad actually draws them:
+ *
+ *   • **`OPTIONS` → a round pip with the pad's ICON** (`☰` on Xbox/DualSense, `+` on a Switch Pro).
+ *     It is a small round key on every pad, so it gets the same circular pip as the d-pad's chevron and
+ *     sits in the same visual family as the face buttons.
+ *   • **everything else → a text PILL** carrying {@link buttonLabel} ("LT" / "L2" / "ZL", "LS" / "L3"),
+ *     because those buttons really are printed with a *word*, and no word fits a pip sized for one
+ *     glyph. The trigger hardware isn't round either.
  *
- * A **pill** rather than a circular pip, because "Options" does not fit in a pip sized for one glyph.
- * Everything else is the pip's own language reused verbatim (raised lip, pulse, pressed sink, inert
- * grey), so the two shapes read as one family, and the text still comes from {@link buttonLabel} — the
- * rule that no letter is ever hardcoded holds here too.
+ * Either way the state machine is the pip's, reused verbatim (raised lip, pulse, pressed sink, inert
+ * grey), and nothing is hardcoded per brand: the icon comes from {@link SYSTEM_ICON} and the text from
+ * {@link buttonLabel}.
  *
- * Steel-grey by default (a system button is never the confirm/back hue), and — unlike the pip
- * factories — the attract pulse is **off** unless asked for: these caps label a shortcut the rider can
- * take, not an action being demanded of them. `setCooldown` is accepted for interface parity but draws
- * nothing: these buttons open menus, they don't gate timed abilities.
+ * Steel-grey (these are never the confirm/back hues), and — unlike the pip factories — the attract
+ * pulse is **off** unless asked for: these caps label a shortcut the rider *can* take, not an action
+ * being demanded of them. `setCooldown` is accepted for interface parity but draws nothing on the pill:
+ * these buttons open menus, they don't gate timed abilities.
  *
- * Pass a face-diamond or d-pad button here and you get its letter/arrow in a pill — legal, but prefer
- * {@link createKeycap} / {@link createDpadKeycap}, which draw the real button shape.
+ * Pass a face-diamond or d-pad button here and you get its letter in a pill — legal, but prefer
+ * {@link createKeycap} / {@link createDpadKeycap}, which draw those buttons' real shapes.
  */
-export declare function createLabelKeycap(button: ButtonName, opts?: KeycapOptions): Keycap;
+export declare function createButtonKeycap(button: ButtonName, opts?: KeycapOptions): Keycap;
 /**
  * Build a bare directional (UP/DOWN/LEFT/RIGHT) keycap. Identical state machine to {@link createKeycap}
  * — solo/full, pulse, pressed, cooldown ring — only the active button shows a WHITE chevron (rotated

package/dist/ui/keycap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keycap.d.ts","sourceRoot":"","sources":["../../src/ui/keycap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtF,+FAA+F;AAC/F,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,GAAG,eAAe,CAAC;AAC7F,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AACzD,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAC5C,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/E;AAoBD,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,MAAM;IACrB,mDAAmD;IACnD,EAAE,EAAE,WAAW,CAAC;IAChB,uCAAuC;IACvC,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChE,6BAA6B;IAC7B,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,8FAA8F;IAC9F,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,4BAA4B;IAC5B,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,OAAO,IAAI,IAAI,CAAC;CACjB;AA0KD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAEpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAoBtF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAEjF"}
+{"version":3,"file":"keycap.d.ts","sourceRoot":"","sources":["../../src/ui/keycap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtF,+FAA+F;AAC/F,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,GAAG,eAAe,CAAC;AAC7F,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AACzD,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAC5C,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/E;AAoBD,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,MAAM;IACrB,mDAAmD;IACnD,EAAE,EAAE,WAAW,CAAC;IAChB,uCAAuC;IACvC,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChE,6BAA6B;IAC7B,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACvC,8FAA8F;IAC9F,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,4BAA4B;IAC5B,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,OAAO,IAAI,IAAI,CAAC;CACjB;AA2ND;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAEpF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAgCvF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAEjF"}