@rydr/game-sdk 8.9.0 → 8.11.0

package/dist/overlay/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Overlay boxes — the DOM half of overlay mode.
+ *
+ * `session.overlay` is transport: it moves box declarations out and host answers in, and draws
+ * nothing. This module is what actually puts boxes on screen, measures them, drags them and keeps
+ * the host told where they are. Same division as `mountOptionMenu` in `@rydr/game-sdk/ui`, and it
+ * is deliberate — a game with its own renderer can use the transport directly and ignore this.
+ *
+ * It lives behind the `./overlay` subpath so the main entry stays free of DOM: a headless consumer
+ * (a test, a server-side tool) can import the protocol types without pulling a document in.
+ *
+ * WHAT THE GAME STILL OWNS: the content. Each box hands back a `body` element and this module never
+ * writes to it. That is the whole point of overlay mode — only the game knows what a workout target
+ * or a compliance band should look like.
+ *
+ * COORDINATES. A box's stored position is a FRACTION of the guest viewport, so it survives a
+ * resolution change; its size is CSS pixels, because content is laid out in pixels. Rectangles go
+ * out in CSS pixels relative to that same viewport, which is what the host's cursor hit test needs.
+ * That mapping assumes the guest fills the host window — true when the shell sizes the game frame
+ * to the viewport, and the shell is expected to verify it before entering overlay mode rather than
+ * shipping boxes that hit-test somewhere else.
+ */
+import type { OverlayBoxPlacement, OverlayBoxRect, OverlayBoxSpec } from "../protocol/overlay.js";
+/**
+ * The slice of the session this module needs.
+ *
+ * A structural type, not `PlatformSession`, for the same reason `OptionMenuSession` is: a showcase
+ * page or a test can pass a hand-written stub and see real boxes with no platform in the loop.
+ */
+export interface OverlaySession {
+    overlay: {
+        readonly supported: boolean;
+        readonly active: boolean;
+        defineBoxes(boxes: OverlayBoxSpec[]): void;
+        publishRects(rects: OverlayBoxRect[]): void;
+        setDragging(dragging: boolean): void;
+        moveBox(id: string, x: number, y: number): void;
+        onStateChange(cb: (active: boolean) => void): () => void;
+        onLayout(cb: (placements: Record<string, OverlayBoxPlacement>) => void): () => void;
+    };
+}
+/** One live box. `body` is yours to render into; everything else is managed here. */
+export interface OverlayBoxHandle {
+    readonly id: string;
+    /** Render the box's content in here. This module never touches its children. */
+    readonly body: HTMLElement;
+    /** Hide or show this box without redeclaring the set. */
+    setVisible(visible: boolean): void;
+    readonly visible: boolean;
+}
+export interface OverlayBoxesHandle {
+    readonly boxes: readonly OverlayBoxHandle[];
+    get(id: string): OverlayBoxHandle | undefined;
+    /** Replace the whole set. Boxes whose id survives keep their element, and their content. */
+    define(specs: OverlayBoxSpec[]): void;
+    /** Remove the layer and unsubscribe. Safe to call twice. */
+    dispose(): void;
+}
+export interface OverlayBoxesOptions {
+    /** Where to mount the layer. Default `document.body`. */
+    host?: HTMLElement;
+    /**
+     * Let the rider drag a box to reposition it. Default true.
+     *
+     * Pass false for a game that positions boxes itself; the host still hit-tests them, so they
+     * remain clickable, they just don't move.
+     */
+    draggable?: boolean;
+}
+export declare function mountOverlayBoxes(session: OverlaySession, specs: OverlayBoxSpec[], options?: OverlayBoxesOptions): OverlayBoxesHandle;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/overlay/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAElG;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE;QACP,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;QAC3C,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;QAC5C,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;QACrC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAChD,aAAa,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;QACzD,QAAQ,CAAC,EAAE,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KACrF,CAAC;CACH;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,yDAAyD;IACzD,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAC9C,4FAA4F;IAC5F,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACtC,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoCD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA0OpB"}

package/dist/overlay/index.js

