@remix-gg/three 0.1.1

package/dist/juice.js

@@ -0,0 +1,237 @@
+/**
+ * The curated set. Linear motion everywhere is the tell of an untweened game —
+ * real objects accelerate — but a menagerie of forty easings is choice with no
+ * information. These seven cover the moves portrait games make: `quadOut` for
+ * almost everything that moves on screen, `backOut` for pops that overshoot,
+ * `elasticOut` for the rare springy emphasis, the rest for symmetry and ramps.
+ */
+export const easings = {
+    linear: (t) => t,
+    quadIn: (t) => t * t,
+    quadOut: (t) => t * (2 - t),
+    quadInOut: (t) => (t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t)),
+    cubicOut: (t) => 1 + (t - 1) ** 3,
+    backOut: (t) => 1 + 2.70158 * (t - 1) ** 3 + 1.70158 * (t - 1) ** 2,
+    elasticOut: (t) => t === 0 || t === 1 ? t : 2 ** (-10 * t) * Math.sin((t * 10 - 0.75) * ((2 * Math.PI) / 3)) + 1,
+};
+/** Absorbs accumulated step error in "has this timer elapsed" comparisons. */
+const EPSILON = 1e-9;
+const resolveEasing = (easing) => {
+    if (easing === undefined)
+        return easings.quadOut;
+    if (typeof easing === 'function')
+        return easing;
+    const found = easings[easing];
+    if (!found)
+        throw new Error(`unknown easing '${String(easing)}'`);
+    return found;
+};
+/**
+ * A tween runner stepped by the game's own fixed timestep.
+ *
+ * Stepped, not clocked: it advances only when `update(step)` is called, so
+ * tweens pause with the simulation (including during hit-stop, which is the
+ * behaviour that reads as impact), run identically on 60 Hz and 120 Hz
+ * displays, and are deterministic under test.
+ *
+ * Create it once at module scope, call `tweens.update(step)` first thing in
+ * the game's update, and `tweens.cancelAll()` from the run reset — a tween
+ * from the previous run landing on a freshly reset object is a classic ghost.
+ */
+export function createTweens() {
+    let live = [];
+    return {
+        to(target, to, options) {
+            if (!(options.duration >= 0)) {
+                throw new Error(`tween duration must be >= 0, got ${options.duration}`);
+            }
+            const record = target;
+            const keys = Object.keys(to);
+            const tween = {
+                target: record,
+                keys,
+                from: keys.map((key) => {
+                    const value = record[key];
+                    if (typeof value !== 'number') {
+                        throw new Error(`tween target property '${key}' is not a number`);
+                    }
+                    return value;
+                }),
+                to: keys.map((key) => to[key]),
+                easing: resolveEasing(options.easing),
+                duration: options.duration,
+                yoyo: options.yoyo ?? false,
+                elapsed: 0,
+                cancelled: false,
+                onUpdate: options.onUpdate,
+                onComplete: options.onComplete,
+            };
+            live.push(tween);
+            return {
+                cancel() {
+                    tween.cancelled = true;
+                },
+                get done() {
+                    return tween.cancelled || tween.elapsed + EPSILON >= tween.duration * (tween.yoyo ? 2 : 1);
+                },
+            };
+        },
+        update(step) {
+            if (live.length === 0)
+                return;
+            const finished = [];
+            for (const tween of live) {
+                if (tween.cancelled)
+                    continue;
+                tween.elapsed += step;
+                const total = tween.duration * (tween.yoyo ? 2 : 1);
+                // The epsilon absorbs accumulated float error: thirty 1/60 steps sum
+                // to a hair under 0.5, and without it every tween runs one extra frame.
+                const landed = tween.elapsed + EPSILON >= total;
+                if (landed) {
+                    // Snap to the exact destination rather than trusting easing(1) —
+                    // curves like backOut miss their endpoint by float noise, and a
+                    // scale meant to return to 1 must be 1, not 1 ± 2e-16, forever.
+                    const finals = tween.yoyo ? tween.from : tween.to;
+                    for (let i = 0; i < tween.keys.length; i++) {
+                        tween.target[tween.keys[i]] = finals[i];
+                    }
+                }
+                else {
+                    const t = tween.elapsed / total;
+                    // The yoyo leg mirrors progress; easing applies per leg so the
+                    // return trip decelerates the same way the outbound one did.
+                    const leg = tween.yoyo ? 1 - Math.abs(1 - 2 * t) : t;
+                    const eased = tween.easing(leg);
+                    for (let i = 0; i < tween.keys.length; i++) {
+                        const from = tween.from[i];
+                        tween.target[tween.keys[i]] = from + (tween.to[i] - from) * eased;
+                    }
+                }
+                tween.onUpdate?.();
+                if (landed)
+                    finished.push(tween);
+            }
+            if (finished.length > 0 || live.some((tween) => tween.cancelled)) {
+                live = live.filter((tween) => !tween.cancelled && !finished.includes(tween));
+                // Callbacks run after the list is settled, so an onComplete that starts
+                // the next tween (a squash chaining into a stretch) is not swept away.
+                for (const tween of finished)
+                    tween.onComplete?.();
+            }
+        },
+        cancelAll() {
+            for (const tween of live)
+                tween.cancelled = true;
+            live = [];
+        },
+        get active() {
+            return live.filter((tween) => !tween.cancelled).length;
+        },
+    };
+}
+/**
+ * Wraps any camera rig with trauma-based screen shake.
+ *
+ * A decorator, because ownership is the entire problem: rigs own the camera
+ * transform, and `followRig` rewrites it every frame while `portraitRig` never
+ * touches it after boot. Adding an offset directly therefore either vanishes
+ * next frame or accumulates forever, depending on which rig the game picked.
+ * The wrapper removes last frame's offset, lets the inner rig do its work,
+ * then applies a fresh one — correct against both behaviours.
+ *
+ * Trauma-squared with linear decay (Squirrel Eiserloh's model): shake feels
+ * proportional to events this way, and it composes — two quick hits raise
+ * trauma additively instead of restarting a fixed animation.
+ *
+ * Shake runs on render time (`rig.update(dt)`), so it keeps moving during
+ * hit-stop and after `gameOver` — a dead-still camera over a game-over sheet
+ * reads as a hang, and shake-through-freeze is the classic impact combo.
+ *
+ *     const rig = shakeRig(portraitRig())
+ *     await createGame({ camera: rig, ... })
+ *     rig.shake(0.4)
+ */
+export function shakeRig(rig, options = {}) {
+    const maxOffset = options.maxOffset ?? 0.35;
+    const maxRoll = options.maxRoll ?? 0.04;
+    const decay = options.decay ?? 1.5;
+    const rng = options.rng ?? Math.random;
+    let trauma = 0;
+    let appliedX = 0;
+    let appliedY = 0;
+    let appliedRoll = 0;
+    // Inverse in reverse order: the roll changed the local axes the offsets
+    // were applied along, so it unwinds first or the translation comes back
+    // along the wrong basis and the camera drifts a little every frame.
+    const remove = () => {
+        rig.camera.rotateZ(-appliedRoll);
+        rig.camera.translateY(-appliedY);
+        rig.camera.translateX(-appliedX);
+        appliedX = 0;
+        appliedY = 0;
+        appliedRoll = 0;
+    };
+    return {
+        get camera() {
+            return rig.camera;
+        },
+        resize(viewport) {
+            rig.resize(viewport);
+        },
+        update(dt) {
+            remove();
+            rig.update(dt);
+            trauma = Math.max(trauma - decay * dt, 0);
+            const shake = trauma * trauma;
+            if (shake > 0) {
+                appliedX = maxOffset * shake * (rng() * 2 - 1);
+                appliedY = maxOffset * shake * (rng() * 2 - 1);
+                appliedRoll = maxRoll * shake * (rng() * 2 - 1);
+                rig.camera.translateX(appliedX);
+                rig.camera.translateY(appliedY);
+                rig.camera.rotateZ(appliedRoll);
+            }
+        },
+        shake(amount) {
+            trauma = Math.min(trauma + Math.max(amount, 0), 1);
+        },
+        get trauma() {
+            return trauma;
+        },
+    };
+}
+/**
+ * Hit-stop: the few-frame freeze that sells an impact.
+ *
+ * It cannot be a sleep and cannot skip rendering — the loop keeps drawing the
+ * frozen state, which is exactly the effect. What stops is simulation, and the
+ * game owns its update, so this is a countdown the game gates on rather than
+ * something the SDK can impose.
+ *
+ * Keep it short and rare: 0.05–0.12s, on the few biggest moments (a death, a
+ * heavy hit). On every minor event it stops reading as impact and starts
+ * reading as jank. Screen shake keeps moving through it (see `shakeRig`) —
+ * freeze-plus-shake is the combination that reads as force.
+ */
+export function createHitStop() {
+    let remaining = 0;
+    return {
+        trigger(seconds) {
+            remaining = Math.max(remaining, seconds);
+        },
+        frozen(step) {
+            // The epsilon keeps three 1/60 steps from leaving 5e-18s of freeze that
+            // buys a whole extra frozen frame.
+            if (remaining <= EPSILON) {
+                remaining = 0;
+                return false;
+            }
+            remaining -= step;
+            return true;
+        },
+        get active() {
+            return remaining > EPSILON;
+        },
+    };
+}

