@flayerlabs/gamemode-client 0.1.0

package/src/embed.ts

@@ -0,0 +1,395 @@
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import {
+  EMBED_CHANNEL,
+  EMBED_PROTOCOL_VERSION,
+  isCanonicalSpendHookData,
+  isPlayerIdentities,
+  isSessionChallenge,
+  parseGameToHostMessage,
+  parseHostToGameMessage,
+  type EmbedFailure,
+  type EmbedRequest,
+  type EmbeddedContext,
+  type GameToHostMessage,
+  type HostToGameMessage,
+} from '@flayerlabs/gamemode-spec/embed';
+import type { MarketState, WireMarketState } from '@flayerlabs/gamemode-spec/live';
+import type { ClientPlatform, IdentityResolver, Readable } from './index.js';
+import { immutableLaunch, marketFrom, type Authorisation, type Host, type HostBuyProgress } from './live.js';
+import { Signal } from './signal.js';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** A room uses far fewer; refusing after the cap keeps lifetime replay memory strictly bounded. */
+const MAX_ACCEPTED_REQUEST_IDS = 1_024;
+
+export interface EmbedEventWindow {
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+}
+
+export interface EmbedTargetWindow {
+  postMessage(message: unknown, targetOrigin: string): void;
+}
+
+export interface EmbeddedGameConnection {
+  context: EmbeddedContext;
+  host: Host;
+  platform: ClientPlatform;
+  dispose(): void;
+}
+
+interface Pending {
+  method: EmbedRequest['method'];
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+  progress?: (event: HostBuyProgress) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface ConnectEmbeddedGameOptions {
+  /** Fixed in trusted game code, never taken from a query string supplied by the parent. */
+  parentOrigin: string;
+  timeoutMs?: number;
+  currentWindow?: EmbedEventWindow;
+  parentWindow?: EmbedTargetWindow;
+}
+
+/** Connect an untrusted game frame to the semantic services of its trusted parent. */
+export function connectEmbeddedGame(options: ConnectEmbeddedGameOptions): Promise<EmbeddedGameConnection> {
+  const current = options.currentWindow ?? window;
+  const parent = options.parentWindow ?? window.parent;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const market = new Signal<MarketState>({ status: 'unavailable', prices: [], trades: [], marketCapUsd: null });
+  const pending = new Map<string, Pending>();
+  let disposed = false;
+  let context: EmbeddedContext | null = null;
+  let resolveContext!: (value: EmbeddedContext) => void;
+  let rejectContext!: (error: Error) => void;
+  const ready = new Promise<EmbeddedContext>((resolve, reject) => {
+    resolveContext = resolve;
+    rejectContext = reject;
+  });
+
+  const post = (message: GameToHostMessage): void => parent.postMessage(message, options.parentOrigin);
+  const request = (value: EmbedRequest, progress?: (event: HostBuyProgress) => void): Promise<unknown> => {
+    if (disposed) return Promise.reject(new Error('the embedded connection is closed'));
+    const id = globalThis.crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error('the trusted parent did not answer in time'));
+      }, timeoutMs);
+      pending.set(id, { method: value.method, resolve, reject, timer, ...(progress ? { progress } : {}) });
+      post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'request', id, request: value });
+    });
+  };
+
+  const onMessage: EventListener = (rawEvent): void => {
+    const event = rawEvent as MessageEvent;
+    if (event.origin !== options.parentOrigin || event.source !== parent) return;
+    const message = parseHostToGameMessage(event.data);
+    if (!message) return;
+    if (message.type === 'context') {
+      if (context === null) {
+        context = Object.freeze({ ...message.context, launch: immutableLaunch(message.context.launch) });
+        resolveContext(context);
+      }
+      return;
+    }
+    if (message.type === 'market') {
+      const parsed = marketFrom(message.market);
+      if (parsed) market.set(parsed);
+      return;
+    }
+    const waiting = pending.get(message.id);
+    if (!waiting) return;
+    if (message.type === 'buy-progress') {
+      waiting.progress?.(
+        message.transactionHash
+          ? { state: 'pending', transactionHash: message.transactionHash }
+          : { state: 'pending' },
+      );
+      return;
+    }
+    pending.delete(message.id);
+    clearTimeout(waiting.timer);
+    if (!message.ok) {
+      if (waiting.method === 'buy') {
+        const reason = message.error === 'no-wallet' ? 'try-again' : message.error;
+        waiting.resolve({ failed: { bought: false, reason } });
+      } else {
+        waiting.reject(new Error(message.error));
+      }
+      return;
+    }
+    waiting.resolve(message.value);
+  };
+  current.addEventListener('message', onMessage);
+
+  const contextTimer = setTimeout(() => {
+    disposed = true;
+    current.removeEventListener('message', onMessage);
+    rejectContext(new Error('the trusted parent did not provide game context'));
+  }, timeoutMs);
+  post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'ready' });
+
+  return ready.then((trustedContext) => {
+    clearTimeout(contextTimer);
+    const host: Host = {
+      address: async () => {
+        const value = await request({ method: 'address' });
+        return typeof value === 'string' || value === null ? value : null;
+      },
+      signIn: async (message) => {
+        const value = await request({ method: 'sign-in', message });
+        if (typeof value !== 'string' || !/^0x[0-9a-fA-F]+$/.test(value)) throw new Error('invalid signature response');
+        return value as `0x${string}`;
+      },
+      sessionEvidence: () => request({ method: 'session-evidence' }),
+      buy: async (authorisation, progress) => {
+        const value = await request({ method: 'buy', authorisation }, progress);
+        if (typeof value !== 'object' || value === null) return { failed: { bought: false, reason: 'try-again' } };
+        const spent = (value as { spentWei?: unknown }).spentWei;
+        try {
+          const spentWei = BigInt(String(spent));
+          return spentWei >= 0n ? { spentWei } : { failed: { bought: false, reason: 'try-again' } };
+        } catch {
+          return { failed: { bought: false, reason: 'try-again' } };
+        }
+      },
+    };
+    const identity: IdentityResolver = {
+      resolve: async (players) => {
+        const value = await request({ method: 'identity', players });
+        return isPlayerIdentities(value) ? value : [];
+      },
+    };
+    const marketReadable: Readable<MarketState> = {
+      current: () => market.current(),
+      subscribe: (listener) => market.subscribe(listener),
+    };
+    return {
+      context: trustedContext,
+      host,
+      platform: { identity, market: marketReadable },
+      dispose: () => {
+        if (disposed) return;
+        disposed = true;
+        current.removeEventListener('message', onMessage);
+        for (const waiting of pending.values()) {
+          clearTimeout(waiting.timer);
+          waiting.reject(new Error('the embedded connection is closed'));
+        }
+        pending.clear();
+        market.clear();
+      },
+    };
+  });
+}
+
+export interface ServeEmbeddedGameOptions {
+  currentWindow?: EmbedEventWindow;
+  frameWindow: EmbedTargetWindow;
+  gameOrigin: string;
+  context: EmbeddedContext;
+  host: Host;
+  /**
+   * Verify the gate signature and signer for the canonical spend fields.
+   *
+   * The bridge itself checks the complete ABI encoding, including the required zero referrer,
+   * before calling this seam. A false result fails closed before any wallet UI can open.
+   */
+  validateAuthorisation(
+    authorisation: Authorisation,
+    context: EmbeddedContext,
+    signal?: AbortSignal,
+  ): boolean | Promise<boolean>;
+  platform?: ClientPlatform;
+  /** Display domain used by the gate's canonical wallet challenge. */
+  signInDomain?: string;
+}
+
+function wireMarket(state: MarketState): WireMarketState {
+  return { ...state, trades: state.trades.map((trade) => ({ ...trade, spendWei: trade.spendWei.toString() })) };
+}
+
+function failure(reason: string): EmbedFailure {
+  return ['nothing-to-spend', 'declined', 'not-enough-for-fees', 'window-closed'].includes(reason)
+    ? (reason as EmbedFailure)
+    : 'try-again';
+}
+
+/** Serve one known iframe. Both its origin and WindowProxy are required for every request. */
+export function serveEmbeddedGame(options: ServeEmbeddedGameOptions): () => void {
+  const current = options.currentWindow ?? window;
+  const active = new Set<string>();
+  const acceptedRequestIds = new Set<string>();
+  const usedAuthorisations = new Set<string>();
+  const requestTimes: number[] = [];
+  let buyActive = false;
+  let signInActive = false;
+  let evidenceActive = false;
+  let childReady = false;
+  let stopped = false;
+  const lifetime = new AbortController();
+  let latestMarket: MarketState | null = options.platform?.market?.current() ?? null;
+  const post = (message: HostToGameMessage): void => {
+    if (!stopped) options.frameWindow.postMessage(message, options.gameOrigin);
+  };
+  const answer = (id: string, value: unknown): void =>
+    post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'response', id, ok: true, value });
+  const refuse = (id: string, error: EmbedFailure): void =>
+    post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'response', id, ok: false, error });
+
+  const run = async (id: string, request: EmbedRequest): Promise<void> => {
+    if (stopped || acceptedRequestIds.has(id) || acceptedRequestIds.size >= MAX_ACCEPTED_REQUEST_IDS) return;
+    const now = Date.now();
+    while (requestTimes[0] !== undefined && requestTimes[0] <= now - 1_000) requestTimes.shift();
+    if (active.size >= 16 || requestTimes.length >= 64) return;
+    requestTimes.push(now);
+    acceptedRequestIds.add(id);
+    active.add(id);
+    try {
+      switch (request.method) {
+        case 'address':
+          answer(id, await options.host.address(lifetime.signal));
+          break;
+        case 'sign-in':
+          if (signInActive) {
+            refuse(id, 'try-again');
+            break;
+          }
+          signInActive = true;
+          try {
+            const address = await options.host.address(lifetime.signal);
+            if (stopped) break;
+            if (
+              !address ||
+              !isSessionChallenge(request.message, address, options.context.gateUrl, options.signInDomain)
+            ) {
+              refuse(id, address ? 'try-again' : 'no-wallet');
+              break;
+            }
+            const signature = await options.host.signIn(request.message, lifetime.signal);
+            if (stopped) break;
+            answer(id, signature);
+          } finally {
+            signInActive = false;
+          }
+          break;
+        case 'session-evidence':
+          if (evidenceActive) {
+            refuse(id, 'try-again');
+            break;
+          }
+          evidenceActive = true;
+          try {
+            const evidence = await options.host.sessionEvidence?.(lifetime.signal);
+            if (!stopped) answer(id, evidence);
+          } finally {
+            evidenceActive = false;
+          }
+          break;
+        case 'identity':
+          answer(id, (await options.platform?.identity?.resolve(request.players)) ?? []);
+          break;
+        case 'buy': {
+          if (buyActive) {
+            refuse(id, 'try-again');
+            break;
+          }
+          buyActive = true;
+          try {
+            const address = await options.host.address(lifetime.signal);
+            if (stopped) break;
+            if (
+              !address ||
+              address.toLowerCase() !== request.authorisation.buyer.toLowerCase() ||
+              request.authorisation.poolId.toLowerCase() !== options.context.launch.poolId.toLowerCase()
+            ) {
+              refuse(id, address ? 'try-again' : 'no-wallet');
+              break;
+            }
+            if (
+              !isCanonicalSpendHookData(request.authorisation) ||
+              !(await options.validateAuthorisation(request.authorisation, options.context, lifetime.signal))
+            ) {
+              refuse(id, 'try-again');
+              break;
+            }
+            if (stopped) break;
+            const authorisationId = [
+              request.authorisation.buyer.toLowerCase(),
+              request.authorisation.poolId.toLowerCase(),
+              request.authorisation.nonce,
+            ].join(':');
+            if (usedAuthorisations.has(authorisationId) || usedAuthorisations.size >= 256) {
+              refuse(id, 'try-again');
+              break;
+            }
+            usedAuthorisations.add(authorisationId);
+            const result = await options.host.buy(
+              request.authorisation,
+              (event) => {
+                post({
+                  channel: EMBED_CHANNEL,
+                  v: EMBED_PROTOCOL_VERSION,
+                  type: 'buy-progress',
+                  id,
+                  ...(event.transactionHash ? { transactionHash: event.transactionHash } : {}),
+                });
+              },
+              lifetime.signal,
+            );
+            if (stopped) break;
+            if ('failed' in result) {
+              refuse(id, result.failed.bought ? 'try-again' : failure(result.failed.reason));
+            } else {
+              answer(id, { spentWei: result.spentWei.toString() });
+            }
+          } finally {
+            buyActive = false;
+          }
+          break;
+        }
+      }
+    } catch {
+      refuse(id, 'try-again');
+    } finally {
+      active.delete(id);
+    }
+  };
+
+  const onMessage: EventListener = (rawEvent): void => {
+    const event = rawEvent as MessageEvent;
+    if (event.origin !== options.gameOrigin || event.source !== options.frameWindow) return;
+    const message = parseGameToHostMessage(event.data);
+    if (!message) return;
+    if (message.type === 'ready') {
+      if (childReady) return;
+      childReady = true;
+      post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'context', context: options.context });
+      if (latestMarket) {
+        post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'market', market: wireMarket(latestMarket) });
+      }
+      return;
+    }
+    void run(message.id, message.request);
+  };
+  current.addEventListener('message', onMessage);
+  const stopMarket =
+    options.platform?.market?.subscribe((state) => {
+      latestMarket = state;
+      if (childReady) {
+        post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'market', market: wireMarket(state) });
+      }
+    }) ?? (() => {});
+
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    lifetime.abort();
+    current.removeEventListener('message', onMessage);
+    stopMarket();
+  };
+}

