@rydr/game-sdk 3.10.0 → 3.12.0

package/dist/sounds/sound-bank.js

@@ -0,0 +1,313 @@
+import { SOUND_CATEGORIES } from "./types.js";
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+const dbToGain = (db) => Math.pow(10, db / 20);
+/** Uniform in [-mag, +mag]. Deterministic-free; variation only needs perceptual jitter. */
+const jitter = (mag) => (mag > 0 ? (Math.random() * 2 - 1) * mag : 0);
+/**
+ * A shuffle-bag: deals every item once (shuffled) before repeating, and never repeats the last item
+ * across a reshuffle — so an N-clip event cycles through all N with no immediate repeat. Beats
+ * `Math.random()` picking, which is what makes repeated SFX sound repetitive.
+ */
+class Bag {
+    size;
+    order = [];
+    last = -1;
+    constructor(size) {
+        this.size = size;
+    }
+    next() {
+        if (this.size <= 1)
+            return 0;
+        if (this.order.length === 0) {
+            this.order = Array.from({ length: this.size }, (_, i) => i);
+            for (let i = this.order.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                const a = this.order[i];
+                this.order[i] = this.order[j];
+                this.order[j] = a;
+            }
+            if (this.order[0] === this.last && this.order.length > 1) {
+                const a = this.order[0];
+                this.order[0] = this.order[1];
+                this.order[1] = a;
+            }
+        }
+        const idx = this.order.pop();
+        this.last = idx;
+        return idx;
+    }
+}
+export function createSoundBank(opts = {}) {
+    const ownsContext = !opts.context;
+    let ctx = opts.context ?? null;
+    let master = null;
+    const buses = new Map();
+    const busTargetDb = new Map(); // pre-duck level, so unduck returns here
+    const events = new Map();
+    const bags = new Map();
+    const lastPlayedAt = new Map();
+    const live = new Map();
+    const bufferCache = new Map();
+    let assetList = [];
+    function ensureGraph() {
+        if (ctx && master)
+            return ctx;
+        const AC = typeof window !== "undefined"
+            ? window.AudioContext ?? window.webkitAudioContext
+            : undefined;
+        if (!ctx) {
+            if (!AC)
+                return null;
+            ctx = new AC();
+        }
+        master = ctx.createGain();
+        let tail = master;
+        if (opts.limiter !== false) {
+            const lim = ctx.createDynamicsCompressor();
+            lim.threshold.value = -3;
+            lim.knee.value = 0;
+            lim.ratio.value = 20;
+            lim.attack.value = 0.002;
+            lim.release.value = 0.15;
+            master.connect(lim);
+            tail = lim;
+        }
+        tail.connect(ctx.destination);
+        for (const cat of SOUND_CATEGORIES) {
+            const g = ctx.createGain();
+            g.connect(master);
+            buses.set(cat, g);
+            busTargetDb.set(cat, 0);
+        }
+        return ctx;
+    }
+    function busFor(cat) {
+        ensureGraph();
+        return buses.get(cat) ?? null;
+    }
+    async function decode(url) {
+        const cached = bufferCache.get(url);
+        if (cached)
+            return cached;
+        const p = (async () => {
+            const c = ensureGraph();
+            if (!c)
+                return null;
+            try {
+                const res = await fetch(url);
+                if (!res.ok)
+                    return null;
+                const bytes = await res.arrayBuffer();
+                return await c.decodeAudioData(bytes);
+            }
+            catch {
+                return null;
+            }
+        })();
+        bufferCache.set(url, p);
+        return p;
+    }
+    function trackVoice(key, voice, maxVoices) {
+        const arr = live.get(key) ?? [];
+        arr.push(voice);
+        if (maxVoices && arr.length > maxVoices) {
+            const stolen = arr.shift();
+            try {
+                stolen?.stop();
+            }
+            catch {
+                /* already ended */
+            }
+        }
+        live.set(key, arr);
+    }
+    function untrackVoice(key, voice) {
+        const arr = live.get(key);
+        if (!arr)
+            return;
+        const i = arr.indexOf(voice);
+        if (i >= 0)
+            arr.splice(i, 1);
+    }
+    function pickClip(asset) {
+        if (asset.clips.length === 0)
+            return null;
+        if (asset.clips.length === 1)
+            return asset.clips[0] ?? null;
+        let bag = bags.get(asset.key);
+        if (!bag) {
+            bag = new Bag(asset.clips.length);
+            bags.set(asset.key, bag);
+        }
+        return asset.clips[bag.next()] ?? null;
+    }
+    function playStream(asset, clip, bus, c, o) {
+        if (typeof Audio === "undefined")
+            return null;
+        const media = new Audio();
+        media.crossOrigin = "anonymous";
+        media.src = clip.url;
+        media.loop = o.loop ?? (asset.category === "music" || asset.category === "ambience");
+        const src = c.createMediaElementSource(media);
+        const g = c.createGain();
+        g.gain.value = dbToGain((asset.gainDb ?? 0) + (o.gainDb ?? 0) + jitter(asset.variation?.volumeDb ?? 0));
+        src.connect(g).connect(bus);
+        void media.play().catch(() => undefined);
+        const voice = {
+            stop: () => {
+                media.pause();
+                try {
+                    src.disconnect();
+                }
+                catch {
+                    /* noop */
+                }
+                untrackVoice(asset.key, voice);
+            },
+        };
+        media.addEventListener("ended", () => voice.stop());
+        trackVoice(asset.key, voice, asset.variation?.maxVoices);
+        return { key: asset.key, stop: voice.stop };
+    }
+    return {
+        async load() {
+            let manifest = opts.manifest ?? null;
+            if (!manifest && opts.manifestUrl) {
+                try {
+                    const res = await fetch(opts.manifestUrl, { cache: "no-cache" });
+                    if (res.ok)
+                        manifest = (await res.json());
+                }
+                catch {
+                    manifest = null;
+                }
+            }
+            assetList = manifest?.sounds ?? [];
+            events.clear();
+            for (const a of assetList)
+                events.set(a.key, a);
+        },
+        async preload(keys) {
+            const targets = (keys ? keys.map((k) => events.get(k)) : assetList).filter((a) => !!a && !a.stream);
+            await Promise.all(targets.flatMap((a) => a.clips.map((cl) => decode(cl.url))));
+        },
+        play(key, o = {}) {
+            const asset = events.get(key);
+            if (!asset)
+                return null;
+            const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+            const cd = asset.variation?.cooldownMs ?? 0;
+            if (cd > 0 && now - (lastPlayedAt.get(key) ?? -Infinity) < cd)
+                return null;
+            lastPlayedAt.set(key, now);
+            const c = ensureGraph();
+            if (!c)
+                return null;
+            if (c.state === "suspended")
+                void c.resume().catch(() => undefined);
+            const bus = busFor(asset.category);
+            if (!bus)
+                return null;
+            const clip = pickClip(asset);
+            if (!clip)
+                return null;
+            if (asset.stream)
+                return playStream(asset, clip, bus, c, o);
+            // Decode-to-memory path (SFX): fire-and-forget; the buffer is cached after first play.
+            const handle = { stopped: false, voice: null };
+            void decode(clip.url).then((buf) => {
+                if (!buf || handle.stopped)
+                    return;
+                const src = c.createBufferSource();
+                src.buffer = buf;
+                src.loop = o.loop ?? false;
+                src.detune.value = jitter(asset.variation?.pitchCents ?? 0) + (o.detuneCents ?? 0);
+                const g = c.createGain();
+                g.gain.value = dbToGain((asset.gainDb ?? 0) + (o.gainDb ?? 0) + jitter(asset.variation?.volumeDb ?? 0));
+                src.connect(g).connect(bus);
+                const voice = {
+                    stop: () => {
+                        try {
+                            src.stop();
+                        }
+                        catch {
+                            /* already stopped */
+                        }
+                        untrackVoice(asset.key, voice);
+                    },
+                };
+                src.addEventListener("ended", () => untrackVoice(asset.key, voice));
+                trackVoice(asset.key, voice, asset.variation?.maxVoices);
+                handle.voice = voice;
+                src.start();
+            });
+            return {
+                key,
+                stop: () => {
+                    handle.stopped = true;
+                    handle.voice?.stop();
+                },
+            };
+        },
+        stop(key) {
+            const arr = live.get(key);
+            if (!arr)
+                return;
+            for (const v of [...arr]) {
+                try {
+                    v.stop();
+                }
+                catch {
+                    /* noop */
+                }
+            }
+            live.set(key, []);
+        },
+        setBusVolume(category, db) {
+            busTargetDb.set(category, db);
+            const g = busFor(category);
+            if (g && ctx)
+                g.gain.setTargetAtTime(dbToGain(db), ctx.currentTime, 0.01);
+        },
+        setMasterVolume(db) {
+            ensureGraph();
+            if (master && ctx)
+                master.gain.setTargetAtTime(dbToGain(clamp(db, -60, 6)), ctx.currentTime, 0.01);
+        },
+        duck(category, db, ms = 120) {
+            const g = busFor(category);
+            if (!g || !ctx)
+                return;
+            const target = (busTargetDb.get(category) ?? 0) - Math.abs(db);
+            g.gain.setTargetAtTime(dbToGain(target), ctx.currentTime, Math.max(0.005, ms / 1000 / 3));
+        },
+        unduck(category, ms = 250) {
+            const g = busFor(category);
+            if (!g || !ctx)
+                return;
+            g.gain.setTargetAtTime(dbToGain(busTargetDb.get(category) ?? 0), ctx.currentTime, Math.max(0.005, ms / 1000 / 3));
+        },
+        keys: () => [...events.keys()],
+        assets: () => assetList.slice(),
+        dispose() {
+            for (const key of live.keys()) {
+                for (const v of live.get(key) ?? []) {
+                    try {
+                        v.stop();
+                    }
+                    catch {
+                        /* noop */
+                    }
+                }
+            }
+            live.clear();
+            bufferCache.clear();
+            if (ownsContext && ctx)
+                void ctx.close().catch(() => undefined);
+            ctx = null;
+            master = null;
+            buses.clear();
+        },
+    };
+}
+//# sourceMappingURL=sound-bank.js.map