package/dist/loop.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure fixed-timestep accumulator. Extracted from the render loop so the timing
+ * rules are unit-testable with zero DOM and zero WebGL.
+ */
+/**
+ * A frame gap longer than this is a stall, not gameplay: a backgrounded tab, a
+ * GC pause, or a paused debugger. Clamping it is what stops the game from
+ * burst-simulating minutes of physics in a single frame when the player comes
+ * back.
+ */
+export declare const MAX_FRAME_DELTA = 0.25;
+export type StepResult = {
+    /** How many fixed `update(step)` calls this frame owes. */
+    steps: number;
+    /** Sub-step remainder in 0..1, for interpolating the render between states. */
+    alpha: number;
+    /** Carry-over to feed into the next call. */
+    accumulator: number;
+};
+/**
+ * @param accumulator seconds carried over from the previous frame
+ * @param dt seconds of wall clock since the previous frame
+ * @param step fixed simulation step in seconds (1/60)
+ * @param maxSteps hard ceiling on steps per frame — the spiral-of-death guard
+ */
+export declare function stepClock(accumulator: number, dt: number, step: number, maxSteps: number): StepResult;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC,MAAM,MAAM,UAAU,GAAG;IACvB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IACb,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAA;IACb,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,UAAU,CAcZ"}