@@ -0,0 +1,242 @@
+const STYLE_ID = "rydr-overlay-css";
+/** Self-contained: this module does not pull in the `./ui` stylesheet, so it stays standalone. */
+function injectCss() {
+    if (typeof document === "undefined" || document.getElementById(STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = `
+.rydr-overlay-layer{position:fixed;inset:0;pointer-events:none;z-index:60}
+.rydr-overlay-layer[hidden]{display:none}
+/* Only the boxes take the pointer. The layer covers everything, so making IT interactive would
+   swallow every click the host meant to let through. */
+.rydr-overlay-box{position:absolute;pointer-events:auto;box-sizing:border-box;
+  display:flex;align-items:stretch;justify-content:stretch}
+.rydr-overlay-box[hidden]{display:none}
+.rydr-overlay-box[data-draggable="true"]{cursor:grab}
+.rydr-overlay-box[data-dragging="true"]{cursor:grabbing;user-select:none}
+.rydr-overlay-body{flex:1;min-width:0;min-height:0}
+`;
+    document.head.appendChild(style);
+}
+export function mountOverlayBoxes(session, specs, options = {}) {
+    injectCss();
+    const host = options.host ?? document.body;
+    const draggable = options.draggable !== false;
+    const layer = document.createElement("div");
+    layer.className = "rydr-overlay-layer";
+    // Hidden until the host says overlay mode is on, so declaring boxes early cannot leave them
+    // floating over the game's ordinary screen.
+    layer.hidden = !session.overlay.active;
+    host.appendChild(layer);
+    const boxes = new Map();
+    /** The rider's stored overrides, remembered so a later `define()` still honours them. */
+    let placements = {};
+    let disposed = false;
+    let rectFrame = 0;
+    /**
+     * The box a fraction is a fraction OF.
+     *
+     * The LAYER's own size, not the window's. In a game they are the same thing — the layer is
+     * `position: fixed; inset: 0` — but a showcase page that mounts the layer inside a panel would
+     * otherwise place boxes by the window and scatter them outside it. Measuring what we actually
+     * position within is both correct there and identical here.
+     *
+     * Published rectangles are unaffected: `getBoundingClientRect` is already viewport-relative,
+     * which is what the host's cursor hit test needs.
+     */
+    function viewport() {
+        const r = layer.getBoundingClientRect();
+        return { w: r.width || window.innerWidth || 1, h: r.height || window.innerHeight || 1 };
+    }
+    function place(box) {
+        const { w: vw, h: vh } = viewport();
+        box.el.style.left = `${Math.round(box.x * vw)}px`;
+        box.el.style.top = `${Math.round(box.y * vh)}px`;
+        box.el.style.width = `${box.w}px`;
+        box.el.style.height = `${box.h}px`;
+        box.el.hidden = !box.visible;
+    }
+    /**
+     * Tell the host where the boxes are — coalesced to one report per frame.
+     *
+     * Every move, resize and visibility change would otherwise post its own message, and a drag
+     * fires per pointer event.
+     */
+    function publish() {
+        if (disposed || rectFrame)
+            return;
+        rectFrame = requestAnimationFrame(() => {
+            rectFrame = 0;
+            if (disposed)
+                return;
+            const rects = [];
+            for (const box of boxes.values()) {
+                // An invisible box must not be grabbable: there is nothing on screen to aim at, and the
+                // host would hand over the mouse for a click the rider aimed at whatever is behind.
+                if (!box.visible)
+                    continue;
+                const r = box.el.getBoundingClientRect();
+                rects.push({ id: box.spec.id, x: r.left, y: r.top, w: r.width, h: r.height });
+            }
+            session.overlay.publishRects(rects);
+        });
+    }
+    function effective(spec) {
+        return placements[spec.id] ?? {};
+    }
+    function applyPlacement(box) {
+        const p = effective(box.spec);
+        box.x = p.x ?? box.spec.x;
+        box.y = p.y ?? box.spec.y;
+        box.w = p.w ?? box.spec.width;
+        box.h = p.h ?? box.spec.height;
+        // The GAME's visibility wins when it says hidden: a rider override may only reveal a box the
+        // game is willing to show, never force one it has deliberately taken away.
+        box.visible = box.spec.visible && (p.visible ?? true);
+        place(box);
+    }
+    function attachDrag(box) {
+        if (!draggable)
+            return;
+        box.el.dataset["draggable"] = "true";
+        box.el.addEventListener("pointerdown", (event) => {
+            if (event.button !== 0)
+                return;
+            const start = box.el.getBoundingClientRect();
+            const grabX = event.clientX - start.left;
+            const grabY = event.clientY - start.top;
+            box.el.dataset["dragging"] = "true";
+            box.el.setPointerCapture(event.pointerId);
+            // The host holds the mouse for the whole gesture; without this it would take it back the
+            // moment the cursor left the box and the drag would end mid-flight.
+            session.overlay.setDragging(true);
+            event.preventDefault();
+            const move = (e) => {
+                const { w: vw, h: vh } = viewport();
+                // Clamped so a box cannot be dropped off-screen: there is no window frame to drag it back
+                // by, and the only recovery would be resetting the layout.
+                const left = Math.min(Math.max(e.clientX - grabX, 0), Math.max(vw - box.w, 0));
+                const top = Math.min(Math.max(e.clientY - grabY, 0), Math.max(vh - box.h, 0));
+                box.x = left / vw;
+                box.y = top / vh;
+                place(box);
+                publish();
+            };
+            const end = () => {
+                box.el.removeEventListener("pointermove", move);
+                box.el.removeEventListener("pointerup", end);
+                box.el.removeEventListener("pointercancel", end);
+                delete box.el.dataset["dragging"];
+                session.overlay.setDragging(false);
+                // Remembered locally as well as reported, so a later `define()` doesn't snap the box back
+                // to the game's default while the host's echo is still in flight.
+                placements = { ...placements, [box.spec.id]: { ...placements[box.spec.id], x: box.x, y: box.y } };
+                session.overlay.moveBox(box.spec.id, box.x, box.y);
+                publish();
+            };
+            box.el.addEventListener("pointermove", move);
+            box.el.addEventListener("pointerup", end);
+            box.el.addEventListener("pointercancel", end);
+        });
+    }
+    function create(spec) {
+        const el = document.createElement("div");
+        el.className = "rydr-overlay-box";
+        el.dataset["boxId"] = spec.id;
+        const body = document.createElement("div");
+        body.className = "rydr-overlay-body";
+        el.appendChild(body);
+        layer.appendChild(el);
+        const box = { spec, el, body, x: spec.x, y: spec.y, w: spec.width, h: spec.height, visible: spec.visible };
+        applyPlacement(box);
+        attachDrag(box);
+        return box;
+    }
+    function define(next) {
+        if (disposed)
+            return;
+        const seen = new Set();
+        for (const spec of next) {
+            seen.add(spec.id);
+            const existing = boxes.get(spec.id);
+            if (existing) {
+                // Reuse the element so the game's content survives a redeclaration — rebuilding would
+                // throw away whatever it had rendered and flicker on every set change.
+                existing.spec = spec;
+                applyPlacement(existing);
+                continue;
+            }
+            boxes.set(spec.id, create(spec));
+        }
+        for (const [id, box] of [...boxes]) {
+            if (seen.has(id))
+                continue;
+            box.el.remove();
+            boxes.delete(id);
+        }
+        session.overlay.defineBoxes(next);
+        publish();
+    }
+    const offState = session.overlay.onStateChange((active) => {
+        layer.hidden = !active;
+        // Republish on entering: rects measured while hidden are all zero, and the host would have
+        // nothing to hit-test against.
+        publish();
+    });
+    const offLayout = session.overlay.onLayout((next) => {
+        placements = next ?? {};
+        for (const box of boxes.values())
+            applyPlacement(box);
+        publish();
+    });
+    // A resolution or window change moves every box, because positions are fractions.
+    const onResize = () => {
+        for (const box of boxes.values())
+            place(box);
+        publish();
+    };
+    window.addEventListener("resize", onResize);
+    define(specs);
+    return {
+        get boxes() {
+            return [...boxes.values()].map(toHandle);
+        },
+        get: (id) => {
+            const box = boxes.get(id);
+            return box ? toHandle(box) : undefined;
+        },
+        define,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            if (rectFrame)
+                cancelAnimationFrame(rectFrame);
+            offState();
+            offLayout();
+            window.removeEventListener("resize", onResize);
+            layer.remove();
+            boxes.clear();
+            // Tell the host the boxes are gone, or it would keep hit-testing rectangles that are no
+            // longer on screen and hand the mouse to empty space.
+            session.overlay.publishRects([]);
+            session.overlay.defineBoxes([]);
+        },
+    };
+    function toHandle(box) {
+        return {
+            id: box.spec.id,
+            body: box.body,
+            get visible() {
+                return box.visible;
+            },
+            setVisible: (visible) => {
+                box.visible = visible && box.spec.visible;
+                place(box);
+                publish();
+            },
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/overlay/index.js.map

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

package/dist/protocol/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/protocol/guards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EACV,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAwDvB,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW,CAI1D;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,qBAAqB,CAE9E;AAED,8FAA8F;AAC9F,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,qBAAqB,CAE9E"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/protocol/guards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EACV,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AA0DvB,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW,CAI1D;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,qBAAqB,CAE9E;AAED,8FAA8F;AAC9F,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,qBAAqB,CAE9E"}

package/dist/protocol/guards.js

@@ -23,6 +23,8 @@ const PLATFORM_TO_GAME = {
     "rydr/audio.setMaster": true,
     "rydr/identity.update": true,
     "rydr/trainer.status": true,
+    "rydr/overlay.state": true,
+    "rydr/overlay.layout": true,
     "rydr/lifecycle.pause": true,
     "rydr/lifecycle.resume": true,
     "rydr/ping": true,

package/dist/protocol/guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/protocol/guards.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AACH,MAAM,gBAAgB,GAAgD;IACpE,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,IAAI;IACzB,eAAe,EAAE,IAAI;IACrB,qBAAqB,EAAE,IAAI;IAC3B,mBAAmB,EAAE,IAAI;IACzB,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,IAAI;IACzB,sBAAsB,EAAE,IAAI;IAC5B,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,sBAAsB,EAAE,IAAI;IAC5B,uBAAuB,EAAE,IAAI;IAC7B,WAAW,EAAE,IAAI;IACjB,8BAA8B,EAAE,IAAI;IACpC,kCAAkC,EAAE,IAAI;IACxC,0BAA0B,EAAE,IAAI;IAChC,sBAAsB,EAAE,IAAI;IAC5B,4BAA4B,EAAE,IAAI;IAClC,+BAA+B,EAAE,IAAI;IACrC,4BAA4B,EAAE,IAAI;IAClC,oBAAoB,EAAE,IAAI;IAC1B,iBAAiB,EAAE,IAAI;IACvB,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,uBAAuB,EAAE,IAAI;IAC7B,sBAAsB,EAAE,IAAI;IAC5B,2BAA2B,EAAE,IAAI;IACjC,0BAA0B,EAAE,IAAI;IAChC,oBAAoB,EAAE,IAAI;IAC1B,kBAAkB,EAAE,IAAI;IACxB,kBAAkB,EAAE,IAAI;IACxB,oBAAoB,EAAE,IAAI;IAC1B,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,IAAI;IACzB,qBAAqB,EAAE,IAAI;IAC3B,iBAAiB,EAAE,IAAI;CACxB,CAAC;AACF,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAE3F,+CAA+C;AAC/C,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,CAAC,GAAG,CAAuC,CAAC;IAClD,OAAO,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AACrF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,uBAAuB,CAAC,CAAU;IAChD,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAChE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,uBAAuB,CAAC,CAAU;IAChD,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/protocol/guards.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AACH,MAAM,gBAAgB,GAAgD;IACpE,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI;IACrB,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,IAAI;IACzB,eAAe,EAAE,IAAI;IACrB,qBAAqB,EAAE,IAAI;IAC3B,mBAAmB,EAAE,IAAI;IACzB,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,IAAI;IACzB,sBAAsB,EAAE,IAAI;IAC5B,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,oBAAoB,EAAE,IAAI;IAC1B,qBAAqB,EAAE,IAAI;IAC3B,sBAAsB,EAAE,IAAI;IAC5B,uBAAuB,EAAE,IAAI;IAC7B,WAAW,EAAE,IAAI;IACjB,8BAA8B,EAAE,IAAI;IACpC,kCAAkC,EAAE,IAAI;IACxC,0BAA0B,EAAE,IAAI;IAChC,sBAAsB,EAAE,IAAI;IAC5B,4BAA4B,EAAE,IAAI;IAClC,+BAA+B,EAAE,IAAI;IACrC,4BAA4B,EAAE,IAAI;IAClC,oBAAoB,EAAE,IAAI;IAC1B,iBAAiB,EAAE,IAAI;IACvB,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,uBAAuB,EAAE,IAAI;IAC7B,sBAAsB,EAAE,IAAI;IAC5B,2BAA2B,EAAE,IAAI;IACjC,0BAA0B,EAAE,IAAI;IAChC,oBAAoB,EAAE,IAAI;IAC1B,kBAAkB,EAAE,IAAI;IACxB,kBAAkB,EAAE,IAAI;IACxB,oBAAoB,EAAE,IAAI;IAC1B,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,IAAI;IACzB,qBAAqB,EAAE,IAAI;IAC3B,iBAAiB,EAAE,IAAI;CACxB,CAAC;AACF,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAE3F,+CAA+C;AAC/C,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,CAAC,GAAG,CAAuC,CAAC;IAClD,OAAO,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AACrF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,uBAAuB,CAAC,CAAU;IAChD,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAChE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,uBAAuB,CAAC,CAAU;IAChD,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC"}

package/dist/protocol/identity.d.ts

@@ -6,6 +6,60 @@
  * name, and the physics metrics it explicitly requested. This is the privacy
  * boundary that makes third-party games safe.
  */
+/**
+ * What CONTENT this rider may see, as a ladder: `free` < `beta` < `all_access`, each rung
+ * containing the one below it.
+ *
+ * | Tier | The rider gets |
+ * |---|---|
+ * | `free` | the free experiences only |
+ * | `beta` | the free ones plus early access |
+ * | `all_access` | everything, including unpublished content |
+ *
+ * ## The platform states the fact, the game applies the policy
+ *
+ * Which of YOUR experiences are free is yours to decide, not the platform's: it knows nothing
+ * about your tracks, songs or levels, and a list of them kept platform-side would drift the first
+ * time someone shipped content without updating it. So the host says which tier the rider is on and
+ * your game decides what that unlocks. Same division as the FTP difficulty ladder: the platform
+ * hands over a calibrated fact, the game decides what to do with it.
+ *
+ * ## Fewer values than the platform has
+ *
+ * The platform also holds buckets meaning "cannot play at all" (waiting for a beta place, played at
+ * an event, access ended). None of them can appear here, because a game only ever runs for a rider
+ * who is already playing. Do not add branches for states that cannot arrive.
+ *
+ * ## Never compare it directly
+ *
+ * Use {@link tierAtLeast}. A bare `tier === "beta"` excludes `all_access` riders from content they
+ * are entitled to, silently, and the day a tier is inserted into the middle of the ladder every
+ * such comparison is wrong at once.
+ */
+export type AccessTier = "free" | "beta" | "all_access";
+/**
+ * What an ABSENT tier means, and why it is not the lowest one.
+ *
+ * The field is missing whenever an older host meets a newer game (the host simply does not send
+ * it). Reading that as `free` would strip content from fully entitled riders during any version
+ * skew, which is a worse failure than briefly showing someone one track too many. So absence means
+ * today's behaviour, which is `beta`.
+ *
+ * A compatibility default, not a policy: a host that HAS tiers always sends one.
+ */
+export declare const DEFAULT_ACCESS_TIER: AccessTier;
+/**
+ * Is this rider on `min` or better? The one way to read {@link AccessTier}.
+ *
+ * ```ts
+ * if (tierAtLeast(identity.accessTier, "beta")) showEarlyAccessTracks();
+ * ```
+ *
+ * An absent tier counts as {@link DEFAULT_ACCESS_TIER}, and an unrecognised one (a host newer than
+ * this SDK, sending a tier that did not exist when you built) counts the same way rather than
+ * throwing: a game mid-session should not crash because the ladder grew.
+ */
+export declare function tierAtLeast(tier: AccessTier | undefined, min: AccessTier): boolean;
 export interface ScopedIdentity {
     /** Stable, opaque per-player id. Safe to use as a key; reveals no PII. */
     playerId: string;
@@ -24,5 +78,14 @@ export interface ScopedIdentity {
      * enforces auth via RLS on the admin role.
      */
     isAdmin?: boolean;
+    /**
+     * What content this rider is entitled to (see {@link AccessTier}). Read it with
+     * {@link tierAtLeast}, never by comparing it.
+     *
+     * A UI hint, exactly like {@link isAdmin}: it tells your game what to OFFER. Nothing stops a
+     * modified guest from ignoring it, so the day real money hangs on a tier the enforcement has to
+     * be server-side as well. Absent means {@link DEFAULT_ACCESS_TIER}.
+     */
+    accessTier?: AccessTier;
 }
 //# sourceMappingURL=identity.d.ts.map

package/dist/protocol/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAAmB,CAAC;AAStD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAGlF;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB"}

package/dist/protocol/identity.js

@@ -1,2 +1,41 @@
-export {};
+/**
+ * The scoped identity a game receives — deliberately NOT the full player profile.
+ *
+ * The platform holds PII (real name, gender, year of birth, exact weight). A
+ * game only ever receives this redacted view: a stable opaque id, a display
+ * name, and the physics metrics it explicitly requested. This is the privacy
+ * boundary that makes third-party games safe.
+ */
+/**
+ * What an ABSENT tier means, and why it is not the lowest one.
+ *
+ * The field is missing whenever an older host meets a newer game (the host simply does not send
+ * it). Reading that as `free` would strip content from fully entitled riders during any version
+ * skew, which is a worse failure than briefly showing someone one track too many. So absence means
+ * today's behaviour, which is `beta`.
+ *
+ * A compatibility default, not a policy: a host that HAS tiers always sends one.
+ */
+export const DEFAULT_ACCESS_TIER = "beta";
+/** Position on the ladder. Private on purpose: ask {@link tierAtLeast}, never a number. */
+const TIER_RANK = {
+    free: 0,
+    beta: 1,
+    all_access: 2,
+};
+/**
+ * Is this rider on `min` or better? The one way to read {@link AccessTier}.
+ *
+ * ```ts
+ * if (tierAtLeast(identity.accessTier, "beta")) showEarlyAccessTracks();
+ * ```
+ *
+ * An absent tier counts as {@link DEFAULT_ACCESS_TIER}, and an unrecognised one (a host newer than
+ * this SDK, sending a tier that did not exist when you built) counts the same way rather than
+ * throwing: a game mid-session should not crash because the ladder grew.
+ */
+export function tierAtLeast(tier, min) {
+    const have = TIER_RANK[tier] ?? TIER_RANK[DEFAULT_ACCESS_TIER];
+    return have >= TIER_RANK[min];
+}
 //# sourceMappingURL=identity.js.map

package/dist/protocol/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":""}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkCH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAe,MAAM,CAAC;AAEtD,2FAA2F;AAC3F,MAAM,SAAS,GAA+B;IAC5C,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,UAAU,EAAE,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAA4B,EAAE,GAAe;IACvE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAkB,CAAC,IAAI,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC7E,OAAO,IAAI,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC"}

package/dist/protocol/index.d.ts

@@ -6,6 +6,7 @@ export * from "./buttons.js";
 export * from "./glyphs.js";
 export * from "./haptics.js";
 export * from "./boards.js";
+export * from "./overlay.js";
 export * from "./gamedata.js";
 export * from "./worlds.js";
 export * from "./characters.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/protocol/index.js

@@ -6,6 +6,7 @@ export * from "./buttons.js";
 export * from "./glyphs.js";
 export * from "./haptics.js";
 export * from "./boards.js";
+export * from "./overlay.js";
 export * from "./gamedata.js";
 export * from "./worlds.js";
 export * from "./characters.js";

package/dist/protocol/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/protocol/messages.d.ts

@@ -16,6 +16,7 @@ import type { ButtonName, ButtonEdge, AxisName } from "./buttons.js";
 import type { GlyphSet } from "./glyphs.js";
 import type { HapticEffect } from "./haptics.js";
 import type { BoardDefinition, BoardEntry, ScoreSubmission, SubmitScoreResult, AdminSeedEntry, LeaderboardPage } from "./boards.js";
+import type { OverlayBoxPlacement, OverlayBoxRect, OverlayBoxSpec } from "./overlay.js";
 import type { GameDataScope, GameDoc } from "./gamedata.js";
 import type { CoreWorld } from "./worlds.js";
 import type { CatalogCharacter, CharacterRig } from "./characters.js";
@@ -69,6 +70,44 @@ export interface TrainerSetErgModeMessage extends RydrTagged {
     type: "rydr/trainer.setErgMode";
     enabled: boolean;
 }
+/**
+ * Ask to enter or leave overlay mode.
+ *
+ * A request, not a statement: the host answers with {@link OverlayStateMessage}, and may also send
+ * that unprompted when the RIDER leaves by some route of its own (a tray item, a global shortcut).
+ * Never assume this took effect.
+ */
+export interface OverlaySetModeMessage extends RydrTagged {
+    type: "rydr/overlay.setMode";
+    enabled: boolean;
+}
+/** Declare the game's box set, replacing any previous one. */
+export interface OverlayDefineBoxesMessage extends RydrTagged {
+    type: "rydr/overlay.defineBoxes";
+    boxes: OverlayBoxSpec[];
+}
+/** Publish where the boxes now are, so the host can hit-test the cursor against them. */
+export interface OverlayRectsMessage extends RydrTagged {
+    type: "rydr/overlay.rects";
+    rects: OverlayBoxRect[];
+}
+/**
+ * A box drag started or ended.
+ *
+ * The host must keep giving the game the mouse for the whole drag, or the box would be dropped the
+ * instant the cursor outran it.
+ */
+export interface OverlayDraggingMessage extends RydrTagged {
+    type: "rydr/overlay.dragging";
+    dragging: boolean;
+}
+/** A box was dropped. `x`/`y` are fractions of the usable screen area, for the host to remember. */
+export interface OverlayMoveBoxMessage extends RydrTagged {
+    type: "rydr/overlay.moveBox";
+    id: string;
+    x: number;
+    y: number;
+}
 /**
  * Request the rate at which the shell streams hardware to this game. `hz` is a ceiling, never an
  * upsampler: the shell averages the trainer's faster native samples down to `hz` (anti-aliased —
@@ -377,7 +416,7 @@ export interface RoomScheduleEventMessage extends RydrTagged {
     payload?: unknown;
     at?: number;
 }
-export type GameToPlatformMessage = HelloMessage | ReadyMessage | LoadProgressMessage | PongMessage | TrainerSetSimulationMessage | TrainerSetTargetPowerMessage | TrainerSetErgModeMessage | HwSetRateMessage | RouteChangedMessage | SetPowerBarMessage | SetActivityMessage | ExitRequestMessage | RequestHardwareModalMessage | GameErrorMessage | LeaderboardQueryMessage | LeaderboardRankQueryMessage | AdminBoardsMessage | RunSaveMessage | RunStartMessage | HapticsVibrateMessage | TrainerAdjustResistanceMessage | RiderAdjustFtpMessage | MenuToggleMessage | GameDataGetMessage | GameDataListMessage | GameDataSaveMessage | GameDataDeleteMessage | AssetUploadUrlMessage | VoiceoverGenerateMessage | MediaUploadUrlMessage | MediaSavedMessage | ReplaySaveMessage | ReplayGetMessage | RunGetMessage | WorldListMessage | WorldGetMessage | CharacterListMessage | CharacterGetMessage | RigGetMessage | RoomJoinMessage | RoomLeaveMessage | RoomSendMessage | RoomSetStateMessage | RoomScheduleEventMessage;
+export type GameToPlatformMessage = HelloMessage | ReadyMessage | LoadProgressMessage | PongMessage | TrainerSetSimulationMessage | TrainerSetTargetPowerMessage | TrainerSetErgModeMessage | OverlaySetModeMessage | OverlayDefineBoxesMessage | OverlayRectsMessage | OverlayDraggingMessage | OverlayMoveBoxMessage | HwSetRateMessage | RouteChangedMessage | SetPowerBarMessage | SetActivityMessage | ExitRequestMessage | RequestHardwareModalMessage | GameErrorMessage | LeaderboardQueryMessage | LeaderboardRankQueryMessage | AdminBoardsMessage | RunSaveMessage | RunStartMessage | HapticsVibrateMessage | TrainerAdjustResistanceMessage | RiderAdjustFtpMessage | MenuToggleMessage | GameDataGetMessage | GameDataListMessage | GameDataSaveMessage | GameDataDeleteMessage | AssetUploadUrlMessage | VoiceoverGenerateMessage | MediaUploadUrlMessage | MediaSavedMessage | ReplaySaveMessage | ReplayGetMessage | RunGetMessage | WorldListMessage | WorldGetMessage | CharacterListMessage | CharacterGetMessage | RigGetMessage | RoomJoinMessage | RoomLeaveMessage | RoomSendMessage | RoomSetStateMessage | RoomScheduleEventMessage;
 /** Accepts the handshake: grants capabilities and hands over the scoped identity. */
 export interface WelcomeMessage extends RydrTagged {
     type: "rydr/welcome";
@@ -400,6 +439,17 @@ export interface WelcomeMessage extends RydrTagged {
      *  right glyphs instead of waiting for the first `input.status`. Omitted ⇒
      *  {@link DEFAULT_GLYPH_SET}. See {@link InputStatusMessage} for the update channel. */
     glyphSet?: GlyphSet;
+    /**
+     * Whether this host can put the game's boxes on top of everything else on the machine — see
+     * ./overlay.ts. False or absent in an ordinary browser tab, and true only when the host supports
+     * it AND the game's manifest declares an overlay mode.
+     *
+     * On `welcome` rather than a status message on purpose: it cannot change mid-session, and
+     * arriving with the handshake means the game's FIRST frame already knows, so nothing has to
+     * render twice. (`TrainerStatusMessage.ergSupported` is the counter-example — it can go stale,
+     * because there is no channel that re-pushes it.)
+     */
+    overlaySupported?: boolean;
 }
 /** Rejects the handshake (e.g. unknown game, unsupported protocol, denied capabilities). */
 export interface RejectMessage extends RydrTagged {
@@ -752,7 +802,28 @@ export interface RoomEventMessage extends RydrTagged {
     at: number;
     from: string;
 }
-export type PlatformToGameMessage = WelcomeMessage | RejectMessage | PowerMessage | CadenceMessage | HeartRateMessage | SpeedMessage | PowerBufferMessage | InputButtonMessage | InputAxisMessage | AudioSetMasterMessage | IdentityUpdateMessage | TrainerStatusMessage | InputStatusMessage | LifecyclePauseMessage | LifecycleResumeMessage | PingMessage | LeaderboardQueryResultMessage | LeaderboardRankQueryResultMessage | AdminBoardsResultMessage | GameDataResultMessage | AssetUploadUrlResultMessage | VoiceoverGenerateResultMessage | MediaUploadUrlResultMessage | ReplayResultMessage | RunGetResultMessage | RunStartResultMessage | RunSaveResultMessage | WorldListResultMessage | WorldGetResultMessage | CharacterListResultMessage | CharacterGetResultMessage | RigGetResultMessage | RoomOpenedMessage | RoomClosedMessage | RoomPresenceMessage | RoomStateMessage | RoomMessageMessage | RoomTelemetryMessage | RoomEventMessage;
+/**
+ * Overlay mode was entered or left.
+ *
+ * Sent in answer to {@link OverlaySetModeMessage}, and ALSO unprompted when the rider leaves by a
+ * route the game cannot see. While the overlay is click-through the game's own menus are
+ * unreachable, so the host's tray or shortcut is the way out and this is how the game finds out.
+ */
+export interface OverlayStateMessage extends RydrTagged {
+    type: "rydr/overlay.state";
+    active: boolean;
+}
+/**
+ * The rider's stored box placements, to apply over the game's declared defaults.
+ *
+ * Keyed by box id and sparse: a box with no entry has never been moved. Arrives on entering
+ * overlay mode and whenever the host has something new to say about it.
+ */
+export interface OverlayLayoutMessage extends RydrTagged {
+    type: "rydr/overlay.layout";
+    placements: Record<string, OverlayBoxPlacement>;
+}
+export type PlatformToGameMessage = WelcomeMessage | RejectMessage | PowerMessage | CadenceMessage | HeartRateMessage | SpeedMessage | PowerBufferMessage | InputButtonMessage | InputAxisMessage | AudioSetMasterMessage | IdentityUpdateMessage | TrainerStatusMessage | OverlayStateMessage | OverlayLayoutMessage | InputStatusMessage | LifecyclePauseMessage | LifecycleResumeMessage | PingMessage | LeaderboardQueryResultMessage | LeaderboardRankQueryResultMessage | AdminBoardsResultMessage | GameDataResultMessage | AssetUploadUrlResultMessage | VoiceoverGenerateResultMessage | MediaUploadUrlResultMessage | ReplayResultMessage | RunGetResultMessage | RunStartResultMessage | RunSaveResultMessage | WorldListResultMessage | WorldGetResultMessage | CharacterListResultMessage | CharacterGetResultMessage | RigGetResultMessage | RoomOpenedMessage | RoomClosedMessage | RoomPresenceMessage | RoomStateMessage | RoomMessageMessage | RoomTelemetryMessage | RoomEventMessage;
 /** Any message in the protocol. */
 export type RydrMessage = GameToPlatformMessage | PlatformToGameMessage;
 export {};