@rydr/game-sdk 6.1.0 → 7.0.1

package/dist/ui/pause-menu.d.ts

@@ -0,0 +1,144 @@
+/**
+ * PAUSE MENU — the in-game menu every RYDR game shares, opened by the game's own `OPTIONS` button.
+ *
+ * This is the GAME's menu, deliberately distinct from the PLATFORM's overlay (which the shell opens on
+ * `MENU` / `M` / phone MENU and which never reaches a game — see `ButtonName`). The platform overlay
+ * carries the rider's concerns: activity, hardware, volume, exit. This one carries the *game's*:
+ * resume, restart, back to your own menu. It deliberately quotes the platform overlay's visual language
+ * — dim + blurred backdrop, frosted rows, the staggered "warp" entrance — so pause reads as a RYDR
+ * surface one level shallower than the platform's, rather than as a second, unrelated menu.
+ *
+ *   const pause = mountPauseMenu(document.body, {
+ *     session,
+ *     title: "Split Racing",
+ *     canOpen: () => phase === "playing",     // the game decides WHEN it may open
+ *     onOpen: () => { paused = true },        // the game freezes its own loop
+ *     onClose: () => { paused = false },
+ *     items: [
+ *       { label: "Restart", shortcut: "DIAMOND_UP", onSelect: () => restart() },
+ *       { label: "Back to menu", onSelect: () => go("/") },
+ *     ],
+ *   });
+ *
+ * `Resume` is prepended for free, so the shortest useful menu is no items at all.
+ *
+ * **Everything the rider reads is in the GAME's font.** The title and every row inherit the host's
+ * font-family (override with the `font` option or the `--rydr-pause-font` custom property), because
+ * this menu belongs to the game, not to the shell — the one exception being the keycaps, which keep
+ * their standard RYDR type because they are pictures of the rider's physical controller.
+ *
+ * **What it does NOT do: stop your game.** No library can — your loop, timers and physics are yours.
+ * The menu tells you when it opens and closes; freeze there. What it *does* guarantee is that a game
+ * which keeps running cannot be *driven* while the rider is in the menu: it takes the controller over
+ * for the duration (`session.grabInput`), so your `onButton` handlers go quiet, `isDown`/`stick` read
+ * resting, and anything held is released first. It also declares `"menu"` to the shell while it's up,
+ * so trainer resistance eases like on any other non-racing screen, and restores `"playing"` on resume.
+ *
+ * A row may advertise a `shortcut` — the button the rider can press *in-game* to do the same thing
+ * (`Restart · Shortcut [Y]`). Binding that shortcut during play stays the game's own job; the menu
+ * only teaches it, and honours it while the menu itself is open (where it owns input anyway).
+ */
+import type { ButtonEdge, ButtonName, GlyphSet } from "../protocol/index.js";
+import { type NavCue } from "../nav/spatial-nav.js";
+/**
+ * The slice of a `PlatformSession` the menu uses. A real session satisfies it structurally, and every
+ * capability past `onButton` is optional so a stand-in (a showcase double, a test) works too — without
+ * `grabInput` the menu simply can't quiet the game's own input, and without `setActivity` the trainer
+ * isn't eased.
+ */
+export interface PauseMenuSession {
+    onButton(cb: (e: {
+        name: ButtonName;
+        edge: ButtonEdge;
+    }) => void): () => void;
+    grabInput?(handler: (e: {
+        name: ButtonName;
+        edge: ButtonEdge;
+    }) => void): () => void;
+    setActivity?(state: "playing" | "menu"): void;
+}
+/** One row of the menu. */
+export interface PauseMenuItem {
+    /** The row's text — keep it short (it's read from a few feet away): "Restart", "Back to menu". */
+    label: string;
+    /** Run when the rider picks the row (with `A`, a click, or the row's `shortcut`). */
+    onSelect: () => void;
+    /**
+     * The button that does this same thing **directly in-game**, shown on the row as `Shortcut [Y]` so
+     * the rider learns it. The game keeps owning that binding during play; the menu honours it too while
+     * it's open.
+     */
+    shortcut?: ButtonName;
+    /** Optional second line under the label — a consequence worth spelling out ("You'll lose this lap"). */
+    hint?: string;
+    /** Unavailable right now: shown inert, skipped by the focus ring. */
+    disabled?: boolean;
+    /** Destructive tint (leaving, wiping a run) — the same red the platform overlay gives Exit. */
+    danger?: boolean;
+    /** Keep the menu open after `onSelect` (a toggle, a row that swaps the list via `setItems`). Default
+     *  is to close first, so the action runs on a resumed game with input already handed back. */
+    keepOpen?: boolean;
+}
+export interface PauseMenuOptions {
+    /** The platform session — for input, the trainer-easing hint, and the rider's controller lettering. */
+    session?: PauseMenuSession;
+    /** The game's name, printed big at the top in the game's own font. */
+    title: string;
+    /** The rows after `Resume`. Replaceable at any time with `setItems`. */
+    items?: PauseMenuItem[];
+    /** Which button opens (and closes) the menu. Default `"OPTIONS"` — the game's own menu button. */
+    openButton?: ButtonName;
+    /**
+     * Asked before opening: return `false` to refuse. This is how a game keeps the menu to its PLAYING
+     * phase (`() => phase === "playing"`) instead of letting it stack on top of its own menus. Default:
+     * always allowed.
+     */
+    canOpen?: () => boolean;
+    /** Label of the free first row. Default `"Resume"`. */
+    resumeLabel?: string;
+    /** Declare `"menu"` to the shell while open and `"playing"` on close (eases trainer resistance).
+     *  Default `true`. Turn it off only if the game manages activity state itself around the menu. */
+    activity?: boolean;
+    /** Take the controller over while open via `session.grabInput` (default `true`). Off = the game keeps
+     *  receiving input behind the menu, which it must then ignore itself. */
+    captureInput?: boolean;
+    /** Nav sounds — pass a `Soundboard.cue`; omit for silence. */
+    cue?: (id: NavCue) => void;
+    /** Force the menu's font (any CSS `font-family` value). Default: inherited from the host — i.e. the
+     *  game's own font, which is what you want. */
+    font?: string;
+    /** Controller lettering for the keycaps. Default: the session's, else Xbox. */
+    glyphSet?: GlyphSet;
+    /** The menu opened — freeze your loop here. */
+    onOpen?: () => void;
+    /** The menu closed (resume, back, the backdrop, or a row that ran) — unfreeze here. */
+    onClose?: () => void;
+}
+export interface PauseMenu {
+    /** The overlay root (mounted in the host; hidden while closed). */
+    root: HTMLElement;
+    /** Open it (no-op if already open or `canOpen` refuses). Returns whether it opened. */
+    open(): boolean;
+    /** Close it, playing the exit animation. */
+    close(): void;
+    /** Open if closed, close if open. Returns whether it ended up open. */
+    toggle(): boolean;
+    isOpen(): boolean;
+    /** Replace the rows after `Resume` (rebuilt live if the menu is open). */
+    setItems(items: PauseMenuItem[]): void;
+    /** Change the big title. */
+    setTitle(title: string): void;
+    /**
+     * Feed one canonical button in by hand — for a host that arbitrates input itself instead of letting
+     * the menu subscribe (`session` omitted, or a shell-style router). Returns `true` if the menu
+     * consumed it. Pass `down` edges.
+     */
+    handleButton(name: ButtonName): boolean;
+    dispose(): void;
+}
+/**
+ * Mount the pause menu (hidden until opened). Appended to `host` — normally `document.body`, so the
+ * overlay covers the game whatever the DOM under it looks like.
+ */
+export declare function mountPauseMenu(host: HTMLElement, opts: PauseMenuOptions): PauseMenu;
+//# sourceMappingURL=pause-menu.d.ts.map