package/dist/loop.js

@@ -0,0 +1,30 @@
+/**
+ * Pure fixed-timestep accumulator. Extracted from the render loop so the timing
+ * rules are unit-testable with zero DOM and zero WebGL.
+ */
+/**
+ * A frame gap longer than this is a stall, not gameplay: a backgrounded tab, a
+ * GC pause, or a paused debugger. Clamping it is what stops the game from
+ * burst-simulating minutes of physics in a single frame when the player comes
+ * back.
+ */
+export const MAX_FRAME_DELTA = 0.25;
+/**
+ * @param accumulator seconds carried over from the previous frame
+ * @param dt seconds of wall clock since the previous frame
+ * @param step fixed simulation step in seconds (1/60)
+ * @param maxSteps hard ceiling on steps per frame — the spiral-of-death guard
+ */
+export function stepClock(accumulator, dt, step, maxSteps) {
+    if (!(step > 0))
+        throw new Error(`stepClock: step must be > 0, got ${step}`);
+    const total = accumulator + Math.min(Math.max(dt, 0), MAX_FRAME_DELTA);
+    const steps = Math.min(Math.floor(total / step), Math.max(0, Math.floor(maxSteps)));
+    // `total % step` serves both cases. In the normal case it equals
+    // `total - steps * step`. When we hit `maxSteps` it additionally DROPS the
+    // backlog we refused to simulate — keeping it would guarantee we hit the cap
+    // again next frame and never catch up (the spiral of death), while the
+    // remainder preserves sub-step phase so motion stays smooth.
+    const remainder = total % step;
+    return { steps, alpha: remainder / step, accumulator: remainder };
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,50 @@
+import { type FarcadeSDKGlobal, type GameInfo, type GameState, type HapticFeedbackType, type Player, type SafeAreaInset, type ShopItem, type ViewContext } from './sdk-contract.js';
+export type Platform = {
+    readonly info: GameInfo | null;
+    readonly player: Player | null;
+    readonly players: readonly Player[];
+    readonly viewContext: ViewContext;
+    readonly safeArea: SafeAreaInset;
+    readonly state: GameState | null;
+    readonly shopItems: readonly ShopItem[];
+    /** True once `gameOver` has been sent for the current run. */
+    readonly isOver: boolean;
+    ready(): Promise<GameInfo>;
+    gameOver(score: number): void;
+    /** Clears the one-`game_over`-per-run latch. Called by `game.restart()`. */
+    rearm(): void;
+    saveState(state: GameState): void;
+    onPlayAgain(cb: () => void): () => void;
+    onToggleMute(cb: (muted: boolean) => void): () => void;
+    onGameInfo(cb: (info: GameInfo) => void): () => void;
+    haptic(type?: HapticFeedbackType): void;
+    hasItem(slug: string): boolean;
+    itemCount(slug: string): number;
+    purchase(slug: string): Promise<{
+        success: boolean;
+        item?: string;
+    }>;
+    reportError(error: unknown): void;
+};
+/**
+ * Resolves `window.FarcadeSDK`, rAF-polling until it appears.
+ *
+ * The poll is not paranoia: remix-dev's dev-init installs its SDK mock
+ * asynchronously, so the global is genuinely absent at module-eval time in the
+ * dev dashboard. Resolves `null` past the deadline rather than rejecting — a
+ * game opened as a bare file has no host and must still boot.
+ */
+export declare function awaitSdk(timeoutMs?: number): Promise<FarcadeSDKGlobal | null>;
+/**
+ * Typed wrapper over `window.FarcadeSDK`.
+ *
+ * It owns the two things every game gets wrong on its own: exactly one
+ * `game_over` per run, and the fact that `game_info` (and therefore
+ * `contentSafeAreaInset`) arrives *after* the first frames.
+ *
+ * The wrapper registers exactly one callback per SDK event and fans out to its
+ * own listener sets, because the SDK's `onPlayAgain`/`onToggleMute` helpers wrap
+ * the callback in a closure and so cannot be unsubscribed.
+ */
+export declare function createPlatform(sdk: FarcadeSDKGlobal | null): Platform;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/platform/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,kBAAkB,EACvB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAA;AAE1B,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAA;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,4EAA4E;IAC5E,KAAK,IAAI,IAAI,CAAA;IACb,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IACjC,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IACvC,YAAY,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACtD,UAAU,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACpD,MAAM,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpE,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CAClC,CAAA;AAaD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAc3E;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,QAAQ,CAsHrE"}

package/dist/platform/index.js

@@ -0,0 +1,177 @@
+import { ZERO_SAFE_AREA_INSET, } from './sdk-contract.js';
+const STANDALONE_PLAYER = { id: 'local', name: 'Player', purchasedItems: [] };
+const STANDALONE_INFO = {
+    players: [STANDALONE_PLAYER],
+    player: STANDALONE_PLAYER,
+    shopItems: [],
+    viewContext: 'full_screen',
+    contentSafeAreaInset: ZERO_SAFE_AREA_INSET,
+    initialGameState: null,
+};
+/**
+ * Resolves `window.FarcadeSDK`, rAF-polling until it appears.
+ *
+ * The poll is not paranoia: remix-dev's dev-init installs its SDK mock
+ * asynchronously, so the global is genuinely absent at module-eval time in the
+ * dev dashboard. Resolves `null` past the deadline rather than rejecting — a
+ * game opened as a bare file has no host and must still boot.
+ */
+export function awaitSdk(timeoutMs = 2000) {
+    const global = globalThis;
+    if (global.FarcadeSDK)
+        return Promise.resolve(global.FarcadeSDK);
+    if (typeof requestAnimationFrame !== 'function')
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        const deadline = performance.now() + timeoutMs;
+        const poll = () => {
+            if (global.FarcadeSDK)
+                return resolve(global.FarcadeSDK);
+            if (performance.now() >= deadline)
+                return resolve(null);
+            requestAnimationFrame(poll);
+        };
+        requestAnimationFrame(poll);
+    });
+}
+function subscribe(set, cb) {
+    set.add(cb);
+    return () => {
+        set.delete(cb);
+    };
+}
+/**
+ * Typed wrapper over `window.FarcadeSDK`.
+ *
+ * It owns the two things every game gets wrong on its own: exactly one
+ * `game_over` per run, and the fact that `game_info` (and therefore
+ * `contentSafeAreaInset`) arrives *after* the first frames.
+ *
+ * The wrapper registers exactly one callback per SDK event and fans out to its
+ * own listener sets, because the SDK's `onPlayAgain`/`onToggleMute` helpers wrap
+ * the callback in a closure and so cannot be unsubscribed.
+ */
+export function createPlatform(sdk) {
+    const listeners = { playAgain: new Set(), toggleMute: new Set(), gameInfo: new Set() };
+    let info = null;
+    let state = null;
+    let over = false;
+    if (sdk) {
+        const handlePlayAgain = () => {
+            for (const cb of [...listeners.playAgain])
+                cb();
+        };
+        const handleToggleMute = (data) => {
+            for (const cb of [...listeners.toggleMute])
+                cb(data.isMuted);
+        };
+        const handleGameInfo = (next) => {
+            info = next;
+            if (next.initialGameState)
+                state = next.initialGameState.gameState;
+            for (const cb of [...listeners.gameInfo])
+                cb(next);
+        };
+        const handleGameStateUpdated = (data) => {
+            state = data ? data.gameState : null;
+        };
+        // remix-dev 1.8.1 implements the generic event API but predates these
+        // named helpers. Prefer the production helpers and fall back without making
+        // a freshly scaffolded game crash before its first frame.
+        if (typeof sdk.onPlayAgain === 'function')
+            sdk.onPlayAgain(handlePlayAgain);
+        else
+            sdk.on?.('play_again', handlePlayAgain);
+        if (typeof sdk.onToggleMute === 'function')
+            sdk.onToggleMute(handleToggleMute);
+        else
+            sdk.on?.('toggle_mute', handleToggleMute);
+        if (typeof sdk.onGameInfo === 'function')
+            sdk.onGameInfo(handleGameInfo);
+        else
+            sdk.on?.('game_info', handleGameInfo);
+        if (typeof sdk.onGameStateUpdated === 'function')
+            sdk.onGameStateUpdated(handleGameStateUpdated);
+        else
+            sdk.on?.('game_state_updated', handleGameStateUpdated);
+    }
+    const purchasedItems = () => info?.player.purchasedItems ?? [];
+    return {
+        get info() {
+            return info;
+        },
+        get player() {
+            return info?.player ?? null;
+        },
+        get players() {
+            return info?.players ?? [];
+        },
+        get viewContext() {
+            return info?.viewContext ?? 'full_screen';
+        },
+        get safeArea() {
+            return info?.contentSafeAreaInset ?? ZERO_SAFE_AREA_INSET;
+        },
+        get state() {
+            return state;
+        },
+        get shopItems() {
+            return info?.shopItems ?? [];
+        },
+        get isOver() {
+            return over;
+        },
+        async ready() {
+            if (!sdk) {
+                info = STANDALONE_INFO;
+                return STANDALONE_INFO;
+            }
+            const resolved = await sdk.ready();
+            info = resolved;
+            if (!state && resolved.initialGameState)
+                state = resolved.initialGameState.gameState;
+            return resolved;
+        },
+        gameOver(score) {
+            // Idempotent per run. The host scores the FIRST game_over it sees, so a
+            // second one from a death animation's callback would silently overwrite a
+            // real score with a stale one.
+            if (over)
+                return;
+            over = true;
+            sdk?.singlePlayer.actions.gameOver({ score });
+        },
+        rearm() {
+            over = false;
+        },
+        saveState(next) {
+            state = next;
+            sdk?.singlePlayer.actions.saveGameState({ gameState: next });
+        },
+        onPlayAgain: (cb) => subscribe(listeners.playAgain, cb),
+        onToggleMute: (cb) => subscribe(listeners.toggleMute, cb),
+        onGameInfo: (cb) => subscribe(listeners.gameInfo, cb),
+        haptic(type) {
+            const actions = sdk?.singlePlayer.actions;
+            if (actions?.hapticFeedback)
+                actions.hapticFeedback(type);
+            else
+                sdk?.hapticFeedback?.(type);
+        },
+        hasItem: (slug) => purchasedItems().includes(slug),
+        itemCount: (slug) => purchasedItems().filter((item) => item === slug).length,
+        async purchase(slug) {
+            if (!sdk)
+                return { success: false };
+            return sdk.purchase({ item: slug });
+        },
+        reportError(error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            const actions = sdk?.singlePlayer.actions;
+            if (actions?.reportError)
+                actions.reportError({ message: err.message, error: err });
+            else
+                sdk?.reportError?.({ message: err.message, error: err });
+        },
+    };
+}

