Preview a match by join code before joining

GET /api/games/preview returns the lobby behind a code plus the game's
name and engine-echoed options. The lobby debounces the lookup as a
complete code is typed and shows the game, seated players, open seats
and option badges rendered from the game's schema, disabling Join when
the lobby is full or the match has already started.

server/packages/tavolo-platform/src/tavolo/platform/engine.py

@@ -201,7 +201,13 @@ class GameEngine(ABC):
 
     @abstractmethod
     def lobby_view(self, session: GameSession) -> Dict[str, Any]:
-        """Game-specific fields of the lobby payload (options echo, phase)."""
+        """Game-specific fields of the lobby payload (options echo, phase).
+
+        Echo the creation options under the same keys as
+        :attr:`options_schema`, plus ``phase``, so clients can render a
+        generic pre-join preview (``GET /api/games/preview``) from the
+        schema without game-specific code.
+        """
 
     @abstractmethod
     def in_lobby(self, session: GameSession) -> bool:

server/packages/tavolo-platform/src/tavolo/platform/routes/games.py

@@ -24,7 +24,14 @@ from kaya.openapi import operation
 from ..auth import display_name, require_auth
 from ..engine import GameSession, Seat
 from ..errors import GameError
-from ..http import JsonRequestError, read_json, read_json_optional, send_error, send_json
+from ..http import (
+    JsonRequestError,
+    extract_query_params,
+    read_json,
+    read_json_optional,
+    send_error,
+    send_json,
+)
 
 if TYPE_CHECKING:
     from ..mixin import Platform
@@ -79,6 +86,18 @@ def _view_payload(platform: "Platform", session: GameSession, sub: str) -> Dict[
     }
 
 
+def _preview_payload(platform: "Platform", session: GameSession) -> Dict[str, Any]:
+    """The join-code preview: the lobby payload plus the game's name and
+    description, so a client can render a pre-join summary without a
+    second lookup."""
+    engine = platform.registry.require(session.game_type)
+    return {
+        **_lobby_payload(platform, session),
+        "game_name": engine.name,
+        "game_description": engine.description,
+    }
+
+
 def register(app: KayaApp, platform: "Platform") -> None:
     @app.GET("/api/game-types")
     @operation(summary="List available games",
@@ -262,6 +281,33 @@ def register(app: KayaApp, platform: "Platform") -> None:
         log.info("%s joined game %s (seat %d); match started", user.sub, session.id, seat)
         await send_json(ctx, 200, _view_payload(platform, session, user.sub))
 
+    @app.GET("/api/games/preview")
+    @operation(summary="Preview a game by join code",
+               description="Looks up a game by its join code without "
+                           "joining, for the lobby's pre-join summary: game "
+                           "name and description, seated players, open "
+                           "seats and the game-specific options echoed by "
+                           "its engine.",
+               tags=["games"],
+               responses={
+                   200: {"description": "The lobby preview"},
+                   400: {"description": "Missing code"},
+                   401: {"description": "Authentication required"},
+                   404: {"description": "Unknown join code"},
+               })
+    @require_auth(platform.oidc)
+    async def preview_game(ctx: HttpContext) -> None:
+        values = extract_query_params(ctx.query_string).get("code")
+        code = values[0].strip() if values else ""
+        if not code:
+            await send_error(ctx, 400, "code is required")
+            return
+        session = await platform.game_store.find_by_code(code)
+        if session is None:
+            await send_error(ctx, 404, "unknown join code")
+            return
+        await send_json(ctx, 200, _preview_payload(platform, session))
+
     @app.GET("/api/games/${game_id}")
     @operation(summary="Get a game snapshot",
                description="Only seated players may read a game; the view is "

server/packages/tavolo-platform/tests/test_routes.py

@@ -69,6 +69,56 @@ class GamesRouteTest(unittest.TestCase):
             self.assertEqual(0, state["plays"])
             self.assertTrue(state["viewer_seated"])
 
+    @async_test
+    async def test_preview_requires_auth(self) -> None:
+        app, _, _ = make_platform()
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            response = await client.get("/api/games/preview?code=ABC123")
+            self.assertEqual(401, response.status_code)
+
+    @async_test
+    async def test_preview_lobby_and_started_game(self) -> None:
+        app, platform, _ = make_platform()
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            with oidc_user(platform.oidc, "alice"):
+                created = await client.post(
+                    "/api/games", json={"options": {"target": 5}}
+                )
+            code = created.json()["join_code"]
+
+            with oidc_user(platform.oidc, "mallory"):
+                missing = await client.get("/api/games/preview")
+                unknown = await client.get("/api/games/preview?code=ZZZZZZ")
+            self.assertEqual(400, missing.status_code)
+            self.assertEqual(404, unknown.status_code)
+
+            with oidc_user(platform.oidc, "mallory"):
+                preview = await client.get(f"/api/games/preview?code={code}")
+            self.assertEqual(200, preview.status_code)
+            body = preview.json()
+            self.assertEqual("dummy", body["game_type"])
+            self.assertEqual("Dummy game", body["game_name"])
+            self.assertTrue(body["game_description"])
+            self.assertEqual("lobby", body["phase"])
+            self.assertEqual(5, body["target"])
+            self.assertEqual(1, body["seats_open"])
+            self.assertEqual("alice", body["players"][0]["sub"])
+
+            # Join codes are case-insensitive.
+            with oidc_user(platform.oidc, "mallory"):
+                lower = await client.get(f"/api/games/preview?code={code.lower()}")
+            self.assertEqual(200, lower.status_code)
+
+            with oidc_user(platform.oidc, "bob"):
+                await client.post("/api/games/join", json={"code": code})
+            with oidc_user(platform.oidc, "mallory"):
+                started = await client.get(f"/api/games/preview?code={code}")
+            self.assertEqual(200, started.status_code)
+            self.assertEqual("playing", started.json()["phase"])
+            self.assertEqual(0, started.json()["seats_open"])
+
     @async_test
     async def test_create_rejects_bad_options(self) -> None:
         app, platform, _ = make_platform()