@flayerlabs/gamemode-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import type { GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
+import type { BuyFailure, ConnectionState, EconomyBalance, LaunchContext, MarketState, PlayerIdentity, PresenceState, Reaction } from '@flayerlabs/gamemode-spec/live';
+export type { BuyFailure, ConnectionState, EconomyBalance, LaunchContext, MarketPrice, MarketState, MarketTrade, PlayerIdentity, PresenceState, Reaction, } from '@flayerlabs/gamemode-spec/live';
+export { joinRoom, NoWallet } from './live.js';
+export { connectEmbeddedGame, serveEmbeddedGame } from './embed.js';
+export type { ConnectEmbeddedGameOptions, EmbeddedGameConnection, ServeEmbeddedGameOptions, } from './embed.js';
+export { BUSY_LAUNCH, replayMarket } from './replay-market.js';
+export type { MarketFixture, ReplayMarket } from './replay-market.js';
+export type { Authorisation, Host, HostBuyProgress, LiveOptions } from './live.js';
+/**
+ * What a game talks to. Gameplay stays small; reusable platform concerns live in named capabilities.
+ *
+ * A game never sees a socket, a wallet, a chain or a key. Everything it can do is here, which is
+ * why a bug in a game cannot lose anyone money: it has no way to express the transaction that
+ * would.
+ */
+export interface Room<PublicView, PlayerView, Action> {
+    /** Called with the current view immediately, then whenever it changes. Returns an unsubscribe. */
+    subscribe(listener: (snapshot: Snapshot<PublicView, PlayerView>) => void): () => void;
+    /** Propose an action. Points exist only if the rules, running on the server, award them. */
+    send(action: Action): Promise<SendResult>;
+    /**
+     * The only clock a game may trust.
+     *
+     * Corrected against the server, so every player counts down to the same instant regardless of
+     * how wrong their own device's clock is. `Date.now()` in a game is a bug: two players in
+     * different timezones, or one with a drifting clock, see different games.
+     */
+    now(): number;
+    /** Fixed launch facts. Live rooms do not resolve until these have arrived. */
+    readonly launch: Readable<LaunchContext>;
+    readonly connection: Readable<ConnectionState>;
+    readonly economy: Economy;
+    readonly market: Readable<MarketState>;
+    readonly identity: IdentityResolver;
+    readonly presence: Presence;
+    readonly social: Social;
+    dispose(): void;
+}
+/** An observable value whose subscriber always receives the current value immediately. */
+export interface Readable<T> {
+    current(): T;
+    subscribe(listener: (value: T) => void): () => void;
+}
+export interface Snapshot<PublicView, PlayerView> {
+    /** What everyone sees. */
+    publicView: PublicView;
+    /** What this player sees. Null until they have joined. */
+    playerView: PlayerView | null;
+}
+export type SendResult = {
+    accepted: true;
+} | {
+    accepted: false;
+    refuse: string;
+};
+export interface Economy extends Readable<EconomyState> {
+    /** What this player could spend right now, in wei. */
+    available(): bigint;
+    /**
+     * Spend up to `maxSpendWei` on the coin.
+     *
+     * The game does not build this transaction and cannot: the page it is embedded in constructs it
+     * from the server's authorisation and asks the player to approve it.
+     */
+    buy(maxSpendWei: bigint): Promise<BuyResult>;
+}
+export interface EconomyState extends EconomyBalance {
+    buy: BuyProgress | null;
+}
+export type BuyProgress = {
+    state: 'signing';
+    spendWei: bigint;
+} | {
+    state: 'pending';
+    spendWei: bigint;
+    transactionHash?: string;
+} | {
+    state: 'confirmed';
+    spentWei: bigint;
+    transactionHash?: string;
+} | {
+    state: 'failed';
+    reason: BuyFailure;
+};
+export type BuyResult = {
+    bought: true;
+    spentWei: bigint;
+} | {
+    bought: false;
+    reason: BuyFailure;
+};
+/**
+ * Why a buy did not happen, in terms a player can be told about.
+ *
+ * Deliberately a short list of plain outcomes rather than anything from the chain. A game should
+ * never render a revert string or an error code at a player: the client maps each of these to its
+ * own copy, and the copy is free to change without the meaning moving.
+ */
+export interface Social {
+    react(id: string): void;
+    onReaction(listener: (reaction: Reaction) => void): () => void;
+}
+/**
+ * Who is connected. Read-only, because readiness is a game's rule and not the platform's.
+ *
+ * A game that needs a ready-up lobby defines a ready Action, sends it with {@link Room.send}, and
+ * counts it in its own state — where `decide()` can actually see it and act on it.
+ */
+export type Presence = Readable<PresenceState>;
+export interface IdentityResolver {
+    resolve(players: readonly PlayerId[]): Promise<readonly PlayerIdentity[]>;
+}
+/** Trusted, normalized platform data supplied by the embedding integration. */
+export interface ClientPlatform {
+    market?: Readable<MarketState>;
+    identity?: IdentityResolver;
+}
+export interface MockOptions<Config> {
+    config: Config;
+    /** Pins the round so a reload is the same round. Any number. */
+    seed?: number;
+    /** How long until the round opens. Short, because this is for building against. */
+    lobbyMs?: number;
+    roundMs?: number;
+    /** Who you are. A made-up address unless you say otherwise. */
+    player?: PlayerId;
+    /** Points-to-wei, only so the buy button has something to show. */
+    weiPerPoint?: bigint;
+    launch?: LaunchContext;
+    platform?: ClientPlatform;
+    /** The same cosmetic catalogue as live. Omitted disables reactions. */
+    reactionIds?: readonly string[];
+}
+/**
+ * A room with nothing behind it.
+ *
+ * This is what `pnpm dev` runs, and it is not a stand-in: it drives the game's REAL rules module,
+ * the same one the server runs. So a game cannot pass locally and fail live through a difference
+ * in the rules — there is no second implementation to disagree with. What is faked is only the
+ * things a laptop has no way to provide: the network, the wallet and the money.
+ */
+export declare function createMockRoom<Config, State, Event, Action, PublicView, PlayerView>(game: GameModule<Config, State, Event, Action, PublicView, PlayerView>, options: MockOptions<Config>): Room<PublicView, PlayerView, Action>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,16 @@
+import { MockRoom } from './mock.js';
+export { joinRoom, NoWallet } from './live.js';
+export { connectEmbeddedGame, serveEmbeddedGame } from './embed.js';
+export { BUSY_LAUNCH, replayMarket } from './replay-market.js';
+/**
+ * A room with nothing behind it.
+ *
+ * This is what `pnpm dev` runs, and it is not a stand-in: it drives the game's REAL rules module,
+ * the same one the server runs. So a game cannot pass locally and fail live through a difference
+ * in the rules — there is no second implementation to disagree with. What is faked is only the
+ * things a laptop has no way to provide: the network, the wallet and the money.
+ */
+export function createMockRoom(game, options) {
+    return new MockRoom(game, options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAerC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAMpE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA6H/D;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAsE,EACtE,OAA4B;IAE5B,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC"}

package/dist/live.d.ts

@@ -0,0 +1,59 @@
+import type { BuyResult, ClientPlatform, Room } from './index.js';
+import type { SpendAuthorisation } from '@flayerlabs/gamemode-spec/embed';
+import { type LaunchContext, type MarketState } from '@flayerlabs/gamemode-spec/live';
+/**
+ * The page the game is embedded in, as far as the game is concerned.
+ *
+ * This is the whole wallet surface, and it is two verbs rather than a pipe. The game cannot ask
+ * for a transaction to be sent, because there is no way to say it: `buy` names an authorisation
+ * the gate already signed, and the page builds the transaction from that itself.
+ *
+ * The version this replaces forwarded `eth_sendTransaction` with parameters from the frame, which
+ * meant a game could ask for any transaction at all and have it appear in the trusted context of
+ * the page. That is fine for a game you wrote and wrong for one you did not.
+ */
+export interface Host {
+    /**
+     * Which wallet is connected to the page, or null if none is.
+     *
+     * Null is an answer, not a failure: a game can tell a player to connect. The version this
+     * replaces stayed silent instead, so the game waited out an eight-second timeout and then fell
+     * back to whatever extension the browser happened to have — which is how someone ended up signed
+     * in as one wallet while the page showed another.
+     */
+    address(signal?: AbortSignal): Promise<string | null>;
+    /** Ask the player to prove that wallet is theirs. Honour abort when the trusted embed closes. */
+    signIn(message: string, signal?: AbortSignal): Promise<`0x${string}`>;
+    /** Fresh, single-use admission evidence. Honour abort when the trusted embed closes. */
+    sessionEvidence?(signal?: AbortSignal): Promise<unknown>;
+    /** Spend an authorisation the gate issued. The page builds and submits the transaction. */
+    buy(authorisation: Authorisation, progress?: (event: HostBuyProgress) => void, signal?: AbortSignal): Promise<{
+        spentWei: bigint;
+    } | {
+        failed: BuyResult;
+    }>;
+}
+/** The host reports only what it uniquely knows; LiveRoom owns the terminal result. */
+export type HostBuyProgress = {
+    state: 'pending';
+    transactionHash?: string;
+};
+/** Exactly what the gate signed. Everything is a string because bigints do not survive JSON. */
+export type Authorisation = SpendAuthorisation;
+export interface LiveOptions {
+    /** The gate's origin. The one place this game is allowed to talk to. */
+    gateUrl: string;
+    roundId: string;
+    host: Host;
+    /** May be supplied by the parent immediately; a new gate also sends it in its first snapshot. */
+    launch?: LaunchContext;
+    platform?: ClientPlatform;
+}
+export declare function joinRoom<PublicView, PlayerView, Action>(options: LiveOptions): Promise<Room<PublicView, PlayerView, Action>>;
+export declare function marketFrom(input: unknown): MarketState | null;
+export declare function immutableLaunch(launch: LaunchContext): LaunchContext;
+/** No wallet is connected to the page. A game should ask the player to connect one. */
+export declare class NoWallet extends Error {
+    constructor();
+}
+//# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,SAAS,EACT,cAAc,EAGd,IAAI,EAIL,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,WAAW,EAKjB,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,IAAI;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEtD,iGAAiG;IACjG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IACtE,wFAAwF;IACxF,eAAe,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,2FAA2F;IAC3F,GAAG,CACD,aAAa,EAAE,aAAa,EAC5B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,EAC3C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,iGAAiG;IACjG,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAMD,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,EAC3D,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAS/C;AAqbD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAgD7D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAEpE;AAQD,uFAAuF;AACvF,qBAAa,QAAS,SAAQ,KAAK;;CAKlC"}