package/dist/platform/sdk-contract.d.ts

@@ -0,0 +1,113 @@
+/**
+ * VENDORED copy of the public type surface of `@remix-gg/sdk`
+ * (`packages/game-sdk/src/index.ts`). Types only — no logic, no runtime import.
+ *
+ * Two reasons this is a copy rather than a dependency:
+ *
+ * 1. `apps/web/lib/format-game.ts` unconditionally injects a
+ *    `<script src=".../@remix-gg/sdk@x/dist/index.min.js">` into every published
+ *    game. A bundled second copy would run `RemixSDK`'s constructor twice — two
+ *    `ready` postMessages and two listener sets — and the host handshake and the
+ *    launch gate both key off exactly one.
+ * 2. Repo rule: public packages must not publish `workspace:` dependencies.
+ *
+ * Keep in sync by hand when `packages/game-sdk/src/index.ts` changes. The
+ * runtime we talk to is `window.FarcadeSDK`, so only the shapes we actually
+ * consume live here.
+ */
+export type ViewContext = 'feed' | 'full_screen' | 'challenge' | 'tournament';
+export type SafeAreaInset = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export declare const ZERO_SAFE_AREA_INSET: SafeAreaInset;
+export type GameState = Record<string, unknown>;
+export type Player = {
+    id: string;
+    name: string;
+    purchasedItems: string[];
+    imageUrl?: string;
+};
+export type InventoryItem = {
+    slug: string;
+    quantity: number;
+};
+export type ShopItem = {
+    slug: string;
+    name: string;
+    itemType?: string;
+    bitsCost?: number | null;
+    description?: string | null;
+    iconUrl?: string | null;
+    tier?: number | null;
+};
+export type GameInfo = {
+    players: Player[];
+    player: Player;
+    shopItems?: ShopItem[];
+    viewContext: ViewContext;
+    contentSafeAreaInset: SafeAreaInset;
+    initialGameState: {
+        id: string;
+        gameState: GameState;
+    } | null;
+};
+export type HapticFeedbackType = 'light' | 'medium' | 'hard' | 'success' | 'error';
+export type ToggleMuteData = {
+    isMuted: boolean;
+};
+export type GameStateUpdatedData = {
+    id: string;
+    gameState: GameState;
+} | null;
+export type PurchaseCompleteData = {
+    success: boolean;
+    item?: string;
+};
+export type GameErrorData = {
+    message: string;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+    error?: Error;
+};
+export type FarcadeSDKEventMap = {
+    play_again: Record<string, never>;
+    toggle_mute: ToggleMuteData;
+    game_info: GameInfo;
+    game_state_updated: GameStateUpdatedData;
+};
+/** The subset of `window.FarcadeSDK` this SDK actually calls. */
+export type FarcadeSDKGlobal = {
+    ready: () => Promise<GameInfo>;
+    purchase: (data: {
+        item: string;
+    }) => Promise<PurchaseCompleteData>;
+    reportError?: (data: GameErrorData) => void;
+    hapticFeedback?: (type?: HapticFeedbackType) => void;
+    on?: <Event extends keyof FarcadeSDKEventMap>(event: Event, cb: (data: FarcadeSDKEventMap[Event]) => void) => void;
+    onPlayAgain?: (cb: () => void) => void;
+    onToggleMute?: (cb: (data: ToggleMuteData) => void) => void;
+    onGameInfo?: (cb: (data: GameInfo) => void) => void;
+    onGameStateUpdated?: (cb: (data: GameStateUpdatedData) => void) => void;
+    readonly gameInfo?: GameInfo;
+    readonly gameState?: GameState | null;
+    readonly shopItems: ShopItem[];
+    readonly players?: Player[];
+    readonly player?: Player;
+    singlePlayer: {
+        actions: {
+            gameOver: (data: {
+                score: number;
+            }) => void;
+            saveGameState: (data: {
+                gameState: GameState;
+            }) => void;
+            reportError?: (data: GameErrorData) => void;
+            hapticFeedback?: (type?: HapticFeedbackType) => void;
+        };
+    };
+};
+//# sourceMappingURL=sdk-contract.d.ts.map

package/dist/platform/sdk-contract.d.ts.map

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

package/dist/platform/sdk-contract.js

@@ -0,0 +1,18 @@
+/**
+ * VENDORED copy of the public type surface of `@remix-gg/sdk`
+ * (`packages/game-sdk/src/index.ts`). Types only — no logic, no runtime import.
+ *
+ * Two reasons this is a copy rather than a dependency:
+ *
+ * 1. `apps/web/lib/format-game.ts` unconditionally injects a
+ *    `<script src=".../@remix-gg/sdk@x/dist/index.min.js">` into every published
+ *    game. A bundled second copy would run `RemixSDK`'s constructor twice — two
+ *    `ready` postMessages and two listener sets — and the host handshake and the
+ *    launch gate both key off exactly one.
+ * 2. Repo rule: public packages must not publish `workspace:` dependencies.
+ *
+ * Keep in sync by hand when `packages/game-sdk/src/index.ts` changes. The
+ * runtime we talk to is `window.FarcadeSDK`, so only the shapes we actually
+ * consume live here.
+ */
+export const ZERO_SAFE_AREA_INSET = { top: 0, right: 0, bottom: 0, left: 0 };