package/dist/sounds/sound-bank.js.map

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

package/dist/sounds/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Sound-library data types — owned by the SDK (like world/character types), so the platform's
+ * `SoundService`/gallery and every game's `SoundBank` share ONE shape. A "sound" is modelled as an
+ * **event** (a stable key + a pool of clips + behaviour), not a bare file — so variation and the
+ * hardware-driven adaptive layer are additive later with no schema migration.
+ */
+/** Mixer bus + organisational category. Each maps to an independently-controllable gain bus. */
+export type SoundCategory = "sfx" | "music" | "ambience" | "ui" | "voice";
+export declare const SOUND_CATEGORIES: readonly SoundCategory[];
+/** One audio file in an event's pool. */
+export interface SoundClip {
+    /** Public R2 URL of the audio (wav/mp3/ogg). */
+    url: string;
+    /** Original upload filename (display only). */
+    filename?: string;
+    /** Duration in seconds, measured at ingest. */
+    durationSec?: number;
+}
+/** Per-play randomisation. The runtime honours it on every {@link SoundBank.play}; all optional. */
+export interface SoundVariation {
+    /** ± random detune per play, in cents (100 = one semitone). 0/undefined = none. */
+    pitchCents?: number;
+    /** ± random gain per play, in dB. 0/undefined = none. */
+    volumeDb?: number;
+    /** Drop retriggers of this event faster than this many ms (anti-machine-gun). */
+    cooldownMs?: number;
+    /** Cap simultaneous live voices of this event; the oldest is stolen. undefined = unlimited. */
+    maxVoices?: number;
+}
+/** Loudness measured at ingest — the input to future normalisation (P2). */
+export interface SoundLoudness {
+    integratedLufs?: number;
+    peakDb?: number;
+}
+/** Provenance/attribution, e.g. for Freesound packs — feeds a future credits manifest. */
+export interface SoundLicense {
+    source?: string;
+    author?: string;
+    url?: string;
+    note?: string;
+}
+/** A library entry: a named, foldered, taggable sound event games play by its stable {@link key}. */
+export interface SoundAsset {
+    /** Stable play key AND Supabase row id (unique within the library): `sounds.play(key)`. */
+    key: string;
+    name: string;
+    label?: string;
+    category: SoundCategory;
+    /** Id of the {@link SoundFolder} this sound is filed under (authoring-only). null/undefined = unfiled. */
+    folderId?: string | null;
+    /** @deprecated Legacy free-text folder path; superseded by {@link folderId}. Kept for back-compat. */
+    folder?: string;
+    tags?: string[];
+    /** Clip pool. One entry today; many enables the random-container variation (P2). */
+    clips: SoundClip[];
+    /** Per-play randomisation. */
+    variation?: SoundVariation;
+    /** Static designer trim applied to every play, in dB. */
+    gainDb?: number;
+    /** Stream (music/ambience) instead of decoding fully into memory (sfx). */
+    stream?: boolean;
+    loudness?: SoundLoudness;
+    license?: SoundLicense;
+    /** Downsampled |amplitude| in 0..1 for instant waveform rendering in the gallery. */
+    peaks?: number[];
+    /** Epoch ms of last save. */
+    updatedAt?: number;
+}
+/**
+ * A folder in the authoring hierarchy — a first-class entity (stable id + parent), NOT a derived
+ * path. Sounds reference it by {@link SoundAsset.folderId}. Renaming touches one record; moving a
+ * subtree reparents one record. Folders are authoring-only and never published to games.
+ */
+export interface SoundFolder {
+    id: string;
+    name: string;
+    /** Parent folder id, or null for a root folder. */
+    parentId: string | null;
+}
+/** The published, game-facing library snapshot (R2 `sounds/library.json`). */
+export interface SoundLibraryManifest {
+    /** Epoch ms of the last Publish, or null if never published. */
+    generatedAt: number | null;
+    /** Bumped on each Publish — lets a SoundBank cache-bust. */
+    version?: number;
+    sounds: SoundAsset[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sounds/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sounds/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,OAAO,GAAG,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC;AAC1E,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAAgD,CAAC;AAEtG,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,oGAAoG;AACpG,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qGAAqG;AACrG,MAAM,WAAW,UAAU;IACzB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;IACxB,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oFAAoF;IACpF,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB"}

package/dist/sounds/types.js

@@ -0,0 +1,8 @@
+/**
+ * Sound-library data types — owned by the SDK (like world/character types), so the platform's
+ * `SoundService`/gallery and every game's `SoundBank` share ONE shape. A "sound" is modelled as an
+ * **event** (a stable key + a pool of clips + behaviour), not a bare file — so variation and the
+ * hardware-driven adaptive layer are additive later with no schema migration.
+ */
+export const SOUND_CATEGORIES = ["sfx", "music", "ambience", "ui", "voice"];
+//# sourceMappingURL=types.js.map

package/dist/sounds/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sounds/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC"}

package/dist/ui/README.md

@@ -44,8 +44,10 @@ feed its `{x, y, onScreen}` into `setScreenPos`/`setVisible` — don't compute p
 | `mountActionDiamond(host, opts)` | fn | The full 4-button A/B/Y/Z diamond with per-button labels/actions. |
 | `mountLabeledDiamond(host, opts)` | fn | A diamond floating over a point with labels around it (the "actions on offer" affordance). |
 | `mountDialogueCard(host, opts)` | fn | An NPC dialogue box: speaker name, typed-out line, advance cue (A). |
+| `mountSubtitle(host, opts)` | fn | A boxless, self-dismissing caption (the voice-over "auto" look): big centred line + speaker name, no frame. `anchor`/`offset` place it; `showName` toggles the name. |
 | `mountChoiceCard(host, opts)` | fn | A player choice menu: prompt + highlighted option list (▲▼ move, A confirm). |
 | `mountRarityCard(host, opts)` / `buildRarityCard(opts)` | fn | A generic rarity-tinted item/creature card. |
+| `createPowerRace(opts)` | fn | A timed **power-vs-deadline race** overlay — the "push NOW or lose it" beat. A charge bar (∫power dt) races a clock; first to 100% wins. `start()` then `setPower(w)`+`tick(dt)` per frame; `won`/`lost` via `onResolve`. Recolour with `theme`, relabel with `text`. |
 | `injectCss()` | fn | Force the `.rydr-ui-*` CSS into `<head>` early (components call it for you). |
 
 Types: `ButtonLetter` (`"A"\|"B"\|"Y"\|"Z"`), `DirButton`, `KeycapVariant` (`"full"\|"solo"`),

package/dist/ui/index.d.ts

@@ -2,7 +2,7 @@
  * `@rydr/game-sdk/ui` — the reusable controller-button UI: a DOM/CSS keycap of the A/B/Y/Z face
  * buttons and the UP/DOWN/LEFT/RIGHT d-pad, plus higher-level pieces built from it (a dark glass card
  * with a content slot, an action card, the full A/B/Y/Z move diamond, an NPC dialogue card, a player
- * choice menu, a labeled diamond, and a generic rarity card). Games use it to show "which button to
+ * choice menu, a labeled diamond, a solo labeled diamond, and a generic rarity card). Games use it to show "which button to
  * press" in one consistent visual language across the library.
  *
  * Self-contained, like `@rydr/game-sdk/three`'s perf-overlay: it injects its own scoped `.rydr-ui-*`
@@ -26,7 +26,10 @@ export * from "./card.js";
 export * from "./action-card.js";
 export * from "./action-diamond.js";
 export * from "./dialogue-card.js";
+export * from "./subtitle.js";
 export * from "./choice-card.js";
 export * from "./labeled-diamond.js";
+export * from "./solo-labeled-diamond.js";
 export * from "./rarity-card.js";
+export * from "./power-race.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;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"}

