@flayerlabs/gamemode-client 0.3.0 → 0.4.0

package/src/host.ts

@@ -0,0 +1,178 @@
+import type { Host } from './live.js';
+import {
+  FRAME_PROTOCOL_VERSION,
+  gameFrameFrom,
+  type EmbedContext,
+  type HostErrorCode,
+  type HostToGameFrame,
+} from '@flayerlabs/gamemode-spec/frame';
+
+/**
+ * The page's end of the frame protocol: service a game iframe's Host calls.
+ *
+ * This file is its own entry (`@flayerlabs/gamemode-client/host`) rather than part of the main one,
+ * because the page that embeds a game needs none of the game's machinery — importing the parent
+ * side must not drag `LiveRoom` or the mock into an embedder's bundle. The only thing it shares
+ * with the game side is the wire contract in `@flayerlabs/gamemode-spec/frame`; `Host` crosses as a
+ * type alone.
+ *
+ * The page implements the three Host methods with its real wallet; this function does the
+ * listening, the pinning and the dispatch. It answers every `gm:hello` with the context (the frame
+ * may have said hello before this listener existed, so the context is also posted unprompted on
+ * attach — both mount orders work), and it answers every request, refusals included: a game left
+ * waiting cannot tell a slow human from a broken page.
+ */
+
+/**
+ * Thrown by a page's Host implementation to name WHY a call was refused. Anything else thrown maps
+ * to 'failed', so a page that never throws this still behaves — it just tells the game less.
+ */
+export class HostRefusal extends Error {
+  constructor(
+    public readonly code: HostErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'HostRefusal';
+  }
+}
+
+/** The one thing a frame's window must be able to do. Structural, so tests can stand one in. */
+export interface PostTarget {
+  postMessage(message: unknown, targetOrigin: string): void;
+}
+
+/** Where the page hears messages. Defaults to the real window; injectable for tests. */
+export interface HostListenSource {
+  listen(handler: (data: unknown, origin: string, source: unknown) => void): () => void;
+}
+
+export interface AttachGameHostOptions {
+  /** The iframe element (or anything with its `contentWindow`). Read at send time, not attach time. */
+  frame: { contentWindow: PostTarget | null };
+  /** The game's origin, from the iframe URL the page itself built — never from a message. */
+  gameOrigin: string;
+  /** What the game needs to join its round. A function is read fresh per send. */
+  context: EmbedContext | (() => EmbedContext);
+  host: Host;
+  endpoint?: HostListenSource;
+}
+
+function windowListenSource(): HostListenSource {
+  return {
+    listen(handler) {
+      const onMessage = (event: MessageEvent) => handler(event.data, event.origin, event.source);
+      window.addEventListener('message', onMessage);
+      return () => window.removeEventListener('message', onMessage);
+    },
+  };
+}
+
+const refusalOf = (error: unknown): { code: HostErrorCode; message: string } =>
+  error instanceof HostRefusal
+    ? { code: error.code, message: error.message }
+    : { code: 'failed', message: error instanceof Error ? error.message : 'something went wrong' };
+
+/** Attach the page's Host to a game iframe. Returns detach; after it, nothing is ever posted again. */
+export function attachGameHost(options: AttachGameHostOptions): () => void {
+  const { frame, gameOrigin, host } = options;
+  const endpoint = options.endpoint ?? windowListenSource();
+  // Detached is checked at every send because a settling buy outlives many renders: the answer to
+  // a request accepted by THIS attachment must never be posted into a frame we no longer own.
+  let detached = false;
+
+  const send = (message: HostToGameFrame): void => {
+    if (detached) return;
+    frame.contentWindow?.postMessage(message, gameOrigin);
+  };
+
+  const sendContext = (): void => {
+    const context = typeof options.context === 'function' ? options.context() : options.context;
+    send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:context', context });
+  };
+
+  const unlisten = endpoint.listen((data, origin, source) => {
+    // Both checks, always: origin says who wrote the frame, source says which window sent it.
+    // This listener shares the page's window with every other frame the page hosts.
+    if (detached || origin !== gameOrigin || source !== frame.contentWindow) return;
+    const parsed = gameFrameFrom(data);
+    if (!parsed) return;
+
+    if (parsed.type === 'gm:hello') {
+      sendContext();
+      return;
+    }
+
+    const { id, call } = parsed;
+    void (async () => {
+      try {
+        if (call.method === 'address') {
+          const address = await host.address();
+          send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:res', id, ok: true, result: { method: 'address', address } });
+          return;
+        }
+        if (call.method === 'signIn') {
+          const signature = await host.signIn(call.message);
+          send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:res', id, ok: true, result: { method: 'signIn', signature } });
+          return;
+        }
+        // The wire allows hookData to be absent (older frames), but a buy cannot be executed
+        // without its opaque proof — refuse here, at the execution boundary, in the protocol's
+        // own vocabulary rather than letting a type hole reach the wallet call.
+        const { hookData } = call.authorisation;
+        if (hookData === undefined) {
+          send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:res', id, ok: false, error: { code: 'failed', message: 'that authorisation carries no hookData' } });
+          return;
+        }
+        const outcome = await host.buy({ ...call.authorisation, hookData }, (progress) => {
+          send({
+            v: FRAME_PROTOCOL_VERSION,
+            type: 'gm:progress',
+            id,
+            progress:
+              progress.transactionHash !== undefined
+                ? { state: 'pending', transactionHash: progress.transactionHash }
+                : { state: 'pending' },
+          });
+        });
+        if ('spentWei' in outcome) {
+          send({
+            v: FRAME_PROTOCOL_VERSION,
+            type: 'gm:res',
+            id,
+            ok: true,
+            result: { method: 'buy', outcome: { spentWei: outcome.spentWei.toString() } },
+          });
+        } else if (outcome.failed.bought === false) {
+          send({
+            v: FRAME_PROTOCOL_VERSION,
+            type: 'gm:res',
+            id,
+            ok: true,
+            result: { method: 'buy', outcome: { failed: outcome.failed } },
+          });
+        } else {
+          // A Host reporting success through the failure channel is a bug on the page's side;
+          // the game is told the plain truth it can act on.
+          send({
+            v: FRAME_PROTOCOL_VERSION,
+            type: 'gm:res',
+            id,
+            ok: true,
+            result: { method: 'buy', outcome: { spentWei: outcome.failed.spentWei.toString() } },
+          });
+        }
+      } catch (error) {
+        send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:res', id, ok: false, error: refusalOf(error) });
+      }
+    })();
+  });
+
+  // Unprompted, because the frame may have said hello before this listener existed.
+  sendContext();
+
+  return () => {
+    detached = true;
+    unlisten();
+  };
+}

package/src/index.ts

@@ -29,15 +29,14 @@ export type {
 } from '@flayerlabs/gamemode-spec/live';
 
 export { joinEconomy, 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';
+export { connectHost } from './embed.js';
+export type { ConnectHostOptions, EmbeddedHost, FrameEndpoint } from './embed.js';
+export { attachGameHost, HostRefusal } from './host.js';
+export type { AttachGameHostOptions, HostListenSource, PostTarget } from './host.js';
+export type { EmbedContext } from '@flayerlabs/gamemode-spec/frame';
 
 /**
  * What a game talks to. Gameplay stays small; reusable platform concerns live in named capabilities.
@@ -134,13 +133,9 @@ export type BuyProgress =
 
 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.
- */
+// BuyFailure lives in @flayerlabs/gamemode-spec/live (re-exported above): the live room and the
+// embedding page both produce those values, so every end shares one definition.
+
 export interface Social {
   react(id: string): void;
   onReaction(listener: (reaction: Reaction) => void): () => void;