package/src/identity.ts

@@ -0,0 +1,51 @@
+import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import type { PlayerIdentity } from '@flayerlabs/gamemode-spec/live';
+import type { IdentityResolver } from './index.js';
+
+/** Batches misses through the platform adapter and gives every requested player a stable answer. */
+export class CachedIdentityResolver implements IdentityResolver {
+  private readonly cache = new Map<PlayerId, PlayerIdentity>();
+  private readonly inFlight = new Map<PlayerId, Promise<void>>();
+
+  constructor(private readonly adapter?: IdentityResolver) {}
+
+  async resolve(players: readonly PlayerId[]): Promise<readonly PlayerIdentity[]> {
+    if (players.length > 1_000) throw new RangeError('at most 1,000 identities may be resolved at once');
+    const unique = [...new Set(players)];
+    const missing = unique.filter((player) => !this.cache.has(player));
+    const unclaimed = missing.filter((player) => !this.inFlight.has(player));
+
+    if (unclaimed.length > 0) {
+      let loading!: Promise<void>;
+      loading = this.resolveMissing(unclaimed).finally(() => {
+        for (const player of unclaimed) {
+          if (this.inFlight.get(player) === loading) this.inFlight.delete(player);
+        }
+      });
+      for (const player of unclaimed) this.inFlight.set(player, loading);
+    }
+
+    await Promise.all(missing.map((player) => this.inFlight.get(player)));
+
+    return unique.map((player) => this.cache.get(player)!);
+  }
+
+  private async resolveMissing(players: readonly PlayerId[]): Promise<void> {
+    const asked = new Set(players);
+    const batches: PlayerId[][] = [];
+    for (let offset = 0; offset < players.length; offset += 100) {
+      batches.push(players.slice(offset, offset + 100));
+    }
+    const results = await Promise.all(batches.map((batch) => this.adapter?.resolve(batch).catch(() => []) ?? []));
+    for (const resolved of results) {
+      for (const identity of resolved) {
+        if (asked.has(identity.player)) this.cache.set(identity.player, identity);
+      }
+    }
+    for (const player of players) {
+      if (!this.cache.has(player)) {
+        this.cache.set(player, { player, displayName: null, avatarUrl: null });
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,172 @@
+import type { GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
+import type {
+  BuyFailure,
+  ConnectionState,
+  EconomyBalance,
+  LaunchContext,
+  MarketState,
+  PlayerIdentity,
+  PresenceState,
+  Reaction,
+} from '@flayerlabs/gamemode-spec/live';
+import { MockRoom } from './mock.js';
+
+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 function createMockRoom<Config, State, Event, Action, PublicView, PlayerView>(
+  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+  options: MockOptions<Config>,
+): Room<PublicView, PlayerView, Action> {
+  return new MockRoom(game, options);
+}