package/dist/ui/index.js

@@ -2,7 +2,7 @@
  * `@rydr/game-sdk/ui` — the reusable controller-button UI: a DOM/CSS keycap of the A/B/Y/Z face
  * buttons and the UP/DOWN/LEFT/RIGHT d-pad, plus higher-level pieces built from it (a dark glass card
  * with a content slot, an action card, the full A/B/Y/Z move diamond, an NPC dialogue card, a player
- * choice menu, a labeled diamond, and a generic rarity card). Games use it to show "which button to
+ * choice menu, a labeled diamond, a solo labeled diamond, and a generic rarity card). Games use it to show "which button to
  * press" in one consistent visual language across the library.
  *
  * Self-contained, like `@rydr/game-sdk/three`'s perf-overlay: it injects its own scoped `.rydr-ui-*`
@@ -26,7 +26,10 @@ export * from "./card.js";
 export * from "./action-card.js";
 export * from "./action-diamond.js";
 export * from "./dialogue-card.js";
+export * from "./subtitle.js";
 export * from "./choice-card.js";
 export * from "./labeled-diamond.js";
+export * from "./solo-labeled-diamond.js";
 export * from "./rarity-card.js";
+export * from "./power-race.js";
 //# sourceMappingURL=index.js.map

package/dist/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;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"}