package/dist/ui/pause-menu.d.ts.map

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

package/dist/ui/pause-menu.js

@@ -0,0 +1,500 @@
+/**
+ * PAUSE MENU — the in-game menu every RYDR game shares, opened by the game's own `OPTIONS` button.
+ *
+ * This is the GAME's menu, deliberately distinct from the PLATFORM's overlay (which the shell opens on
+ * `MENU` / `M` / phone MENU and which never reaches a game — see `ButtonName`). The platform overlay
+ * carries the rider's concerns: activity, hardware, volume, exit. This one carries the *game's*:
+ * resume, restart, back to your own menu. It deliberately quotes the platform overlay's visual language
+ * — dim + blurred backdrop, frosted rows, the staggered "warp" entrance — so pause reads as a RYDR
+ * surface one level shallower than the platform's, rather than as a second, unrelated menu.
+ *
+ *   const pause = mountPauseMenu(document.body, {
+ *     session,
+ *     title: "Split Racing",
+ *     canOpen: () => phase === "playing",     // the game decides WHEN it may open
+ *     onOpen: () => { paused = true },        // the game freezes its own loop
+ *     onClose: () => { paused = false },
+ *     items: [
+ *       { label: "Restart", shortcut: "DIAMOND_UP", onSelect: () => restart() },
+ *       { label: "Back to menu", onSelect: () => go("/") },
+ *     ],
+ *   });
+ *
+ * `Resume` is prepended for free, so the shortest useful menu is no items at all.
+ *
+ * **Everything the rider reads is in the GAME's font.** The title and every row inherit the host's
+ * font-family (override with the `font` option or the `--rydr-pause-font` custom property), because
+ * this menu belongs to the game, not to the shell — the one exception being the keycaps, which keep
+ * their standard RYDR type because they are pictures of the rider's physical controller.
+ *
+ * **What it does NOT do: stop your game.** No library can — your loop, timers and physics are yours.
+ * The menu tells you when it opens and closes; freeze there. What it *does* guarantee is that a game
+ * which keeps running cannot be *driven* while the rider is in the menu: it takes the controller over
+ * for the duration (`session.grabInput`), so your `onButton` handlers go quiet, `isDown`/`stick` read
+ * resting, and anything held is released first. It also declares `"menu"` to the shell while it's up,
+ * so trainer resistance eases like on any other non-racing screen, and restores `"playing"` on resume.
+ *
+ * A row may advertise a `shortcut` — the button the rider can press *in-game* to do the same thing
+ * (`Restart · Shortcut [Y]`). Binding that shortcut during play stays the game's own job; the menu
+ * only teaches it, and honours it while the menu itself is open (where it owns input anyway).
+ */
+import { DEFAULT_GLYPH_SET } from "../protocol/glyphs.js";
+import { createSpatialNav } from "../nav/spatial-nav.js";
+import { createKeycap, createLabelKeycap } from "./keycap.js";
+import { injectCss } from "./styles.js";
+/**
+ * The rider's controller lettering: an explicit `glyphSet` wins, else the one a real `PlatformSession`
+ * carries, else Xbox. Probed structurally rather than declared on {@link PauseMenuSession} — same
+ * reasoning as `createKeycap`'s own probe: that type is the *minimal* slice the menu needs, and
+ * demanding a hardware snapshot would break every hand-rolled stub for a value that's optional anyway.
+ */
+function resolveGlyphSet(opts) {
+    if (opts.glyphSet)
+        return opts.glyphSet;
+    const probe = opts.session;
+    return probe?.hardware?.current?.glyphSet ?? DEFAULT_GLYPH_SET;
+}
+/** Entrance/exit duration + per-row stagger, mirrored in the CSS below. */
+const ANIM_MS = 500;
+const STAGGER_MS = 26;
+/** Rows warp outward this fraction of their distance from the list's centre. */
+const WARP_PUSH = 0.9;
+let pauseCssInjected = false;
+function injectPauseCss() {
+    if (pauseCssInjected || document.getElementById("rydr-pause-css")) {
+        pauseCssInjected = true;
+        return;
+    }
+    const style = document.createElement("style");
+    style.id = "rydr-pause-css";
+    style.textContent = CSS;
+    document.head.appendChild(style);
+    pauseCssInjected = true;
+}
+/**
+ * Mount the pause menu (hidden until opened). Appended to `host` — normally `document.body`, so the
+ * overlay covers the game whatever the DOM under it looks like.
+ */
+export function mountPauseMenu(host, opts) {
+    injectCss(); // the keycaps' own .rydr-ui-* styles
+    injectPauseCss();
+    const { session, openButton = "OPTIONS", resumeLabel = "Resume", activity = true, captureInput = true, cue, } = opts;
+    const glyphSet = resolveGlyphSet(opts);
+    let items = opts.items ? [...opts.items] : [];
+    let open = false;
+    let closing = false;
+    let closeTimer = null;
+    let releaseInput = null;
+    let nav = null;
+    /** The rows currently in the DOM, index-aligned with {@link rowItems}. */
+    let rows = [];
+    /** The item each row stands for — `Resume` first, then `items`. */
+    let rowItems = [];
+    /** Keycaps built for the current rows (disposed on every rebuild). */
+    let rowCaps = [];
+    // ── DOM ────────────────────────────────────────────────────────────────────────────────────────
+    const root = document.createElement("div");
+    root.className = "rydr-pause";
+    root.tabIndex = -1;
+    if (opts.font)
+        root.style.setProperty("--rydr-pause-font", opts.font);
+    const inner = document.createElement("div");
+    inner.className = "rydr-pause-inner";
+    const titleEl = document.createElement("div");
+    titleEl.className = "rydr-pause-title";
+    titleEl.textContent = opts.title;
+    const listEl = document.createElement("div");
+    listEl.className = "rydr-pause-list";
+    inner.append(titleEl, listEl);
+    root.appendChild(inner);
+    host.appendChild(root);
+    // Backdrop click resumes — the mouse equivalent of pressing the open button again.
+    root.addEventListener("click", (e) => {
+        if (e.target === root)
+            close();
+    });
+    // ── Keycap press feedback ──────────────────────────────────────────────────────────────────────
+    // The keycaps can't listen to `session.onButton`: while the menu holds an input grab, the session
+    // delivers nothing to ordinary listeners (that's the point of the grab). So they subscribe to this
+    // local source, which the menu feeds from whichever path is actually live.
+    const capListeners = new Set();
+    const capSource = {
+        onButton: (cb) => {
+            capListeners.add(cb);
+            return () => capListeners.delete(cb);
+        },
+    };
+    /**
+     * The confirm keycap, which RIDES the focused row: every row carries a fixed-width slot at its end
+     * and the cap is moved into the focused one. Deliberately not the platform overlay's fixed-position
+     * roving cap — these rows are full-width, so a cap anchored to a row's right edge would land on top
+     * of that row's shortcut keycap. Riding a real slot also needs no measuring, so it can't drift
+     * mid-animation or on scroll.
+     */
+    const confirmCap = createKeycap("DIAMOND_DOWN", {
+        variant: "solo",
+        colored: false,
+        animate: true,
+        press: capSource,
+        glyphSet,
+    });
+    confirmCap.el.classList.add("rydr-pause-cap");
+    // ── Rows ───────────────────────────────────────────────────────────────────────────────────────
+    function buildRows() {
+        for (const cap of rowCaps)
+            cap.dispose();
+        rowCaps = [];
+        listEl.textContent = "";
+        rowItems = [{ label: resumeLabel, onSelect: () => { }, shortcut: openButton }, ...items];
+        rows = rowItems.map((item, i) => {
+            const row = document.createElement("button");
+            row.type = "button";
+            row.className = "rydr-pause-row" + (item.danger ? " danger" : "");
+            if (item.disabled)
+                row.disabled = true;
+            row.style.setProperty("--i", String(i));
+            row.style.setProperty("--ri", String(rowItems.length - 1 - i));
+            const text = document.createElement("span");
+            text.className = "rydr-pause-text";
+            const label = document.createElement("span");
+            label.className = "rydr-pause-label";
+            label.textContent = item.label;
+            text.appendChild(label);
+            if (item.hint) {
+                const hint = document.createElement("span");
+                hint.className = "rydr-pause-hint";
+                hint.textContent = item.hint;
+                text.appendChild(hint);
+            }
+            row.appendChild(text);
+            const right = document.createElement("span");
+            right.className = "rydr-pause-right";
+            if (item.shortcut) {
+                const shortcut = document.createElement("span");
+                shortcut.className = "rydr-pause-shortcut";
+                const tag = document.createElement("span");
+                tag.className = "rydr-pause-shortcut-tag";
+                tag.textContent = "Shortcut";
+                const cap = createLabelKeycap(item.shortcut, { press: capSource, glyphSet });
+                rowCaps.push(cap);
+                if (item.disabled)
+                    cap.setDisabled(true);
+                shortcut.append(tag, cap.el);
+                right.appendChild(shortcut);
+            }
+            // The slot the confirm keycap moves into when this row takes focus. Always present (and always
+            // the same width) so focus moving between rows never reflows the list.
+            const slot = document.createElement("span");
+            slot.className = "rydr-pause-confirm";
+            right.appendChild(slot);
+            row.appendChild(right);
+            row.addEventListener("click", () => select(i));
+            listEl.appendChild(row);
+            return row;
+        });
+    }
+    /**
+     * Set each row's warp offset from its position in the list, so the entrance flies rows out from (and
+     * back to) their own side of the centre. Measured with the transform-invariant layout box, never
+     * `getBoundingClientRect()`, which returns the live *transformed* rect mid-animation and would make
+     * every replay drift.
+     */
+    function computeOffsets() {
+        const cy = listEl.offsetHeight / 2;
+        for (const row of rows) {
+            const rc = row.offsetTop + row.offsetHeight / 2;
+            row.style.setProperty("--dy", ((rc - cy) * WARP_PUSH).toFixed(0) + "px");
+        }
+    }
+    /** Move the confirm keycap into the focused row's slot (out of the DOM when nothing is focused). */
+    function placeCap() {
+        const row = open ? nav?.current() ?? null : null;
+        const slot = row?.querySelector(".rydr-pause-confirm");
+        if (!slot) {
+            confirmCap.el.remove();
+            return;
+        }
+        if (confirmCap.el.parentNode !== slot)
+            slot.appendChild(confirmCap.el);
+    }
+    // ── Selection ──────────────────────────────────────────────────────────────────────────────────
+    /**
+     * Run row `i`. Closes FIRST by default — so the game is already unfrozen and holding its own input
+     * again by the time the action runs (a restart shouldn't begin behind a menu that's still up).
+     */
+    function select(i) {
+        const item = rowItems[i];
+        if (!item || item.disabled)
+            return;
+        confirmCap.setPressed(true);
+        setTimeout(() => confirmCap.setPressed(false), 160);
+        cue?.("nav.confirm");
+        if (item.keepOpen) {
+            item.onSelect();
+            return;
+        }
+        close();
+        item.onSelect();
+    }
+    // ── Input ──────────────────────────────────────────────────────────────────────────────────────
+    /** Route one `down` edge. Returns whether the menu consumed it. */
+    function handleButton(name) {
+        if (!open) {
+            if (name !== openButton)
+                return false;
+            return openMenu();
+        }
+        if (name === openButton) {
+            close();
+            return true;
+        }
+        // A row's advertised shortcut fires that row directly — the menu owns input here, so honouring it
+        // costs nothing and matches what the row promises.
+        const shortcutIndex = rowItems.findIndex((it) => it.shortcut === name && !it.disabled);
+        if (shortcutIndex > 0) {
+            select(shortcutIndex);
+            return true;
+        }
+        nav?.handle(name); // directions, A (→ onActivate), B (→ onBack → close)
+        return true;
+    }
+    /** Feed an edge to the in-menu keycaps, then route `down` edges. Shared by both input paths. */
+    function onEdge(e) {
+        for (const cb of capListeners)
+            cb(e);
+        if (e.edge === "down")
+            handleButton(e.name);
+    }
+    // The always-on subscription: it's what hears the open button while the menu is closed. While a grab
+    // is active this receives nothing (the grab is the only recipient) — hence the `releaseInput` guard,
+    // which keeps a session WITHOUT `grabInput` (a stub) working off this one path.
+    const offSession = session?.onButton((e) => {
+        if (releaseInput)
+            return; // the grab handler already has it
+        onEdge(e);
+    });
+    // ── Open / close ───────────────────────────────────────────────────────────────────────────────
+    function openMenu() {
+        if (open)
+            return true;
+        if (opts.canOpen && !opts.canOpen())
+            return false;
+        if (closeTimer !== null) {
+            clearTimeout(closeTimer);
+            closeTimer = null;
+        }
+        open = true;
+        closing = false;
+        root.classList.remove("closing");
+        root.classList.add("open");
+        buildRows();
+        computeOffsets();
+        if (captureInput && session?.grabInput)
+            releaseInput = session.grabInput(onEdge);
+        if (activity)
+            session?.setActivity?.("menu");
+        // Pull keyboard focus onto the overlay so a game that also handles DOM focus can't keep it.
+        root.focus?.();
+        nav = createSpatialNav({
+            root: listEl,
+            selector: ".rydr-pause-row:not([disabled])",
+            ring: false, // the ring is styled below
+            wrap: true, // a single-axis list: DOWN past the last returns to the first
+            pointer: true, // hover and controller share one focus state
+            cue,
+            onActivate: (el) => select(rows.indexOf(el)),
+            onBack: close,
+            onFocusChange: () => placeCap(),
+        });
+        nav.focusFirst(); // land on Resume — the safe default
+        placeCap();
+        opts.onOpen?.();
+        return true;
+    }
+    function close() {
+        if (!open && !closing)
+            return;
+        if (closeTimer !== null)
+            return; // already closing
+        open = false;
+        closing = true;
+        // Keep the overlay mounted and lit for the exit animation; `.closing` only fades the backdrop.
+        root.classList.remove("open");
+        root.classList.add("closing");
+        releaseInput?.();
+        releaseInput = null;
+        if (activity)
+            session?.setActivity?.("playing");
+        nav?.dispose();
+        nav = null;
+        // The cap leaves with the focus ring, but the rows stay mounted for the warp-out.
+        confirmCap.el.remove();
+        cue?.("nav.back");
+        opts.onClose?.();
+        closeTimer = setTimeout(() => {
+            closeTimer = null;
+            closing = false;
+            root.classList.remove("closing");
+            listEl.textContent = "";
+            for (const cap of rowCaps)
+                cap.dispose();
+            rowCaps = [];
+            rows = [];
+        }, ANIM_MS + rows.length * STAGGER_MS + 140);
+    }
+    return {
+        root,
+        open: openMenu,
+        close,
+        toggle: () => {
+            if (open) {
+                close();
+                return false;
+            }
+            return openMenu();
+        },
+        isOpen: () => open,
+        setItems: (next) => {
+            items = [...next];
+            if (open) {
+                buildRows();
+                computeOffsets();
+                nav?.revalidate();
+                nav?.focusFirst();
+                placeCap();
+            }
+        },
+        setTitle: (title) => {
+            titleEl.textContent = title;
+        },
+        handleButton,
+        dispose: () => {
+            offSession?.();
+            releaseInput?.();
+            releaseInput = null;
+            // Torn down mid-open (a game unmounting its screen): hand the trainer back to gameplay, or the
+            // rider would keep riding the menu's eased resistance with no menu on screen.
+            if (open && activity)
+                session?.setActivity?.("playing");
+            open = false;
+            if (closeTimer !== null)
+                clearTimeout(closeTimer);
+            nav?.dispose();
+            nav = null;
+            for (const cap of rowCaps)
+                cap.dispose();
+            rowCaps = [];
+            confirmCap.dispose();
+            capListeners.clear();
+            root.remove();
+        },
+    };
+}
+/**
+ * The overlay's own `.rydr-pause-*` CSS — self-contained, injected once, no global styles or CSS
+ * variables required. Deliberately quotes the platform menu's numbers (the same dim, blur, radii and
+ * warp curve) so the two surfaces read as one family.
+ *
+ * `font-family: var(--rydr-pause-font, inherit)` on every text rule is load-bearing: the menu must
+ * render in the GAME's font, which it gets by inheriting from the host. The keycaps are the exception —
+ * they carry their own type from `styles.ts`, because they depict the rider's physical controller.
+ */
+const CSS = `
+.rydr-pause { position: fixed; inset: 0; z-index: 1400; display: flex; justify-content: center;
+          overflow-x: hidden; overflow-y: auto; padding: clamp(40px, 7vh, 88px) 24px 96px;
+          font-family: var(--rydr-pause-font, inherit);
+          background: rgba(2, 6, 23, calc(0.82 * var(--bd, 0)));
+          -webkit-backdrop-filter: blur(calc(14px * var(--bd, 0)));
+                  backdrop-filter: blur(calc(14px * var(--bd, 0)));
+          opacity: 0; pointer-events: none; visibility: hidden;
+          transition: background 0.45s ease, backdrop-filter 0.45s ease, opacity 0.35s ease; }
+.rydr-pause:focus { outline: none; }
+.rydr-pause.open { opacity: 1; pointer-events: auto; visibility: visible; --bd: 1; }
+/* closing: stay visible so the rows can warp back out — only the backdrop fades */
+.rydr-pause.closing { opacity: 1; visibility: visible; pointer-events: none; --bd: 0;
+          transition: background 0.45s ease, backdrop-filter 0.45s ease; }
+
+.rydr-pause-inner { width: 100%; max-width: 620px; margin: auto 0; display: flex; flex-direction: column; gap: 26px; }
+/* the game's name, in the game's font — the biggest thing on the screen */
+.rydr-pause-title { font-family: var(--rydr-pause-font, inherit); text-align: center;
+          font-size: clamp(2.4rem, 8vw, 3.4rem); font-weight: 800; letter-spacing: -0.03em; line-height: 1;
+          color: #f2f5fb; text-shadow: 0 6px 30px rgba(0, 0, 0, 0.6); }
+.rydr-pause-list { position: relative; display: flex; flex-direction: column; gap: 12px; }
+
+/* a row: frosted glass, label left, shortcut right */
+.rydr-pause-row { appearance: none; cursor: pointer; width: 100%; box-sizing: border-box;
+          display: flex; align-items: center; justify-content: space-between; gap: 18px;
+          min-height: 74px; padding: 0.9rem 1.1rem 0.9rem 1.4rem; border-radius: 18px;
+          font-family: var(--rydr-pause-font, inherit); color: #f2f5fb; text-align: left;
+          background: rgba(255, 255, 255, 0.06); border: 1px solid rgba(255, 255, 255, 0.14);
+          -webkit-backdrop-filter: blur(20px) saturate(120%);
+                  backdrop-filter: blur(20px) saturate(120%);
+          box-shadow: 0 8px 24px rgba(0, 0, 0, 0.28), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+          transition: transform 0.14s ease, border-color 0.14s ease, box-shadow 0.14s ease, background 0.14s ease;
+          will-change: transform, opacity, filter; }
+.rydr-pause-row:hover:not([disabled]) { background: rgba(255, 255, 255, 0.1); border-color: rgba(255, 255, 255, 0.3); }
+.rydr-pause-row:focus-visible { outline: none; }
+.rydr-pause-row[disabled] { cursor: default; opacity: 0.45; }
+.rydr-pause-row.danger .rydr-pause-label { color: #ff8b8b; }
+.rydr-pause-text { display: flex; flex-direction: column; gap: 0.2rem; min-width: 0; }
+.rydr-pause-label { font-family: var(--rydr-pause-font, inherit); font-weight: 700; font-size: 1.6rem;
+          letter-spacing: 0.01em; line-height: 1.1; overflow-wrap: anywhere; }
+.rydr-pause-hint { font-family: var(--rydr-pause-font, inherit); font-size: 0.95rem; font-weight: 500;
+          color: rgba(238, 244, 255, 0.62); line-height: 1.25; }
+/* right side: the "Shortcut" tag + its keycap, then the slot the confirm cap rides into */
+.rydr-pause-right { display: flex; align-items: center; gap: 18px; flex: 0 0 auto; }
+.rydr-pause-shortcut { display: flex; align-items: center; gap: 9px; flex: 0 0 auto; }
+.rydr-pause-shortcut-tag { font-family: var(--rydr-pause-font, inherit); font-size: 0.7rem; font-weight: 700;
+          letter-spacing: 0.14em; text-transform: uppercase; color: rgba(238, 244, 255, 0.5); }
+/* the slot is always there, at a FIXED width (one solo keycap), so focus moving row to row can never
+   reflow the list — only the cap inside it appears and disappears */
+.rydr-pause-confirm { flex: 0 0 38px; height: 38px; display: flex; align-items: center; justify-content: center; }
+
+/* roving controller focus: white ring + halo, as on the platform overlay */
+.rydr-pause-row[nav-focused] { outline: none; transform: scale(1.02);
+          border-color: rgba(255, 255, 255, 0.9);
+          box-shadow: 0 0 0 3px #ffffff, 0 0 22px 0 rgba(255, 255, 255, 0.16), 0 22px 50px rgba(0, 0, 0, 0.55);
+          z-index: 2; }
+
+/* the confirm keycap, sitting in the focused row's slot */
+.rydr-pause-cap { pointer-events: none;
+          filter: drop-shadow(0 2px 3px rgba(0, 0, 0, 0.7)) drop-shadow(0 8px 16px rgba(0, 0, 0, 0.5)); }
+
+/* ── entrance / exit: rows warp in from their own side of the list, staggered ──
+   fill: backwards (not both) so the resting frame hands control back to plain CSS and the
+   [nav-focused] scale can take over without a flash. */
+.rydr-pause.open .rydr-pause-row { animation: rydr-pause-warp-in ${ANIM_MS}ms cubic-bezier(0.1, 0.8, 0.4, 1) backwards;
+          animation-delay: calc(var(--ri, 0) * ${STAGGER_MS}ms); }
+.rydr-pause.open .rydr-pause-title { animation: rydr-pause-warp-in-top ${ANIM_MS}ms cubic-bezier(0.1, 0.8, 0.4, 1) backwards; }
+.rydr-pause.closing .rydr-pause-row { animation: rydr-pause-warp-out ${ANIM_MS}ms cubic-bezier(0.6, 0, 0.9, 0.2) both;
+          animation-delay: calc(var(--i, 0) * ${STAGGER_MS}ms); }
+.rydr-pause.closing .rydr-pause-title { animation: rydr-pause-warp-out-top ${ANIM_MS}ms cubic-bezier(0.6, 0, 0.9, 0.2) both; }
+@keyframes rydr-pause-warp-in {
+  0%   { opacity: 0; transform: translateY(calc(var(--dy, 0px) * 1.5)) scale(2.4); filter: blur(6px); }
+  55%  { opacity: 1; filter: blur(0); }
+  100% { opacity: 1; transform: translateY(0) scale(1); filter: blur(0); }
+}
+@keyframes rydr-pause-warp-out {
+  0%   { opacity: 1; transform: translateY(0) scale(1); filter: blur(0); }
+  45%  { opacity: 1; filter: blur(0); }
+  100% { opacity: 0; transform: translateY(calc(var(--dy, 0px) * 1.5)) scale(2.4); filter: blur(6px); }
+}
+@keyframes rydr-pause-warp-in-top {
+  0%   { opacity: 0; transform: translateY(-70px) scale(1.9); filter: blur(6px); }
+  55%  { opacity: 1; filter: blur(0); }
+  100% { opacity: 1; transform: translateY(0) scale(1); filter: blur(0); }
+}
+@keyframes rydr-pause-warp-out-top {
+  0%   { opacity: 1; transform: translateY(0) scale(1); filter: blur(0); }
+  45%  { opacity: 1; filter: blur(0); }
+  100% { opacity: 0; transform: translateY(-70px) scale(1.9); filter: blur(6px); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .rydr-pause.open .rydr-pause-row,
+  .rydr-pause.open .rydr-pause-title { animation: rydr-pause-fade 0.3s ease both !important; }
+  .rydr-pause.closing .rydr-pause-row,
+  .rydr-pause.closing .rydr-pause-title { animation: rydr-pause-fade 0.2s ease reverse both !important; }
+  @keyframes rydr-pause-fade { from { opacity: 0; } to { opacity: 1; } }
+}
+`;
+//# sourceMappingURL=pause-menu.js.map