package/dist/ui/power-race.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `createPowerRace` — a timed power-race HUD: two bars race each other.
+ *
+ *   · deadline bar — fills at a constant rate over `durationS` (the clock closing in).
+ *   · charge bar   — fills from accumulated effort (∫ power dt) toward
+ *                    `requiredJoules = targetFtpPct × ftp × durationS`.
+ *
+ * If the charge bar reaches 100% before the deadline bar does, the rider **wins**; otherwise the
+ * clock **wins** (the rider loses). Pacing is free — only total work matters. This is the canonical
+ * "push NOW or lose it" beat: a surge you must out-pedal before a timer runs out. It began as
+ * Tower-Defense's nuke-intercept mini-game and VIVAX's Vivapierre charge; both are the same widget.
+ *
+ * Pass `mode: "charge"` for the **no-rival** variant — a solo "charge this up" with no deadline bar and
+ * no clock that can beat you (it only resolves `won`, on fill). Same visuals, calmer framing.
+ *
+ * Self-contained DOM/CSS (no three.js), like the rest of `@rydr/game-sdk/ui`: it injects its own
+ * scoped `.rpr-*` stylesheet once into `<head>`. It takes **power values**, not a `session` — the
+ * game owns its loop and feeds watts in. FTP-relative by construction (`ftp` sets the bar to clear),
+ * so a 150 W and a 350 W rider face the same challenge — never hard-code a raw-watt threshold.
+ *
+ * ── Sizing contract (same as the rest of the kit) ──────────────────────────────────────────────
+ * Tuned for a trainer screen viewed from a few feet away while pedaling. Don't restyle the `.rpr-*`
+ * type sizes / dimensions or wrap it in `transform: scale()`. Recolour it with the `theme` option and
+ * relabel it with `text` — those are the customization surface; the layout is fixed.
+ * ────────────────────────────────────────────────────────────────────────────────────────────────
+ *
+ * Driving it: `start()`, then pump `setPower(w)` + `tick(dt)` every frame. The HUD self-resolves to
+ * `won` / `lost` when either bar crosses 100%; poll `getPhase()` or pass `onResolve`. Drive external
+ * VFX (a glow, a light) off `getProgress().charge`.
+ */
+/** Layout of the two bars. Both drive the same class hooks. */
+export type PowerRaceVariant = "twin-stacked" | "twin-towers";
+/** Where the live precision % sits (or `null` to hide it). */
+export type PowerRaceScoreVariant = "tip" | "impact" | "above" | "infill";
+/** The internal phase machine; `won`/`lost` are the resolved outcomes. */
+export type PowerRacePhase = "idle" | "priming-warning" | "priming-prompt" | "priming-bars" | "racing" | "won" | "lost";
+/** The two terminal outcomes. */
+export type PowerRaceOutcome = "won" | "lost";
+/** Total intro duration in seconds. */
+export declare const INTRO_TOTAL_S: number;
+/**
+ * The six palette colours, driven into the component as CSS custom properties. Each bar is a
+ * `deep → bright` gradient; the win state recolours the charge bar green. The default is the original
+ * "alert" skin (red clock, cyan effort, green win); pass a `theme` (any subset) to recolour.
+ */
+export interface PowerRaceTheme {
+    /** Deadline (clock) bar bright end + all its labels/glows. */
+    deadline: string;
+    /** Deadline bar gradient dark end. */
+    deadlineDeep: string;
+    /** Charge (effort) bar bright end + its label/glow. */
+    charge: string;
+    /** Charge bar gradient dark end. */
+    chargeDeep: string;
+    /** Win state bright end (the charge bar on a win + the "won" stamp). */
+    win: string;
+    /** Win state gradient dark end. */
+    winDeep: string;
+}
+/** The built-in "alert" skin — the proven Tower-Defense look. Default when no `theme` is passed. */
+export declare const DEFAULT_POWER_RACE_THEME: Required<PowerRaceTheme>;
+/** Every user-facing string. Defaults reproduce the original alert copy; override per game. */
+export interface PowerRaceText {
+    heading?: string;
+    prompt?: string;
+    deadlineLabel?: string;
+    chargeLabel?: string;
+    win?: string;
+    lose?: string;
+}
+export interface PowerRaceOpts {
+    /** Rider FTP — sets the effort target (`requiredJoules`). Always FTP-relative; never a raw threshold. */
+    ftp?: number;
+    /** How long the deadline bar takes to fill (seconds). Default 5. */
+    durationS?: number;
+    /** Effort target as a fraction of FTP: `requiredJoules = targetFtpPct × ftp × durationS`. Default 1.1. */
+    targetFtpPct?: number;
+    /**
+     * `"race"` (default) — a rival **deadline** bar races you; you lose if it fills first (the "push NOW
+     * or lose it" beat). `"charge"` — **no rival**: you just fill the charge bar (a solo "charge this
+     * up"). In charge mode the deadline bar is hidden, the alarm framing is calmed (no red klaxon
+     * strobe), and the widget only ever resolves `won` on its own (charge → 100%). There's no built-in
+     * clock, so a rider can charge at their own pace; a game that wants a *failure* (e.g. the rider was
+     * downed, or a scene timeout) drives it with `showResolution("lost")`. `durationS` still sets how
+     * much work fills the bar (`requiredJoules`); it just isn't a losing clock. Relabel the alarm copy
+     * for a charge with `text` (e.g. `heading: "CHARGING"`, `prompt: "PUSH TO CHARGE"`).
+     */
+    mode?: "race" | "charge";
+    /** Bar layout. Default `twin-stacked`. */
+    variant?: PowerRaceVariant;
+    /** Live precision-% placement, or `null`/omitted to hide it. */
+    scoreVariant?: PowerRaceScoreVariant | null;
+    /** All user-facing strings (any subset). */
+    text?: PowerRaceText;
+    /** Palette override (any subset). Defaults to {@link DEFAULT_POWER_RACE_THEME}. */
+    theme?: Partial<PowerRaceTheme>;
+    /** Called once when the race resolves. Same signal as polling `getPhase()`. */
+    onResolve?: (outcome: PowerRaceOutcome) => void;
+}
+export interface PowerRaceHud {
+    /** The overlay root — append it to your HUD layer. */
+    element: HTMLElement;
+    /** Begin the priming intro, then the race. */
+    start(): void;
+    /** Feed the current power (watts) each frame. */
+    setPower(w: number): void;
+    /** Current phase; `won`/`lost` once resolved. */
+    getPhase(): PowerRacePhase;
+    /** Live bar fills 0..1 — drive external VFX (e.g. a glow) off `charge`. */
+    getProgress(): {
+        deadline: number;
+        charge: number;
+    };
+    /** Advance one frame; returns the (possibly new) phase. Self-resolves + fires `onResolve`. */
+    tick(dt: number): PowerRacePhase;
+    /** Force a resolution (e.g. an externally decided outcome), optionally auto-hiding after `durationS`. */
+    showResolution(outcome: PowerRaceOutcome, opts?: {
+        durationS?: number;
+    }): void;
+    /** Back to idle (hidden, bars cleared) for reuse. */
+    reset(): void;
+    dispose(): void;
+}
+export declare function createPowerRace(opts?: PowerRaceOpts): PowerRaceHud;
+//# sourceMappingURL=power-race.d.ts.map

package/dist/ui/power-race.d.ts.map

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