Add briscola: classic two-player and briscola a quattro

New tavolo-briscola distribution implementing briscola on the platform:

- pure rules (state.py, engine.py): 3-card deals, a face-up trump that
  is the last card drawn, trump-first trick resolution (A > 3 > K > H >
  J > 7 > 6 > 5 > 4 > 2), 120 points per deal, 60-60 patta re-deals, a
  configurable target score (default 61), deal-end acknowledgements and
  turn auto-play;
- BriscolaEngine (briscola, 2 players) and BriscolaQuattroEngine
  (briscola_a_quattro, 4 players in fixed partnerships) adapters;
- registered in tavolo-app, packaged in the Docker image, documented.

Platform fixes surfaced by a two-player lobby:

- the websocket state and snapshot payloads now carry seats_open (they
  were only in the REST lobby payload), so lobbies with player counts
  other than four render correctly; seats_open is clamped at zero;
- the web client logs unparseable server messages instead of silently
  dropping them.

Web client: briscola table for both variants (stock, face-up trump,
trick, last-trick banner), deal summary modal and game-over overlay.

Tests: tavolo-briscola rules/adapter suites, app integration tests
(lobby, websocket play, turn timeout, deal-end acks, persistence), a
platform seats_open test and frontend model parsing tests.

README.md

@@ -1,14 +1,16 @@
 # tavolo
 
-A platform for multiplayer card games. The first game is **scopone
+A platform for multiplayer card games. Two games are included:
-scientifico** — the four-player, fixed-partnership Italian card game:
+**scopone scientifico** — the four-player, fixed-partnership Italian card
+game — and **briscola**, in its classic two-player and four-player
+partnership (*briscola a quattro*) variants:
 
 - **`server/`** — backend: Python + [kaya](https://github.com/woggioni/kaya)
   framework, OIDC login, live games in Redis, match statistics in Postgres.
-  A monorepo of three distributions sharing the `tavolo` namespace: the
+  A monorepo of four distributions sharing the `tavolo` namespace: the
-  game-independent `tavolo-platform`, the scopone game `tavolo-scopone`,
+  game-independent `tavolo-platform`, the `tavolo-scopone` and
-  and the `tavolo-app` composition root wiring them together.
+  `tavolo-briscola` games, and the `tavolo-app` composition root wiring
-  See [server/README.md](server/README.md).
+  them together. See [server/README.md](server/README.md).
 - **`web/`** — frontend: Rust + [Sycamore](https://sycamore.dev) compiled to
   WebAssembly, built with [Trunk](https://trunkrs.dev) and styled with
   [Bootstrap](https://getbootstrap.com) 5.3 (MIT, vendored under
@@ -37,21 +39,30 @@ echo "127.0.0.1 mockoauth" | sudo tee -a /etc/hosts
 ## Between hands
 
 When a hand ends but the match is not decided, the game pauses on a
-**scoring summary screen**: every player sees how each category was won
+**scoring summary screen**: scopone players see how each category was won
 (carte, denara, settebello, primiera, scope — plus napola and asso
-pigliatutto when enabled)
+pigliatutto when enabled), briscola players see the deal's points and any
-with the running totals and
+*patta*; both see the running totals and must click "Understood" before
-must click "Understood" before the next hand is dealt. If someone is away
+the next hand is dealt. If someone is away the next hand is dealt
-the next hand is dealt automatically after `HAND_ACK_TIMEOUT_SECONDS`
+automatically after `HAND_ACK_TIMEOUT_SECONDS` (default 30s). The
-(default 30s). The match-ending hand is explained on the final screen.
+match-ending hand is explained on the final screen.
 
 ## On your turn
 
 Every turn shows a countdown (`TURN_TIMEOUT_SECONDS`, default 30s). If a
 player does not move — disconnected or fallen asleep — the server plays a
-random legal card for them (randomizing among the legal captures when the
+random legal card for them (choosing among the legal captures when the
 rules require a capture), so one absent player cannot stall the table.
 
+## Watching
+
+Anyone who has the game URL (`/game/<id>`) can watch, logged in or not:
+spectators see the table, the score and every player's captured cards
+(and scope for scopone), but never a hand and never the join code. The
+"Copy watch link" button in the waiting room and in the game HUD copies
+the URL to share. A spectator who opens the URL before the match starts
+sees a "game not started yet" waiting room.
+
 ## Development
 
 Backend (from `server/`):
@@ -60,10 +71,11 @@ Backend (from `server/`):
 cd server
 python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt
-.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e './packages/tavolo-app[dev]'
+.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e ./packages/tavolo-briscola -e './packages/tavolo-app[dev]'
 .venv/bin/python -m unittest discover -s tests -t .
 .venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
 .venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
+.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
 ```
 
 Frontend (from `web/`), with the backend running on :8080:
@@ -78,8 +90,12 @@ Trunk proxies `/api`, `/auth` and `/ws` to `127.0.0.1:8080` (see
 run the backend with:
 
 ```sh
-OIDC_POST_LOGIN_REDIRECT=http://localhost:8000/ \
+OIDC_0_PROVIDER=default \
-OIDC_POST_LOGOUT_REDIRECT=http://localhost:8000/ \
+OIDC_0_ISSUER=http://localhost:8180/tavolo \
+OIDC_0_CLIENT_ID=tavolo \
+OIDC_0_REDIRECT_URI=http://localhost:8080/auth/default/callback \
+OIDC_0_POST_LOGIN_REDIRECT=http://localhost:8000/ \
+OIDC_0_POST_LOGOUT_REDIRECT=http://localhost:8000/ \
   .venv/bin/granian --host 127.0.0.1 --port 8080 tavolo.app:app
 ```
 

deploy/k8s/tavolo.yaml

@@ -21,7 +21,7 @@
 #   - This file deploys a ClusterIP Service only. Until you add an Ingress,
 #     reach the app with:
 #         kubectl port-forward -n tavolo svc/tavolo 8080:80
-#     and set OIDC_REDIRECT_URI to match whatever URL the browser uses.
+#     and set OIDC_0_REDIRECT_URI to match whatever URL the browser uses.
 
 ---
 apiVersion: v1
@@ -71,22 +71,32 @@ data:
   # CORS_ALLOW_CREDENTIALS: "false"
   # CORS_EXPOSE_HEADERS: ""
   # CORS_MAX_AGE: "600"
-  # OpenTelemetry (kaya-otel): traces + metrics via OTLP/HTTP, disabled
+  # OpenTelemetry (kaya-otel + contrib instrumentations): traces
-  # unless OTEL_ENABLED is set. The image bundles the otel extra.
+  # (HTTP/WebSocket, Postgres, Redis), metrics and logs via OTLP/HTTP,
+  # disabled unless OTEL_ENABLED is set. The image bundles the otel extra.
   # OTEL_ENABLED: "true"
   # OTEL_SERVICE_NAME: "tavolo"
   # OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector.observability:4318"
   # OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Bearer ..."
   # OTEL_EXCLUDED_PATHS: "/api/health"   # default; paths skipped by tracing
-  # OIDC (provider lives in another namespace).
+  # OTEL_METRIC_EXPORT_INTERVAL_MILLIS: "60000"
-  OIDC_CLIENT_ID: tavolo
+  # OTEL_METRICS_POLL_INTERVAL_SECONDS: "15"
-  OIDC_POST_LOGIN_REDIRECT: /
+  # OIDC (the provider lives in another namespace). Each provider is an
-  OIDC_POST_LOGOUT_REDIRECT: /
+  # indexed block: OIDC_<n>_PROVIDER names it in the login URL
+  # (/auth/<provider>/login) and indices must be contiguous from 0. Add
+  # OIDC_1_*, OIDC_2_*, ... blocks for more providers; add their secrets
+  # to tavolo-secrets as well.
+  OIDC_0_PROVIDER: default
+  OIDC_0_CLIENT_ID: tavolo
+  OIDC_0_POST_LOGIN_REDIRECT: /
+  OIDC_0_POST_LOGOUT_REDIRECT: /
   # Issuer URL as seen by the browser AND the pods (see notes above).
-  OIDC_ISSUER: REPLACE_ME
+  OIDC_0_ISSUER: REPLACE_ME
   # Public callback URL of this deployment, e.g.
-  # http://<host>:<port>/auth/callback (must be allowed at the provider).
+  # http://<host>:<port>/auth/default/callback (must be allowed at the
-  OIDC_REDIRECT_URI: REPLACE_ME
+  # provider). When unset it defaults to
+  # http://localhost:8080/auth/<provider>/callback.
+  OIDC_0_REDIRECT_URI: REPLACE_ME
 
 ---
 apiVersion: v1
@@ -103,8 +113,8 @@ stringData:
   # The only Postgres secret: the password for DATABASE_USER at
   # DATABASE_HOST (both configured in the tavolo-config ConfigMap).
   DATABASE_PASSWORD: REPLACE_ME
-  # Client secret for OIDC_CLIENT_ID at the provider.
+  # Client secret for OIDC_0_CLIENT_ID at the provider.
-  OIDC_CLIENT_SECRET: REPLACE_ME
+  OIDC_0_CLIENT_SECRET: REPLACE_ME
 
 ---
 # Redis: sessions + live game state. Ephemeral by design (emptyDir): worst

docker-compose.yml

@@ -103,13 +103,15 @@ services:
       DATABASE_USER: tavolo
       DATABASE_PASSWORD: ${DATABASE_PASSWORD:-password}
       # By default the app and browsers reach the mock IdP under the same
-      # name (see README /etc/hosts note); override OIDC_ISSUER and
+      # name (see README /etc/hosts note); override the OIDC_0_* values to
-      # OIDC_REDIRECT_URI to use a real provider or a different host port.
+      # use a real provider or a different host port. Additional providers
-      OIDC_ISSUER: ${OIDC_ISSUER:-http://mockoauth:8180/tavolo}
+      # take OIDC_1_*, OIDC_2_*, ... blocks (indices are contiguous from 0).
+      OIDC_0_PROVIDER: ${OIDC_0_PROVIDER:-default}
+      OIDC_0_ISSUER: ${OIDC_0_ISSUER:-http://mockoauth:8180/tavolo}
       # The mock OIDC server does not validate clients: any id/secret works.
-      OIDC_CLIENT_ID: tavolo
+      OIDC_0_CLIENT_ID: tavolo
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET:-dev-secret}
+      OIDC_0_CLIENT_SECRET: ${OIDC_0_CLIENT_SECRET:-dev-secret}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-http://localhost:8080/auth/callback}
+      OIDC_0_REDIRECT_URI: ${OIDC_0_REDIRECT_URI:-http://localhost:8080/auth/default/callback}
       REDIS_URL: redis://redis:6379/0
       HAND_ACK_TIMEOUT_SECONDS: ${HAND_ACK_TIMEOUT_SECONDS:-30}
       TURN_TIMEOUT_SECONDS: ${TURN_TIMEOUT_SECONDS:-30}
@@ -122,7 +124,9 @@ services:
       CORS_ALLOW_CREDENTIALS: ${CORS_ALLOW_CREDENTIALS:-}
       CORS_EXPOSE_HEADERS: ${CORS_EXPOSE_HEADERS:-}
       CORS_MAX_AGE: ${CORS_MAX_AGE:-}
-      # OpenTelemetry (kaya-otel): disabled unless OTEL_ENABLED is set.
+      # OpenTelemetry (kaya-otel + contrib instrumentations): traces
+      # (HTTP/WebSocket, Postgres, Redis), metrics and logs via OTLP/HTTP,
+      # disabled unless OTEL_ENABLED is set.
       # The image bundles the otel extra (see packages/tavolo-app/pyproject.toml
       # and server/requirements.txt).
       OTEL_ENABLED: ${OTEL_ENABLED:-}

server/.env.example

@@ -13,12 +13,29 @@ DATABASE_OPTIONS=
 # test suite (sqlite://:memory:) and handy for managed-DB URLs.
 #DATABASE_URL=postgres://tavolo:password@localhost:5432/tavolo
 
-# OIDC (mock-oauth2-server in dev; it does not validate clients, so any
+# OIDC providers. Each provider is an indexed block: OIDC_<n>_PROVIDER
-# client id/secret works. For a real IdP like Keycloak, use its values here.)
+# (required; names the provider in the login URL /auth/<provider>/login and
-OIDC_ISSUER=http://localhost:8180/tavolo
+# in its session state), OIDC_<n>_ISSUER, OIDC_<n>_CLIENT_ID,
-OIDC_CLIENT_ID=tavolo
+# OIDC_<n>_CLIENT_SECRET (optional: leave unset for public clients),
-OIDC_CLIENT_SECRET=dev-secret
+# OIDC_<n>_REDIRECT_URI (defaults to
-OIDC_REDIRECT_URI=http://localhost:8080/auth/callback
+# http://localhost:8080/auth/<provider>/callback), OIDC_<n>_POST_LOGIN_REDIRECT
+# and OIDC_<n>_POST_LOGOUT_REDIRECT (default /). Indices must be contiguous
+# from 0; add a second provider with an OIDC_1_* block (and so on).
+#
+# The values below target the dev mock-oauth2-server (it does not validate
+# clients, so any client id/secret works). For a real IdP like Keycloak,
+# use its values and register the redirect URI there.
+OIDC_0_PROVIDER=default
+OIDC_0_ISSUER=http://localhost:8180/tavolo
+OIDC_0_CLIENT_ID=tavolo
+OIDC_0_CLIENT_SECRET=dev-secret
+OIDC_0_REDIRECT_URI=http://localhost:8080/auth/default/callback
+# A second provider, e.g. Google:
+#OIDC_1_PROVIDER=google
+#OIDC_1_ISSUER=https://accounts.google.com
+#OIDC_1_CLIENT_ID=...
+#OIDC_1_CLIENT_SECRET=...
+#OIDC_1_REDIRECT_URI=http://localhost:8080/auth/google/callback
 
 # Redis (session and live-game storage). Unset to fall back to in-memory
 # stores (only sensible for local development with a single worker).
@@ -61,6 +78,23 @@ TURN_TIMEOUT_SECONDS=30
 # Seconds browsers may cache the preflight response (default 600):
 #CORS_MAX_AGE=600
 
+# OpenTelemetry (via kaya-otel + the contrib instrumentation packages).
+# Off unless OTEL_ENABLED is truthy; exports traces (HTTP/WebSocket,
+# Postgres via asyncpg, Redis), metrics and logs over OTLP/HTTP (requires
+# the tavolo-app "otel" extra, bundled in the Docker image). The endpoint
+# defaults to the standard OTEL_EXPORTER_OTLP_ENDPOINT (localhost:4318)
+# when unset.
+#OTEL_ENABLED=true
+#OTEL_SERVICE_NAME=tavolo
+#OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+#OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer token,X-Tenant=one
+# Paths excluded from tracing and metrics (default /api/health).
+#OTEL_EXCLUDED_PATHS=/api/health
+# Metric export interval (ms, default 60000) and session/game count poll
+# interval (seconds, default 15).
+#OTEL_METRIC_EXPORT_INTERVAL_MILLIS=60000
+#OTEL_METRICS_POLL_INTERVAL_SECONDS=15
+
 # App server
 APP_HOST=0.0.0.0
 APP_PORT=8080

server/Dockerfile

@@ -58,13 +58,13 @@ RUN --mount=type=cache,target=/root/.cache/pip \
  && /opt/venv/bin/pip install --upgrade pip \
  && /opt/venv/bin/pip install -r requirements.txt
 
-# The three sibling distributions, installed from the local tree (PEP 420
+# The four sibling distributions, installed from the local tree (PEP 420
 # namespace packages sharing the `tavolo` namespace). --no-deps: every
 # third-party dependency — including the tavolo-app `otel` extra — is
 # already pinned in requirements.txt.
 COPY server/packages/ ./packages/
 RUN --mount=type=cache,target=/root/.cache/pip \
-    /opt/venv/bin/pip install --no-deps ./packages/tavolo-platform ./packages/tavolo-scopone ./packages/tavolo-app
+    /opt/venv/bin/pip install --no-deps ./packages/tavolo-platform ./packages/tavolo-scopone ./packages/tavolo-briscola ./packages/tavolo-app
 # server/pyproject.toml only carries the [tool.aerich] section (the
 # db-migrate compose service runs `aerich upgrade` with working_dir=/app,
 # next to ./migrations).

server/README.md

@@ -1,10 +1,12 @@
 # tavolo (backend)
 
 The backend for a multiplayer card-game platform, built on the
-[kaya](../kaya) framework. It is a monorepo of three distributions
+[kaya](../kaya) framework. It is a monorepo of four distributions
 sharing the `tavolo` namespace (see
-[`packages/tavolo-platform/README.md`](packages/tavolo-platform/README.md)
+[`packages/tavolo-platform/README.md`](packages/tavolo-platform/README.md),
-and [`packages/tavolo-scopone/README.md`](packages/tavolo-scopone/README.md)):
+[`packages/tavolo-scopone/README.md`](packages/tavolo-scopone/README.md)
+and
+[`packages/tavolo-briscola/README.md`](packages/tavolo-briscola/README.md)):
 
 - **`tavolo-platform`** (`packages/tavolo-platform/`) — everything
   game-independent: the lobby API, the live-game store, the WebSocket
@@ -13,8 +15,12 @@ and [`packages/tavolo-scopone/README.md`](packages/tavolo-scopone/README.md)):
 - **`tavolo-scopone`** (`packages/tavolo-scopone/`) — scopone
   scientifico, the four-player, fixed-partnership variant of the classic
   Italian card game: pure rules plus the platform adapter.
+- **`tavolo-briscola`** (`packages/tavolo-briscola/`) — briscola, the
+  Italian trick-taking game, in its classic two-player (`briscola`) and
+  four-player partnership (`briscola_a_quattro`) variants: pure rules
+  plus the platform adapter.
 - **`tavolo-app`** (`packages/tavolo-app/`) — the
-  composition root wiring the platform to the scopone game, with the
+  composition root wiring the platform to the games, with the
   environment-driven settings and the SPA shell.
 
 Players authenticate with the configured **OIDC** provider. Live game
@@ -43,7 +49,8 @@ Because the browser and the app both talk to the OIDC issuer at
 echo "127.0.0.1 mockoauth" | sudo tee -a /etc/hosts
 ```
 
-Then log in: `GET http://localhost:8080/auth/login`, type any username
+Then log in: `GET http://localhost:8080/auth/login` (a provider-agnostic
+alias that redirects to the first configured provider), type any username
 (e.g. `alice`) in the interactive login, and you are redirected back with a
 session cookie. That cookie authenticates both the REST API and the
 WebSocket endpoint.
@@ -65,14 +72,17 @@ All configuration comes from environment variables (see `.env.example`):
 | `DATABASE_OPTIONS` | unset | Extra DSN query parameters, e.g. `ssl=require` |
 | `DATABASE_URL` | unset | Full-DSN override; when set, the `DATABASE_*` parts above are ignored (used for sqlite in tests and for managed-DB URLs) |
 | `REDIS_URL` | unset | Redis DSN for sessions + live games. Unset falls back to in-memory stores |
-| `OIDC_ISSUER` | `http://localhost:8180/tavolo` | OIDC issuer URL |
+| `OIDC_<n>_PROVIDER` | `default` ¹ | Provider name (required when OIDC is configured): used in the login URL `/auth/<provider>/login` and to namespace its session keys. Unique, `[A-Za-z0-9_-]+` |
-| `OIDC_CLIENT_ID` | `tavolo` | OIDC client id |
+| `OIDC_<n>_ISSUER` | `http://localhost:8180/tavolo` ¹ | OIDC issuer URL |
-| `OIDC_CLIENT_SECRET` | unset | OIDC client secret |
+| `OIDC_<n>_CLIENT_ID` | `tavolo` ¹ | OIDC client id |
-| `OIDC_REDIRECT_URI` | `http://localhost:8080/auth/callback` | Login callback URL |
+| `OIDC_<n>_CLIENT_SECRET` | unset | OIDC client secret; leave unset for public clients |
+| `OIDC_<n>_REDIRECT_URI` | `http://localhost:8080/auth/<provider>/callback` | Login callback URL; must be registered at the provider |
+| `OIDC_<n>_POST_LOGIN_REDIRECT` | `/` | Where the browser is sent after login |
+| `OIDC_<n>_POST_LOGOUT_REDIRECT` | `/` | Where the browser is sent after logout |
 | `GAME_TTL_SECONDS` | `86400` | Sliding TTL of a live game in Redis |
-| `HAND_ACK_TIMEOUT_SECONDS` | `30` | Seconds the scopone between-hands scoring summary waits for acknowledgements (wired into the `ScoponeEngine`) |
+| `HAND_ACK_TIMEOUT_SECONDS` | `30` | Seconds the between-hands scoring summary waits for acknowledgements (wired into the game engines) |
-| `TURN_TIMEOUT_SECONDS` | `30` | Seconds a scopone player has to play before the server plays a random legal card for them (wired into the `ScoponeEngine`) |
+| `TURN_TIMEOUT_SECONDS` | `30` | Seconds a player has to play before the server plays a random legal card for them (wired into the game engines) |
-| `DEADLINE_HEARTBEAT_MS` | `1000` | Upper bound on the deadline consumer's poll interval (locally enqueued deadlines fire on time regardless) |
+| `DEADLINE_HEARTBEAT_MS` | `30000` | Backstop poll interval of the deadline consumer; enqueued deadlines are announced over pub/sub and wake consumers immediately, so this only bounds recovery from lost notifications or a dead worker |
 | `LOGGING_CONFIG` | unset | Path to a YAML logging configuration file (see below). Unset logs DEBUG to the console |
 | `CORS_ALLOW_ORIGINS` | unset | Comma-separated origins allowed for cross-origin requests, or `*` for any. CORS is disabled unless this or `CORS_ALLOW_ORIGIN_REGEX` is set |
 | `CORS_ALLOW_ORIGIN_REGEX` | unset | Regex (fullmatch) additionally matched against request origins, e.g. `https://tavolo-[a-z0-9-]+\.vercel\.app` |
@@ -81,13 +91,53 @@ All configuration comes from environment variables (see `.env.example`):
 | `CORS_ALLOW_CREDENTIALS` | `false` | `1`/`true`/`yes`/`on` allow cookies/credentials on cross-origin requests |
 | `CORS_EXPOSE_HEADERS` | unset | Comma-separated response headers exposed to the browser |
 | `CORS_MAX_AGE` | `600` | Seconds browsers may cache the preflight response |
-| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces and metrics (the Docker image bundles the `otel` extra; non-image installs need `pip install tavolo-app[otel]`) |
+| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces, metrics and logs (the Docker image bundles the `otel` extra; non-image installs need `pip install tavolo-app[otel]`) |
 | `OTEL_SERVICE_NAME` | `tavolo` | `service.name` resource attribute of the exported telemetry |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | Base URL of an OTLP/HTTP collector (e.g. `http://localhost:4318`); unset uses the exporter default |
 | `OTEL_EXPORTER_OTLP_HEADERS` | unset | Comma-separated `key=value` headers sent to the collector (e.g. authentication) |
 | `OTEL_EXCLUDED_PATHS` | `/api/health` | Comma-separated paths excluded from tracing and metrics (exact matches) |
+| `OTEL_METRIC_EXPORT_INTERVAL_MILLIS` | `60000` | How often the OTLP metric reader exports |
+| `OTEL_METRICS_POLL_INTERVAL_SECONDS` | `15` | How often the session/game count gauges are refreshed |
 | `APP_HOST` / `APP_PORT` | `0.0.0.0` / `8080` | Bind address |
 
+¹ When no `OIDC_<n>_*` variable is set at all, a single provider named
+`default` pointing at the dev mock IdP is used. Indices must be contiguous
+from 0 (`OIDC_0_*`, `OIDC_1_*`, ...).
+
+### Multiple OIDC providers
+
+Providers are configured in indexed blocks; each becomes its own login
+route `/auth/<provider>/login` with its own callback URL and session
+namespace:
+
+```sh
+OIDC_0_PROVIDER=google
+OIDC_0_ISSUER=https://accounts.google.com
+OIDC_0_CLIENT_ID=...
+OIDC_0_CLIENT_SECRET=...
+OIDC_0_REDIRECT_URI=https://tavolo.example.com/auth/google/callback
+
+OIDC_1_PROVIDER=github
+OIDC_1_ISSUER=https://github.com/login/oauth
+OIDC_1_CLIENT_ID=...
+OIDC_1_CLIENT_SECRET=...
+OIDC_1_REDIRECT_URI=https://tavolo.example.com/auth/github/callback
+```
+
+The login page reads `GET /api/auth/providers` and shows one button per
+provider. `GET /auth/login` redirects to the first provider (useful for
+bookmarks and scripts), and `GET /auth/logout` signs out whichever
+provider the session is logged in with.
+
+Sessions hold a single identity: logging in with another provider
+replaces the previous one. Each provider's `sub` is a separate account,
+so match history and Elo ratings are per provider identity (someone using
+two providers has two accounts). Migrating from the pre-0.0.6 unindexed
+variables: rename `OIDC_ISSUER`/`OIDC_CLIENT_ID`/... to `OIDC_0_...`, add
+`OIDC_0_PROVIDER`, and register the new callback path
+(`/auth/<provider>/callback`) at the provider. Sessions survive only when
+the provider is named `default`; otherwise users log in once more.
+
 ## Logging
 
 The application logs through the Python stdlib `logging` module, one
@@ -123,6 +173,37 @@ loggers:
     level: INFO
 ```
 
+## OpenTelemetry
+
+With `OTEL_ENABLED` set, the app exports over OTLP/HTTP (kaya-otel plus
+`tavolo.telemetry`):
+
+- **Traces**: HTTP server spans, one span per WebSocket connection, plus
+  database spans for the Postgres (asyncpg, through Tortoise) and Redis
+  clients. Redis command values are redacted by the instrumentation
+  (`GET ? ?`) and asyncpg spans carry the parameterized SQL only — no
+  parameter values. Each HTTP/WebSocket span is tagged with the request's
+  session and user, so all traces of a session can be found together:
+  `session.id` is a truncated SHA-256 of the session id (the cookie is a
+  credential, so it is never exported verbatim) and `user.id` is the OIDC
+  `sub`, present once logged in.
+- **Metrics**: the HTTP server metrics from kaya-otel, plus
+  `tavolo.active_users` (sessions in the session store),
+  `tavolo.ongoing_games` (live matches not finished yet, maintained by the
+  game store), and process/CPython metrics from
+  `opentelemetry-instrumentation-system-metrics`: `process.cpu.time`,
+  `process.cpu.utilization`, `process.memory.usage`,
+  `process.memory.virtual`, `cpython.gc.collections`,
+  `cpython.gc.collected_objects` and `cpython.gc.uncollectable_objects`.
+- **Logs**: forwarded from the root logger at the configured console level
+  (OpenTelemetry's own records are filtered out to avoid export loops).
+
+The session/game gauges are polled every
+`OTEL_METRICS_POLL_INTERVAL_SECONDS` (Redis-backed stores report
+cluster-wide counts, in-memory stores the process's own). Note that with
+multiple workers or replicas each process reports the same global counts:
+aggregate with `max`, not `sum`.
+
 ## Data model
 
 ### Redis (live games)
@@ -137,12 +218,15 @@ loggers:
   signals; every open WebSocket reloads the session and pushes the
   personalized view to its player.
 - `tavolo:deadlines` — a sorted set (score = due timestamp) of pending
-  timeouts (e.g. scopone's turn auto-plays and hand-end auto-continues).
+  timeouts (e.g. the games' turn auto-plays and hand-end auto-continues).
   Every worker runs a consumer that fires due entries under the per-game
   lock by calling the engine's `fire_deadline`, so timeouts do not depend
   on any player being connected and survive the death of any worker
   (delivery is at-least-once; engines revalidate the entry's token
   against the live state before firing).
+- `tavolo:deadlines:events` — a pub/sub channel announcing newly enqueued
+  deadlines; it wakes every worker's consumer immediately, while the
+  heartbeat poll remains as a backstop for lost signals.
 
 ### Postgres (statistics, via Tortoise ORM + aerich migrations)
 
@@ -151,7 +235,8 @@ loggers:
   scoped per game), start/finish timestamps, and the game-specific outcome
   as reported by the engine (`result` JSON — for scopone: both teams'
   final scores, winner, target score, hands played and the per-hand
-  audit).
+  audit; for briscola: the final scores, winner, target score, deals
+  played and the per-deal audit).
 - `match_player` — one row per participant: the OIDC `sub`, display name,
   seat, game-defined team label (nullable), whether they won, the points
   they scored, the Elo change the match produced (`elo_delta`) and
@@ -184,37 +269,46 @@ existed):
 ## REST API
 
 All endpoints except `/api/health`, `/api/docs`, `/api/openapi.json`,
-`/api/game-types` and `/api/leaderboard` require authentication.
+`/api/game-types`, `/api/leaderboard` and the game snapshot
+(`GET /api/games/{id}`) require authentication.
 
 | Method | Path | Description |
 |---|---|---|
 | `GET` | `/api/game-types` | The games the platform can host (for the creation dropdown), each with its `options_schema` |
-| `POST` | `/api/games` | Create a lobby game. Optional body `{"game_type": "scopone_scientifico", "options": {"target_score": 11, "napola": true, "asso_pigliatutto": false}}`. Returns the lobby (`{id, join_code, players, seats_open, ...}`) |
+| `POST` | `/api/games` | Create a lobby game. Optional body `{"game_type": "scopone_scientifico", "options": {"target_score": 11, "napola": true, "asso_pigliatutto": false}}`; briscola games use `{"game_type": "briscola"}` or `{"game_type": "briscola_a_quattro"}` with an optional `{"target_score": 61}`. Returns the lobby (`{id, join_code, players, seats_open, ...}`) |
 | `POST` | `/api/games/join` | Join with `{"code": "ABC123"}`. The last player triggers the start and gets the game view back |
 | `GET` | `/api/games/preview?code=ABC123` | Pre-join summary of the lobby behind a code: game name/description, seated players, open seats and the engine-echoed options. `404` when the code is unknown |
-| `GET` | `/api/games/{id}` | Personalized snapshot (only your own hand is visible) |
+| `GET` | `/api/games/{id}` | Game snapshot. Seated players get the personalized view (own hand plus the join code); anyone else gets the read-only spectator view: table, scores, captured counts and scope, no hands and no join code |
 | `GET` | `/api/me/matches` | Cursor-paginated match history with the engine's `result` and per-player Elo deltas (`?limit=&cursor=&game_type=`) |
 | `GET` | `/api/me/ratings` | The caller's Elo rating per game type |
 | `GET` | `/api/leaderboard` | Elo rating, aggregated wins / matches / points per player, sorted by Elo (`?game_type=`) |
 
 ## WebSocket protocol
 
-Connect to `/ws/games/{game_id}` with your session cookie. Only seated
+Connect to `/ws/games/{game_id}`; the session cookie is optional. Anyone
-players are accepted; unauthenticated, unknown-game and non-player
+who knows the game id is accepted: seated players get their personalized
-connections are closed with codes `4401`, `4404` and `4403` respectively.
+view, everyone else — anonymous users and authenticated non-players — is
+a read-only **spectator**. Only an unknown game id is refused before the
+handshake completes, with `404`. (Browsers report a refused handshake as
+an abnormal close — there is no close code to read.)
 
 Server → client messages are JSON objects with a `type`:
 
 - `{"type": "state", "game": {...}}` — personalized game view. Your own
   hand is included; other players expose only their card counts.
-  `your_turn: true` is present when it is your move.
+  Spectators get no hand at all, `spectator: true` marks the view and
+  `join_code` is omitted for them. `your_turn: true` is present when it
+  is your move. `seats_open` reports the free chairs (0 once the match
+  started).
 - `{"type": "game_over", "scores": {"A": 11, "B": 7}, "winner": "A"}`
 - `{"type": "error", "code": "illegal_move", "message": "..."}`
 
 Client → server messages are JSON objects with an `action`. The
 platform handles `state` (resend the snapshot) itself; every other action
 is dispatched to the session's game engine with the rest of the message
-as its payload. For scopone scientifico:
+as its payload. Spectators may only send `state`/`sync`: any other
+action is answered with an `error` whose `code` is `forbidden`. For
+scopone scientifico:
 
 ```json
 {"action": "play", "card": "07D", "capture": ["02D", "05C"]}
@@ -233,7 +327,21 @@ as its payload. For scopone scientifico:
   after `HAND_ACK_TIMEOUT_SECONDS`.
 - `state` asks for a fresh snapshot.
 
-After every accepted move the new state is broadcast to all four players.
+For briscola (`briscola`, `briscola_a_quattro`) the game actions are
+`play` (with `card` only — every card in hand is legal) and `ack`:
+
+```json
+{"action": "play", "card": "04C"}
+{"action": "ack"}
+```
+
+- `card` uses the same `RRSUIT` convention.
+- `ack` acknowledges the deal-end summary; the next deal is dealt once
+  every player has acknowledged, or automatically after
+  `HAND_ACK_TIMEOUT_SECONDS`.
+
+After every accepted move the new state is broadcast to every connected
+client, spectators included.
 
 ### Turn timeout
 
@@ -249,15 +357,18 @@ match keeps progressing even with every player disconnected.
 ### Hand-end summary
 
 When a hand finishes but the match continues, the game enters the
-`hand_end` phase instead of dealing immediately: the state carries
+`hand_end` phase instead of dealing immediately: the state carries the
-`last_hand` (a full scoring breakdown with an `award` map naming the team
+scoring breakdown of the hand just played (`last_hand` with an `award`
-that won each category), the `acknowledged` seats and a
+map naming the team that won each scopone category; `last_deal` with the
-`hand_end_deadline`. The frontend renders this as a screen every player
+deal's points and running totals for briscola), the `acknowledged` seats
-must dismiss. A play attempted in this phase is rejected with an
+and a `hand_end_deadline`. The frontend renders this as a screen every
+player must dismiss. A play attempted in this phase is rejected with an
 `illegal_move` error.
 
 ## Rules implemented
 
+### Scopone scientifico
+
 - 40-card Italian deck, ten cards per player, empty table at hand start.
 - A card captures a **single card of equal rank** (mandatory when present)
   or a **combination of table cards whose ranks sum to its own**.
@@ -281,20 +392,45 @@ must dismiss. A play attempted in this phase is rejected with an
   configurable per game via the `target_score` creation option) with a
   clear lead; a tie at or above the target is broken by another hand.
 
+### Briscola
+
+- 40-card Italian deck, three cards per player. The card turned up after
+  the deal fixes the trump (*briscola*) suit for the whole deal and is the
+  last card drawn from the stock.
+- Trick play: the highest trump wins; when no trump was played, the
+  highest card of the led suit wins. The winner takes the trick and leads
+  the next one.
+- After each trick every player draws back up to three cards, starting
+  with the trick winner; the face-up briscola card goes to whoever's turn
+  to draw it is.
+- Card points: ace 11, three 10, king 4, horse 3, jack 2 — 120 points per
+  deal. Trick strength is unrelated to points: ace > three > king > horse
+  > jack > 7 > 6 > 5 > 4 > 2.
+- Match points accumulate across deals; a 60–60 deal is a *patta*: its
+  points are discarded and the deal is replayed. The match ends when a
+  team reaches the target score (default 61, configurable per game via
+  the `target_score` creation option) with a clear lead; a tie at or
+  above the target is broken by another deal.
+- `briscola` is the classic two-player game; `briscola_a_quattro` seats
+  four players in two fixed partnerships (seats 0/2 vs 1/3, partners
+  opposite).
+
 ## Development
 
 ```sh
 python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt
-.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e './packages/tavolo-app[dev]'
+.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e ./packages/tavolo-briscola -e './packages/tavolo-app[dev]'
 # app integration suite:
 .venv/bin/python -m unittest discover -s tests -t .
 # per-package suites (each package is self-contained):
 .venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
 .venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
+.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
 # type checks (see packages/tavolo-app/README.md for the app modules):
 .venv/bin/python -m mypy -p tavolo.platform
 .venv/bin/python -m mypy -p tavolo.scopone
+.venv/bin/python -m mypy -p tavolo.briscola
 ```
 
 Tests run fully in-process: in-memory sqlite for Postgres, in-memory stores
@@ -352,14 +488,21 @@ packages/tavolo-scopone/      # scopone scientifico game (own pyproject + tests)
   ├── engine.py               # pure scopone scientifico rules
   ├── errors.py               # scopone-specific rule violations
   └── plugin.py               # ScoponeEngine: the GameEngine adapter
+packages/tavolo-briscola/     # briscola game (own pyproject + tests)
+  src/tavolo/briscola/
+  ├── state.py                # BriscolaState / PlayerState / Card / Trick, JSON (de)serialization
+  ├── engine.py               # pure briscola rules (2- and 4-player)
+  ├── errors.py               # briscola-specific rule violations
+  └── plugin.py               # BriscolaEngine + BriscolaQuattroEngine adapters
 packages/tavolo-app/          # deployable app: composition root (own pyproject)
   src/tavolo/
   ├── app.py                  # session/OIDC/Tortoise/OpenAPI/Platform/DeadlineScheduler mixins
   ├── config.py               # env -> frozen Settings
+  ├── telemetry.py            # OTLP metric/log providers, app gauges, count poller
   ├── aerich_config.py        # aerich CLI configuration
   ├── logging_config.py       # logging setup
   └── static.py               # SPA shell hosting
 pyproject.toml                # tooling shim: [tool.aerich] + [tool.mypy] for server/ CWD
 migrations/                   # aerich migrations for the platform models
-tests/                        # app integration suite (platform + scopone wired together)
+tests/                        # app integration suite (platform + games wired together)
 ```

server/conftest.py

@@ -10,7 +10,8 @@ from __future__ import annotations
 import os
 
 os.environ.setdefault("DATABASE_URL", "sqlite://:memory:")
-os.environ.setdefault("OIDC_ISSUER", "http://localhost:8180/tavolo")
+os.environ.setdefault("OIDC_0_PROVIDER", "default")
-os.environ.setdefault("OIDC_CLIENT_ID", "tavolo")
+os.environ.setdefault("OIDC_0_ISSUER", "http://localhost:8180/tavolo")
-os.environ.setdefault("OIDC_REDIRECT_URI", "http://localhost:8080/auth/callback")
+os.environ.setdefault("OIDC_0_CLIENT_ID", "tavolo")
+os.environ.setdefault("OIDC_0_REDIRECT_URI", "http://localhost:8080/auth/default/callback")
 os.environ.pop("REDIS_URL", None)

server/packages/tavolo-app/README.md

@@ -2,15 +2,22 @@
 
 The deployable tavolo application: the composition root wiring
 [`tavolo-platform`](../tavolo-platform/README.md) to the
-[`tavolo-scopone`](../tavolo-scopone/README.md) game.
+[`tavolo-scopone`](../tavolo-scopone/README.md) and
+[`tavolo-briscola`](../tavolo-briscola/README.md) games.
 
 ## Contents
 
 - `app.py` — assembles the `KayaApp` (session/OIDC/Tortoise/OpenAPI
   mixins plus `PlatformMixin` and the deadline scheduler), registers the
-  `ScoponeEngine` with its configured timeouts, and exposes
+  `ScoponeEngine`, `BriscolaEngine` and `BriscolaQuattroEngine` with
-  `tavolo.app:app` for granian.
+  their configured timeouts, and exposes `tavolo.app:app` for granian.
 - `config.py` — environment-driven frozen `Settings`.
+- `telemetry.py` — the optional OpenTelemetry wiring beyond kaya-otel:
+  meter/tracer/logger providers, the
+  `tavolo.active_users`/`tavolo.ongoing_games` gauges (polled from the
+  stores), process/CPython metrics via
+  `opentelemetry-instrumentation-system-metrics`, Postgres/Redis query
+  spans via the asyncpg/redis instrumentations, and OTLP log export.
 - `aerich_config.py` — Tortoise ORM configuration consumed by the aerich
   CLI (migrations live in `server/migrations/`; aerich itself is
   configured via the `[tool.aerich]` section of `server/pyproject.toml`).
@@ -23,6 +30,7 @@ The deployable tavolo application: the composition root wiring
 .venv/bin/python -m mypy --namespace-packages --explicit-package-bases \
   src/tavolo/app.py \
   src/tavolo/config.py \
+  src/tavolo/telemetry.py \
   src/tavolo/static.py \
   src/tavolo/aerich_config.py \
   src/tavolo/logging_config.py

server/packages/tavolo-app/pyproject.toml

@@ -5,12 +5,13 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "tavolo-app"
 version = "0.1.0"
-description = "Tavolo multiplayer card-game application: platform + scopone game wiring"
+description = "Tavolo multiplayer card-game application: platform + games wiring"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "tavolo-platform",
     "tavolo-scopone",
+    "tavolo-briscola",
     "kaya-core",
     "kaya-cors",
     "kaya-session",
@@ -34,7 +35,10 @@ dev = [
     "httpx-ws",
 ]
 otel = [
-    "kaya-otel>=0.0.4",
+    "kaya-otel>=0.0.7",
+    "opentelemetry-instrumentation-asyncpg>=0.66b0",
+    "opentelemetry-instrumentation-redis>=0.66b0",
+    "opentelemetry-instrumentation-system-metrics>=0.66b0",
 ]
 
 [tool.setuptools.packages.find]

server/packages/tavolo-app/src/tavolo/app.py

@@ -6,7 +6,7 @@ platform:
 - :class:`~kaya.session.SessionMixin` (sessions persisted in Redis via
   :class:`~kaya.session.redis.RedisSessionStore` when ``REDIS_URL`` is set,
   otherwise an in-memory store — e.g. for tests)
-- :class:`~kaya.oidc.OIDCMixin` (OIDC login)
+- :class:`~kaya.oidc.OIDCProviders` (the configured OIDC providers)
 - :class:`~tavolo.platform.tortoise_mixin.TortoiseMixin` (Postgres match
   statistics; skipped for ``/api/health`` and the OpenAPI documentation
   endpoints)
@@ -31,15 +31,15 @@ from __future__ import annotations
 
 from importlib.metadata import version as _pkg_version
 from logging import getLogger
-from typing import Optional
+from typing import Any, Dict, Optional
 
 from kaya.core import KayaApp, KayaMixin
 from kaya.cors import CorsMixin
-from kaya.oidc import OIDCConfig, OIDCMixin
+from kaya.oidc import OIDCConfig, OIDCProviders
 from kaya.openapi import OpenAPIMixin
-from kaya.session import InMemorySessionStore, SessionMixin, SessionStore
+from kaya.session import SessionMixin
-from kaya.session.redis import RedisSessionStore
 from redis.asyncio import Redis
+from tavolo.briscola import BriscolaEngine, BriscolaQuattroEngine
 from tavolo.platform import GameRegistry, Platform, PlatformMixin
 from tavolo.platform.deadlines import DeadlineScheduler, DeadlineSchedulerMixin
 from tavolo.platform.store import GameStore, InMemoryGameStore, RedisGameStore
@@ -48,6 +48,14 @@ from tavolo.scopone import ScoponeEngine
 
 from .config import Settings, settings
 from .logging_config import configure_logging
+from .telemetry import (
+    CountableSessionStore,
+    CountingInMemorySessionStore,
+    CountingRedisSessionStore,
+    otel_headers,
+    session_tag_hook,
+    telemetry_from_settings,
+)
 
 configure_logging(settings.logging_config)
 log = getLogger(__name__)
@@ -73,13 +81,23 @@ def cors_mixin_from_settings(settings: Settings) -> Optional[CorsMixin]:
     )
 
 
-def otel_mixin_from_settings(settings: Settings) -> Optional[KayaMixin]:
+def otel_mixin_from_settings(
+    settings: Settings,
+    meter_provider: Optional[Any] = None,
+    tracer_provider: Optional[Any] = None,
+) -> Optional[KayaMixin]:
     """Build a :class:`~kaya.otel.OTelMixin` from the OTEL_* settings.
 
     Returns ``None`` — telemetry disabled — unless ``OTEL_ENABLED`` is
     truthy. kaya-otel is an optional dependency (the ``otel`` extra), so it
     is imported lazily here: default installs and the test suite never need
     the OpenTelemetry packages.
+
+    ``meter_provider``/``tracer_provider`` are the providers built by
+    :func:`tavolo.telemetry.telemetry_from_settings`; injecting them lets
+    the custom instruments and the database instrumentations share the same
+    OTLP pipelines (kaya-otel then leaves their shutdown to the telemetry
+    mixin).
     """
     if not settings.otel_enabled:
         return None
@@ -90,17 +108,21 @@ def otel_mixin_from_settings(settings: Settings) -> Optional[KayaMixin]:
             "OTEL_ENABLED is set but kaya-otel is not installed; "
             "install tavolo-app with the 'otel' extra"
         ) from exc
-    headers = dict(
+    kwargs: Dict[str, Any] = {
-        pair.split("=", 1)
+        "service_name": settings.otel_service_name,
-        for pair in (settings.otel_exporter_headers or ())
+        "endpoint": settings.otel_exporter_endpoint,
-        if "=" in pair
+        "headers": otel_headers(settings),
-    )
+        "excluded_paths": settings.otel_excluded_paths,
-    return OTelMixin(
+        # Runs after the session mixin's after hook, so the session id has
-        service_name=settings.otel_service_name,
+        # been persisted/minted and the OIDC claims are on the session.
-        endpoint=settings.otel_exporter_endpoint,
+        "server_response_hook": session_tag_hook,
-        headers=headers or None,
+        "websocket_close_hook": session_tag_hook,
-        excluded_paths=settings.otel_excluded_paths,
+    }
-    )
+    if meter_provider is not None:
+        kwargs["meter_provider"] = meter_provider
+    if tracer_provider is not None:
+        kwargs["tracer_provider"] = tracer_provider
+    return OTelMixin(**kwargs)
 
 
 registry = GameRegistry()
@@ -110,19 +132,31 @@ registry.register(
         hand_ack_timeout_seconds=settings.hand_ack_timeout_seconds,
     )
 )
+registry.register(
+    BriscolaEngine(
+        turn_timeout_seconds=settings.turn_timeout_seconds,
+        hand_ack_timeout_seconds=settings.hand_ack_timeout_seconds,
+    )
+)
+registry.register(
+    BriscolaQuattroEngine(
+        turn_timeout_seconds=settings.turn_timeout_seconds,
+        hand_ack_timeout_seconds=settings.hand_ack_timeout_seconds,
+    )
+)
 log.info("registered games: %s", ", ".join(e.id for e in registry.all()))
 log.debug(
-    "scopone timeouts: hand_ack=%ds turn=%ds",
+    "game timeouts: hand_ack=%ds turn=%ds",
     settings.hand_ack_timeout_seconds,
     settings.turn_timeout_seconds,
 )
 
-session_store: SessionStore
+session_store: CountableSessionStore
 game_store: GameStore
 if settings.redis_url is not None:
     # Lazy client: no connection is opened until a session is actually
     # loaded/saved, so importing this module never requires a live Redis.
-    session_store = RedisSessionStore(Redis.from_url(settings.redis_url))
+    session_store = CountingRedisSessionStore(Redis.from_url(settings.redis_url))
     game_store = RedisGameStore(
         Redis.from_url(settings.redis_url, decode_responses=False),
         registry,
@@ -130,23 +164,31 @@ if settings.redis_url is not None:
     )
     log.info("using Redis stores (sessions + live games, game TTL %ds)", settings.game_ttl_seconds)
 else:
-    session_store = InMemorySessionStore()
+    session_store = CountingInMemorySessionStore()
     game_store = InMemoryGameStore(registry)
     log.info("REDIS_URL unset: using in-memory stores (sessions + live games)")
 
 session_mixin = SessionMixin(session_store)
-oidc_mixin = OIDCMixin(
+oidc = OIDCProviders(
+    [
         OIDCConfig(
-        issuer=settings.oidc_issuer,
+            provider=provider.provider,
-        client_id=settings.oidc_client_id,
+            issuer=provider.issuer,
-        client_secret=settings.oidc_client_secret,
+            client_id=provider.client_id,
-        redirect_uri=settings.oidc_redirect_uri,
+            client_secret=provider.client_secret,
-        post_login_redirect=settings.oidc_post_login_redirect,
+            redirect_uri=provider.redirect_uri,
-        post_logout_redirect=settings.oidc_post_logout_redirect,
+            post_login_redirect=provider.post_login_redirect,
+            post_logout_redirect=provider.post_logout_redirect,
             fetch_userinfo=True,
-    ),
+        )
+        for provider in settings.oidc_providers
+    ],
     session=session_mixin,
 )
+log.info(
+    "OIDC providers: %s",
+    ", ".join(provider.provider for provider in settings.oidc_providers),
+)
 openapi_mixin = OpenAPIMixin(
     title="tavolo",
     version=_pkg_version("tavolo-app"),
@@ -171,20 +213,29 @@ platform = Platform(
     registry=registry,
     game_store=game_store,
     scheduler=scheduler,
-    oidc=oidc_mixin,
+    oidc=oidc,
 )
 
-mixins: list[KayaMixin] = [session_mixin, oidc_mixin, tortoise_mixin, openapi_mixin,
+mixins: list[KayaMixin] = [session_mixin, oidc, tortoise_mixin, openapi_mixin,
                            PlatformMixin(platform), DeadlineSchedulerMixin(scheduler)]
-otel_mixin = otel_mixin_from_settings(settings)
+telemetry = telemetry_from_settings(settings, session_store, game_store)
-if otel_mixin is not None:
+if telemetry is not None:
-    # First in the list: before hooks run in registration order (after hooks
+    otel_mixin = otel_mixin_from_settings(
+        settings,
+        meter_provider=telemetry.meter_provider,
+        tracer_provider=telemetry.tracer_provider,
+    )
+    assert otel_mixin is not None  # OTEL_ENABLED was checked above
+    # kaya-otel first: before hooks run in registration order (after hooks
     # in reverse), so the span covers session loading, OIDC handling and the
     # handler itself. CORS, when enabled, is still prepended before it so
-    # preflight short-circuits stay untraced.
+    # preflight short-circuits stay untraced. The telemetry mixin carries no
+    # hooks but owns the metric/logger providers' polling and shutdown, so
+    # it must be in the list too.
+    mixins.insert(0, telemetry.mixin)
     mixins.insert(0, otel_mixin)
     log.info(
-        "OpenTelemetry enabled: service=%s endpoint=%s",
+        "OpenTelemetry enabled: service=%s endpoint=%s (traces, metrics, logs)",
         settings.otel_service_name,
         settings.otel_exporter_endpoint or "(OTLP default)",
     )

server/packages/tavolo-app/src/tavolo/config.py

@@ -6,6 +6,7 @@ dataclass. No pydantic-settings, no settings module.
 from __future__ import annotations
 
 import os
+import re
 from dataclasses import dataclass
 from typing import Optional, Tuple
 from urllib.parse import quote
@@ -39,6 +40,135 @@ def _env_bool(name: str, default: bool = False) -> bool:
     return value.strip().lower() in ("1", "true", "yes", "on")
 
 
+# Per-provider OIDC settings are indexed with a 0-based suffix:
+# OIDC_<n>_PROVIDER, OIDC_<n>_ISSUER, ... Indices must be contiguous from 0.
+_OIDC_VARIABLES = (
+    "PROVIDER",
+    "ISSUER",
+    "CLIENT_ID",
+    "CLIENT_SECRET",
+    "REDIRECT_URI",
+    "POST_LOGIN_REDIRECT",
+    "POST_LOGOUT_REDIRECT",
+)
+_OIDC_ENV = re.compile(r"^OIDC_(\d+)_([A-Z0-9_]+)$")
+_PROVIDER_NAME = re.compile(r"^[A-Za-z0-9_-]+$")
+
+# The pre-0.0.6 unindexed names, detected only to point the migration out.
+_LEGACY_OIDC_VARIABLES = (
+    "OIDC_ISSUER",
+    "OIDC_CLIENT_ID",
+    "OIDC_CLIENT_SECRET",
+    "OIDC_REDIRECT_URI",
+    "OIDC_POST_LOGIN_REDIRECT",
+    "OIDC_POST_LOGOUT_REDIRECT",
+)
+
+_DEFAULT_OIDC_ISSUER = "http://localhost:8180/tavolo"
+_DEFAULT_OIDC_CLIENT_ID = "tavolo"
+
+
+@dataclass(frozen=True)
+class OidcProviderSettings:
+    """One OIDC provider, parsed from the ``OIDC_<n>_*`` variables.
+
+    ``provider`` names the provider in URLs (``/auth/<provider>/login``)
+    and namespaces its session state (``oidc:<provider>:...``); it must
+    match kaya-oidc's ``[A-Za-z0-9_-]+`` pattern.
+    """
+
+    provider: str
+    issuer: str
+    client_id: str
+    client_secret: Optional[str]
+    redirect_uri: str
+    post_login_redirect: str
+    post_logout_redirect: str
+
+
+def _oidc_providers_from_env() -> Tuple[OidcProviderSettings, ...]:
+    """Parse the indexed ``OIDC_<n>_*`` provider configuration.
+
+    With no indexed variables at all, fall back to a single provider
+    named ``default`` pointing at the dev mock IdP, mirroring the
+    pre-0.0.6 defaults. The old unindexed variables are rejected with a
+    migration hint: they would otherwise be silently ignored.
+    """
+    legacy = [name for name in _LEGACY_OIDC_VARIABLES if os.environ.get(name)]
+    if legacy:
+        renamed = ", ".join(
+            f"{name} -> OIDC_0_{name[len('OIDC_'):]}" for name in legacy
+        )
+        raise RuntimeError(
+            "the OIDC variables are now indexed per provider "
+            f"({renamed}; add OIDC_0_PROVIDER)"
+        )
+
+    indices: set = set()
+    for name in os.environ:
+        match = _OIDC_ENV.match(name)
+        if match is None:
+            continue
+        index, variable = match.groups()
+        if variable not in _OIDC_VARIABLES:
+            raise RuntimeError(
+                f"unknown OIDC environment variable {name!r}; expected one of "
+                + ", ".join(f"OIDC_<n>_{v}" for v in _OIDC_VARIABLES)
+            )
+        indices.add(int(index))
+
+    if not indices:
+        return (
+            OidcProviderSettings(
+                provider="default",
+                issuer=_DEFAULT_OIDC_ISSUER,
+                client_id=_DEFAULT_OIDC_CLIENT_ID,
+                client_secret=None,
+                redirect_uri="http://localhost:8080/auth/default/callback",
+                post_login_redirect="/",
+                post_logout_redirect="/",
+            ),
+        )
+
+    missing = sorted(set(range(max(indices) + 1)) - indices)
+    if missing:
+        raise RuntimeError(
+            "OIDC provider indices must be contiguous from 0; missing "
+            + ", ".join(f"OIDC_{index}_*" for index in missing)
+        )
+
+    providers = []
+    seen = set()
+    for index in sorted(indices):
+        prefix = f"OIDC_{index}_"
+        provider = _env(prefix + "PROVIDER")
+        if _PROVIDER_NAME.match(provider) is None:
+            raise RuntimeError(
+                f"{prefix}PROVIDER must be a non-empty string of letters, "
+                f"digits, underscores or hyphens (got {provider!r})"
+            )
+        if provider in seen:
+            raise RuntimeError(f"duplicate OIDC provider name {provider!r}")
+        seen.add(provider)
+        providers.append(
+            OidcProviderSettings(
+                provider=provider,
+                issuer=_env(prefix + "ISSUER"),
+                client_id=_env(prefix + "CLIENT_ID"),
+                client_secret=os.environ.get(prefix + "CLIENT_SECRET") or None,
+                # kaya-oidc's OIDCProviders derives the callback route from
+                # the provider name; keep the default in sync with it.
+                redirect_uri=_env(
+                    prefix + "REDIRECT_URI",
+                    f"http://localhost:8080/auth/{provider}/callback",
+                ),
+                post_login_redirect=_env(prefix + "POST_LOGIN_REDIRECT", "/"),
+                post_logout_redirect=_env(prefix + "POST_LOGOUT_REDIRECT", "/"),
+            )
+        )
+    return tuple(providers)
+
+
 def _database_url_from_parts(engine: str,
                              user: str,
                              password: Optional[str],
@@ -70,15 +200,10 @@ def _database_url_from_parts(engine: str,
 @dataclass(frozen=True)
 class Settings:
     database_url: str
-    oidc_issuer: str
+    # The configured OIDC providers, in index order. Each provider
-    oidc_client_id: str
+    # authenticates users independently and namespaces its session state;
-    oidc_client_secret: Optional[str]
+    # see OidcProviderSettings above.
-    oidc_redirect_uri: str
+    oidc_providers: Tuple[OidcProviderSettings, ...]
-    # Where the browser is sent after login/logout. In production the SPA is
-    # served by this app ("/"); in development point these at the trunk dev
-    # server (e.g. "http://localhost:8000/").
-    oidc_post_login_redirect: str
-    oidc_post_logout_redirect: str
     app_host: str
     app_port: int
     redis_url: Optional[str]
@@ -90,17 +215,17 @@ class Settings:
     # are served by Granian under /static (GRANIAN_STATIC_PATH_* env vars).
     static_dir: str
     # Seconds the between-hands scoring summary waits for acknowledgements
-    # before dealing the next hand anyway (wired into the ScoponeEngine;
+    # before dealing the next hand anyway (wired into the game engines;
     # see tavolo.app).
     hand_ack_timeout_seconds: int
     # Seconds a player has to play before the server plays a random legal
     # card for them, covering disconnects and idle players (wired into the
-    # ScoponeEngine; see tavolo.app).
+    # game engines; see tavolo.app).
     turn_timeout_seconds: int
-    # Upper bound on how long the deadline consumer sleeps between polls.
+    # Upper bound on how long the deadline consumer sleeps between polls
-    # Locally enqueued deadlines wake the consumer immediately; the
+    # when nothing else wakes it. Enqueued deadlines are announced over a
-    # heartbeat only bounds the discovery delay for deadlines enqueued by
+    # pub/sub channel, so this is only the backstop recovering lost
-    # other workers.
+    # notifications and deadlines orphaned by a dead worker.
     deadline_heartbeat_ms: int
     # Path to a YAML logging configuration file (logging.config.dictConfig
     # schema). Unset uses the built-in default: DEBUG to the console.
@@ -125,6 +250,10 @@ class Settings:
     # Paths excluded from tracing and metrics (exact matches). Defaults to
     # the health endpoint, which k8s probes would otherwise spam.
     otel_excluded_paths: Tuple[str, ...]
+    # How often the OTLP metric reader exports (milliseconds) and how often
+    # the telemetry gauges refresh the session/game counts (seconds).
+    otel_metric_export_interval_millis: int
+    otel_metrics_poll_interval_seconds: int
 
     @staticmethod
     def from_env() -> "Settings":
@@ -143,12 +272,7 @@ class Settings:
                 # Raw DSN query string (e.g. "ssl=require"); empty = none.
                 options=os.environ.get("DATABASE_OPTIONS", ""),
             ),
-            oidc_issuer=_env("OIDC_ISSUER", "http://localhost:8180/tavolo"),
+            oidc_providers=_oidc_providers_from_env(),
-            oidc_client_id=_env("OIDC_CLIENT_ID", "tavolo"),
-            oidc_client_secret=os.environ.get("OIDC_CLIENT_SECRET"),
-            oidc_redirect_uri=_env("OIDC_REDIRECT_URI", "http://localhost:8080/auth/callback"),
-            oidc_post_login_redirect=_env("OIDC_POST_LOGIN_REDIRECT", "/"),
-            oidc_post_logout_redirect=_env("OIDC_POST_LOGOUT_REDIRECT", "/"),
             app_host=_env("APP_HOST", "0.0.0.0"),
             app_port=int(_env("APP_PORT", "8080")),
             # When unset, sessions and live games fall back to in-memory
@@ -159,7 +283,7 @@ class Settings:
             static_dir=_env("STATIC_DIR", "web/dist"),
             hand_ack_timeout_seconds=int(_env("HAND_ACK_TIMEOUT_SECONDS", "30")),
             turn_timeout_seconds=int(_env("TURN_TIMEOUT_SECONDS", "30")),
-            deadline_heartbeat_ms=int(_env("DEADLINE_HEARTBEAT_MS", "1000")),
+            deadline_heartbeat_ms=int(_env("DEADLINE_HEARTBEAT_MS", "30000")),
             logging_config=os.environ.get("LOGGING_CONFIG"),
             # CORS is disabled unless CORS_ALLOW_ORIGINS (a comma-separated
             # list of origins, or "*" for any) or CORS_ALLOW_ORIGIN_REGEX
@@ -171,14 +295,20 @@ class Settings:
             cors_allow_credentials=_env_bool("CORS_ALLOW_CREDENTIALS"),
             cors_expose_headers=_env_list("CORS_EXPOSE_HEADERS"),
             cors_max_age=int(_env("CORS_MAX_AGE", "600")),
-            # OpenTelemetry is opt-in: set OTEL_ENABLED=1 to export traces
+            # OpenTelemetry is opt-in: set OTEL_ENABLED=1 to export traces,
-            # and metrics via OTLP/HTTP (requires the ``otel`` extra).
+            # metrics and logs via OTLP/HTTP (requires the ``otel`` extra).
             otel_enabled=_env_bool("OTEL_ENABLED"),
             otel_service_name=_env("OTEL_SERVICE_NAME", "tavolo"),
             otel_exporter_endpoint=os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT") or None,
             # Comma-separated key=value pairs, e.g. "Authorization=Bearer x".
             otel_exporter_headers=_env_list("OTEL_EXPORTER_OTLP_HEADERS"),
             otel_excluded_paths=_env_list("OTEL_EXCLUDED_PATHS") or ("/api/health",),
+            otel_metric_export_interval_millis=int(
+                _env("OTEL_METRIC_EXPORT_INTERVAL_MILLIS", "60000")
+            ),
+            otel_metrics_poll_interval_seconds=int(
+                _env("OTEL_METRICS_POLL_INTERVAL_SECONDS", "15")
+            ),
         )
 
 

server/packages/tavolo-app/src/tavolo/logging_config.py

@@ -2,7 +2,9 @@
 
 Configured once at app import time (see :mod:`tavolo.app`). By default a
 single console handler at DEBUG level is installed, formatting records as
-``{asctime} [{levelname}] ({processName}/{threadName}) - {name} - {message}``.
+``{asctime} [{levelname}] ({processName}/{threadName}) - {name} - {message}``;
+``urllib3.connectionpool`` is capped at INFO so its per-request DEBUG
+chatter does not drown the log.
 Point the ``LOGGING_CONFIG`` environment variable at a YAML file to take
 over the configuration entirely; the file follows the
 :data:`logging.config.dictConfig` schema, e.g.::
@@ -55,6 +57,13 @@ DEFAULT_CONFIG = {
         "level": "DEBUG",
         "handlers": ["console"],
     },
+    "loggers": {
+        # Every pooled HTTP request is a DEBUG record; keep the logger's
+        # INFO+ output, drop the per-connection noise.
+        "urllib3.connectionpool": {
+            "level": "INFO",
+        },
+    },
 }
 
 

server/packages/tavolo-app/src/tavolo/telemetry.py

@@ -0,0 +1,375 @@
+"""OpenTelemetry metrics and log export beyond kaya-otel.
+
+kaya-otel instruments HTTP requests and websockets with traces and HTTP
+metrics; this module adds what it does not cover, all behind the optional
+``otel`` extra (OpenTelemetry imports are lazy, so default installs and
+the test suite never need them):
+
+* application gauges: ``tavolo.active_users`` (sessions held in the
+  session store) and ``tavolo.ongoing_games`` (live matches that have not
+  finished yet);
+* process metrics through ``opentelemetry-instrumentation-system-metrics``:
+  CPU time/utilization, memory usage and CPython garbage-collection
+  counters;
+* OTLP log export through a stdlib :class:`logging.Handler` attached to
+  the root logger, mirroring what the console sees;
+* session/user tagging of request and websocket spans through
+  :func:`session_tag_hook` (kaya-otel's response/close hooks), so traces
+  can be correlated with a session (hashed id) and an OIDC user.
+
+The store counts are asynchronous while OpenTelemetry instrument
+callbacks are synchronous, so :class:`TelemetryMixin` polls the stores on
+a background task and its callbacks report the cached values.
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+from dataclasses import dataclass
+from logging import getLogger
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union
+
+from kaya.core import KayaApp, KayaMixin
+from kaya.session import InMemorySessionStore, SessionStore
+from kaya.session.redis import RedisSessionStore
+from redis.asyncio import Redis
+from tavolo.platform.auth import session_user
+from tavolo.platform.store import GameStore
+
+from .config import Settings
+
+if TYPE_CHECKING:
+    from opentelemetry.sdk._logs import LoggerProvider
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.trace import TracerProvider
+
+log = getLogger(__name__)
+
+# Session keys live under kaya's default prefix. Keeping it explicit here
+# makes the Redis count scan exact and preserves existing sessions.
+SESSION_KEY_PREFIX = "kaya:session:"
+
+# The interpreter metrics to export. The instrumentation package can also
+# emit host-level ``system.*`` metrics; those are deliberately left off:
+# the application cares about its own process, and per-CPU host metrics
+# add cardinality without context.
+#
+# ``process.cpu.utilization`` ignores its configuration value upstream
+# (the callback always emits one aggregate observation), so its ``None``
+# is only for readability.
+PROCESS_METRICS_CONFIG: Dict[str, Optional[list]] = {
+    "process.cpu.time": ["user", "system"],
+    "process.cpu.utilization": None,
+    "process.memory.usage": None,
+    "process.memory.virtual": None,
+    "cpython.gc.collections": None,
+    "cpython.gc.collected_objects": None,
+    "cpython.gc.uncollectable_objects": None,
+}
+
+
+def otel_headers(settings: Settings) -> Optional[Dict[str, str]]:
+    """Parse ``OTEL_EXPORTER_OTLP_HEADERS`` into a mapping (or ``None``)."""
+    headers = dict(
+        pair.split("=", 1)
+        for pair in (settings.otel_exporter_headers or ())
+        if "=" in pair
+    )
+    return headers or None
+
+
+def _signal_endpoint(base: Optional[str], signal: str) -> Optional[str]:
+    """``{base}/v1/<signal>``, or ``None`` for the exporter's own default."""
+    return f"{base}/{signal}" if base else None
+
+
+def session_tag_hook(span: Any, carrier: Any) -> None:
+    """Tag an HTTP request/websocket span with the request's session/user.
+
+    Wired into kaya-otel as its ``server_response_hook`` and
+    ``websocket_close_hook``: those run after the session mixin's after
+    hook has persisted (and, at login, minted) the session, so the final
+    session id is visible here.
+
+    The session id is the session cookie, i.e. a credential, so only a
+    truncated SHA-256 of it is exported; session ids are
+    ``secrets.token_urlsafe(32)`` (256 bits), which makes the digest
+    irreversible in practice. The OIDC ``sub`` is a pseudonymous
+    identifier already persisted in Postgres and served by the API, so it
+    is exported verbatim as ``user.id`` (OpenTelemetry's current end-user
+    attribute; ``enduser.id`` is PII-flagged and being superseded).
+    """
+    session = getattr(carrier, "session", None)
+    if session is None:
+        return
+    session_id = getattr(session, "id", None)
+    if session_id:
+        span.set_attribute(
+            "session.id",
+            hashlib.sha256(session_id.encode()).hexdigest()[:16],
+        )
+    user = session_user(session)
+    if user is not None:
+        sub = user.get("sub")
+        if sub:
+            span.set_attribute("user.id", str(sub))
+
+
+class _NoOtelLogs(logging.Filter):
+    """Drop OpenTelemetry's own log records.
+
+    Export failures are logged by the SDK; forwarding those through the
+    same exporter would feed an endless retry loop.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not record.name.startswith("opentelemetry")
+
+
+class CountingInMemorySessionStore(InMemorySessionStore):
+    """In-memory session store that can report its live session count."""
+
+    async def count(self) -> int:
+        now = self._clock()
+        return sum(
+            1
+            for session_id in self._data
+            if session_id not in self._expires
+            or self._expires[session_id] > now
+        )
+
+
+class CountingRedisSessionStore(RedisSessionStore):
+    """Redis session store that can report its live session count."""
+
+    def __init__(self, client: Redis, prefix: str = SESSION_KEY_PREFIX) -> None:
+        super().__init__(client, prefix=prefix)
+
+    async def count(self) -> int:
+        total = 0
+        async for _ in self._client.scan_iter(match=f"{self._prefix}*", count=500):
+            total += 1
+        return total
+
+
+# The session stores the application builds: both expose ``count()`` on top
+# of kaya's ``SessionStore`` interface. Game stores need no alias — the
+# platform's ``GameStore`` declares ``count_ongoing()`` itself.
+CountableSessionStore = Union[CountingInMemorySessionStore, CountingRedisSessionStore]
+
+
+class TelemetryMixin(KayaMixin):
+    """Application gauges, DB instrumentation and log export.
+
+    The meter, tracer and logger providers are built by
+    :func:`telemetry_from_settings` and injected: kaya-otel only shuts
+    down providers it created itself, so this mixin owns their shutdown
+    (and uninstruments the database clients it instrumented).
+    """
+
+    def __init__(
+        self,
+        *,
+        meter_provider: "MeterProvider",
+        tracer_provider: "TracerProvider",
+        logger_provider: Optional["LoggerProvider"],
+        log_handler: Optional[logging.Handler],
+        session_store: CountableSessionStore,
+        game_store: GameStore,
+        poll_interval_seconds: float,
+    ) -> None:
+        self._meter_provider = meter_provider
+        self._tracer_provider = tracer_provider
+        self._logger_provider = logger_provider
+        self._log_handler = log_handler
+        self._session_store = session_store
+        self._game_store = game_store
+        self._poll_interval = poll_interval_seconds
+        self._active_users: Optional[int] = None
+        self._ongoing_games: Optional[int] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._instrumentor: Optional[Any] = None
+        self._db_instrumentors: list = []
+
+    def apply(self, app: KayaApp) -> None:
+        from opentelemetry.instrumentation.asyncpg import AsyncPGInstrumentor
+        from opentelemetry.instrumentation.redis import RedisInstrumentor
+        from opentelemetry.instrumentation.system_metrics import (
+            SystemMetricsInstrumentor,
+        )
+        from opentelemetry.metrics import CallbackOptions, Observation
+
+        instrumentor = SystemMetricsInstrumentor(config=PROCESS_METRICS_CONFIG)
+        self._instrumentor = instrumentor
+        instrumentor.instrument(meter_provider=self._meter_provider)
+
+        # Query spans for the Postgres (asyncpg, used by Tortoise) and Redis
+        # clients. Redis command values are redacted by the instrumentation
+        # (``SET ? ?``); asyncpg spans carry the parameterized SQL only.
+        self._db_instrumentors = [
+            AsyncPGInstrumentor(capture_parameters=False),
+            RedisInstrumentor(),
+        ]
+        for db_instrumentor in self._db_instrumentors:
+            db_instrumentor.instrument(tracer_provider=self._tracer_provider)
+
+        meter = self._meter_provider.get_meter(__name__)
+
+        def active_users(options: CallbackOptions):
+            if self._active_users is not None:
+                yield Observation(self._active_users)
+
+        def ongoing_games(options: CallbackOptions):
+            if self._ongoing_games is not None:
+                yield Observation(self._ongoing_games)
+
+        meter.create_observable_gauge(
+            "tavolo.active_users",
+            callbacks=[active_users],
+            unit="{user}",
+            description="Sessions currently held in the session store.",
+        )
+        meter.create_observable_gauge(
+            "tavolo.ongoing_games",
+            callbacks=[ongoing_games],
+            unit="{game}",
+            description="Live games that have not finished yet.",
+        )
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def setup(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._poll_task = loop.create_task(self._poll())
+
+    def shutdown(self, loop: asyncio.AbstractEventLoop) -> None:
+        if self._poll_task is not None:
+            self._poll_task.cancel()
+            self._poll_task = None
+        for db_instrumentor in self._db_instrumentors:
+            db_instrumentor.uninstrument()
+        self._db_instrumentors = []
+        if self._log_handler is not None:
+            logging.getLogger().removeHandler(self._log_handler)
+            self._log_handler.close()
+            self._log_handler = None
+        if self._logger_provider is not None:
+            self._logger_provider.shutdown()
+        self._tracer_provider.shutdown()
+        self._meter_provider.shutdown()
+
+    async def _poll(self) -> None:
+        while True:
+            await self.refresh_counts()
+            await asyncio.sleep(self._poll_interval)
+
+    async def refresh_counts(self) -> None:
+        """Refresh the cached store counts (the poll loop calls this)."""
+        try:
+            self._active_users = await self._session_store.count()
+        except Exception:
+            log.warning("active_users refresh failed", exc_info=True)
+        try:
+            self._ongoing_games = await self._game_store.count_ongoing()
+        except Exception:
+            log.warning("ongoing_games refresh failed", exc_info=True)
+
+
+@dataclass
+class Telemetry:
+    """The providers and mixin built from the ``OTEL_*`` settings."""
+
+    meter_provider: "MeterProvider"
+    tracer_provider: "TracerProvider"
+    logger_provider: Optional["LoggerProvider"]
+    log_handler: Optional[logging.Handler]
+    mixin: TelemetryMixin
+
+
+def telemetry_from_settings(
+    settings: Settings,
+    session_store: CountableSessionStore,
+    game_store: GameStore,
+) -> Optional[Telemetry]:
+    """Build the metric/trace/log providers, or ``None`` when telemetry is off.
+
+    Only called when ``OTEL_ENABLED`` is set; the OpenTelemetry imports
+    are lazy so the default install does not need the ``otel`` extra.
+    """
+    if not settings.otel_enabled:
+        return None
+    try:
+        from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+            OTLPLogExporter,
+        )
+        from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+            OTLPMetricExporter,
+        )
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+        from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+        from opentelemetry.sdk.metrics import MeterProvider
+        from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    except ImportError as exc:
+        raise RuntimeError(
+            "OTEL_ENABLED is set but the OpenTelemetry dependencies are not "
+            "installed; install tavolo-app with the 'otel' extra"
+        ) from exc
+
+    endpoint = settings.otel_exporter_endpoint
+    headers = otel_headers(settings)
+    resource = Resource.create({"service.name": settings.otel_service_name})
+    tracer_provider = TracerProvider(resource=resource)
+    tracer_provider.add_span_processor(
+        BatchSpanProcessor(
+            OTLPSpanExporter(
+                endpoint=_signal_endpoint(endpoint, "v1/traces"),
+                headers=headers,
+            )
+        )
+    )
+    meter_provider = MeterProvider(
+        resource=resource,
+        metric_readers=[
+            PeriodicExportingMetricReader(
+                OTLPMetricExporter(
+                    endpoint=_signal_endpoint(endpoint, "v1/metrics"),
+                    headers=headers,
+                ),
+                export_interval_millis=settings.otel_metric_export_interval_millis,
+            )
+        ],
+    )
+    logger_provider = LoggerProvider(resource=resource)
+    logger_provider.add_log_record_processor(
+        BatchLogRecordProcessor(
+            OTLPLogExporter(
+                endpoint=_signal_endpoint(endpoint, "v1/logs"),
+                headers=headers,
+            )
+        )
+    )
+    handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider)
+    handler.addFilter(_NoOtelLogs())
+    logging.getLogger().addHandler(handler)
+    mixin = TelemetryMixin(
+        meter_provider=meter_provider,
+        tracer_provider=tracer_provider,
+        logger_provider=logger_provider,
+        log_handler=handler,
+        session_store=session_store,
+        game_store=game_store,
+        poll_interval_seconds=settings.otel_metrics_poll_interval_seconds,
+    )
+    return Telemetry(
+        meter_provider=meter_provider,
+        tracer_provider=tracer_provider,
+        logger_provider=logger_provider,
+        log_handler=handler,
+        mixin=mixin,
+    )

server/packages/tavolo-briscola/README.md

@@ -0,0 +1,58 @@
+# tavolo-briscola
+
+Briscola — the Italian trick-taking game — as a
+[`tavolo-platform`](../tavolo-platform/README.md) game implementation.
+Two variants share one rules core:
+
+- `briscola` — the classic two-player game;
+- `briscola_a_quattro` — four-player fixed-partnership briscola.
+
+## Contents
+
+- `state.py` — `BriscolaState` (pure game data: phases, players, hands,
+  stock, face-up briscola, tricks, scores, deadlines), `PlayerState`,
+  `Card`, `TrickCard`, `Trick`, with JSON (de)serialization. No session
+  envelope, no transport, no I/O.
+- `engine.py` — the pure rules engine: deck, deals, trick resolution
+  (trump first, then the led suit; strength ace > three > king > horse >
+  jack > 7 > 6 > 5 > 4 > 2), the draw order (trick winner first, the
+  face-up briscola last), card points (ace 11, three 10, king 4, horse 3,
+  jack 2), patta re-deals and the target-score match end, deal-end
+  acknowledgements and auto-play. Deterministic and I/O-free apart from
+  logging, so the whole rule set is unit-testable.
+- `errors.py` — briscola-specific errors (`CardNotInHand`); every other
+  failure mode is a shared `tavolo.platform.errors` subclass.
+- `plugin.py` — `BriscolaEngine` and `BriscolaQuattroEngine`
+  (`GameEngine`): the platform-facing adapters. They validate the
+  `target_score` creation option (61–120, default 61) and extract the
+  `MatchResult` (teams, winner, per-player scores and the match summary
+  persisted as the match's JSON `result`).
+
+Timeouts are constructor arguments (`turn_timeout_seconds`,
+`hand_ack_timeout_seconds`), wired from the environment by the
+application composition root.
+
+## Rules
+
+- Three cards per player; the next card is turned face up: its suit is
+  the trump (briscola) for the deal and it is the last card drawn.
+- The winner of a trick is the highest trump, or the highest card of the
+  led suit when no trump was played. The winner takes the trick and leads
+  the next one.
+- After each trick everyone draws back up to three cards, starting with
+  the trick winner.
+- Card points total 120 per deal; a 60–60 deal is a *patta*, its points
+  are discarded and the deal is replayed. The first team to the target
+  score wins; a tie at or above the target is broken by another deal.
+- Between deals of an unfinished match every player acknowledges the
+  summary (or the hand-end timeout deals on), exactly like scopone.
+
+## Development (from `server/`)
+
+```sh
+.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
+.venv/bin/python -m mypy -p tavolo.briscola
+```
+
+`test_engine.py` covers the pure rules; `test_plugin.py` covers the
+platform contract (actions, deadlines, serialization, results).

server/packages/tavolo-briscola/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tavolo-briscola"
+version = "0.1.0"
+description = "Briscola game implementation for the tavolo platform"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "tavolo-platform",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+plugins = []

server/packages/tavolo-briscola/src/tavolo/briscola/__init__.py

@@ -0,0 +1,20 @@
+"""Briscola: tavolo's trick-taking game implementation.
+
+Two variants share the same rules core and platform adapter:
+
+- :class:`~tavolo.briscola.plugin.BriscolaEngine` — classic two-player
+  briscola (``briscola``);
+- :class:`~tavolo.briscola.plugin.BriscolaQuattroEngine` — four-player
+  fixed-partnership briscola a quattro (``briscola_a_quattro``).
+
+The pure rules (:mod:`tavolo.briscola.engine`,
+:mod:`tavolo.briscola.state`) know nothing about HTTP, Redis or Postgres;
+:mod:`tavolo.briscola.plugin` adapts them to the platform's
+:class:`~tavolo.platform.engine.GameEngine` contract so the
+game-independent platform can host them.
+"""
+from __future__ import annotations
+
+from .plugin import BriscolaEngine, BriscolaQuattroEngine
+
+__all__ = ["BriscolaEngine", "BriscolaQuattroEngine"]

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

@@ -0,0 +1,469 @@
+"""Pure rules engine for briscola.
+
+Every function here is deterministic and I/O-free (the only side effect is
+logging): it mutates (or reads)
+:class:`~tavolo.briscola.state.BriscolaState` and raises
+:class:`~tavolo.platform.errors.GameError` subclasses on rule violations.
+This makes the whole rule set unit-testable without Redis, Postgres or
+HTTP. The platform-facing adapter is
+:class:`~tavolo.briscola.plugin.BriscolaEngine`.
+
+Rules implemented
+-----------------
+* 40-card Italian deck (4 suits x ranks 1-10), three cards per player.
+* The next card after the deal is turned face up: its suit is the
+  **briscola** (trump) for the whole deal, and it is the last card drawn
+  from the stock (the stock is drawn from the bottom up).
+* Trick play: the player to the dealer's left leads; each other player
+  plays one card. The highest trump wins; when no trump was played, the
+  highest card of the led suit wins. The winner takes the trick and leads
+  the next one.
+* After each trick every player draws back up to three cards, starting
+  with the trick winner and continuing in turn order; the face-up
+  briscola card is drawn last, so whoever's turn to draw when only it
+  remains takes it.
+* Card points: ace 11, three 10, king 4, horse 3, jack 2, everything else
+  0 — 120 points per deal. Trick strength is unrelated to points:
+  ace > three > king > horse > jack > 7 > 6 > 5 > 4 > 2.
+* Match points accumulate across deals. A 60-60 deal is a **patta**: its
+  points are discarded and the deal is replayed (the dealer rotates).
+  The first team to reach the target score (default 61) wins; a tie at or
+  above the target is broken by another deal.
+* Between deals of an unfinished match the game pauses in the
+  ``hand_end`` phase for the deal summary, exactly like scopone: every
+  player acknowledges (or the hand-end timeout elapses) before the next
+  deal.
+"""
+from __future__ import annotations
+
+import random
+from datetime import datetime, timedelta, timezone
+from logging import getLogger
+from typing import Any, Dict, List, Optional, Tuple
+
+from tavolo.platform.errors import (
+    AlreadyJoined,
+    GameFinished,
+    GameNotStarted,
+    IllegalMove,
+    LobbyFull,
+    NotYourTurn,
+)
+
+from .errors import CardNotInHand
+
+from .state import (
+    DEFAULT_HAND_ACK_TIMEOUT_SECONDS,
+    DEFAULT_TARGET_SCORE,
+    DEFAULT_TURN_TIMEOUT_SECONDS,
+    HAND_SIZE,
+    MAX_TARGET_SCORE,
+    MIN_TARGET_SCORE,
+    PHASE_FINISHED,
+    PHASE_HAND_END,
+    PHASE_LOBBY,
+    PHASE_PLAYING,
+    PLAYER_COUNTS,
+    SUITS,
+    TEAM_NAMES,
+    BriscolaState,
+    Card,
+    PlayerState,
+    Trick,
+    TrickCard,
+    parse_card,
+)
+
+log = getLogger(__name__)
+
+# Trick strength: higher wins. Ace > three > king > horse > jack, then the
+# remaining ranks in descending order. All ranks are distinct within a
+# suit, so a trick never ties.
+TRICK_STRENGTH: Dict[int, int] = {
+    1: 9,
+    3: 8,
+    10: 7,
+    9: 6,
+    8: 5,
+    7: 4,
+    6: 3,
+    5: 2,
+    4: 1,
+    2: 0,
+}
+
+# Card points: 120 per deal in total.
+CARD_POINTS: Dict[int, int] = {
+    1: 11,
+    3: 10,
+    10: 4,
+    9: 3,
+    8: 2,
+}
+
+_rng = random.SystemRandom()
+
+
+def full_deck() -> List[Card]:
+    """Return the 40 cards of the Italian deck in canonical order."""
+    return [Card(rank=rank, suit=suit) for suit in SUITS for rank in range(1, 11)]
+
+
+def shuffled_deck(rng: Optional[random.Random] = None) -> List[Card]:
+    """Return a shuffled deck. Pass ``rng`` for deterministic tests."""
+    deck = full_deck()
+    (rng or _rng).shuffle(deck)
+    return deck
+
+
+def card_points(card: Card) -> int:
+    """The point value of a single card."""
+    return CARD_POINTS.get(card.rank, 0)
+
+
+def create_game(
+    creator_sub: str,
+    creator_name: str,
+    player_count: int = 2,
+    target_score: int = DEFAULT_TARGET_SCORE,
+    hand_ack_timeout: int = DEFAULT_HAND_ACK_TIMEOUT_SECONDS,
+    turn_timeout: int = DEFAULT_TURN_TIMEOUT_SECONDS,
+) -> BriscolaState:
+    """Create a lobby game with the creator seated first."""
+    if player_count not in PLAYER_COUNTS:
+        raise IllegalMove(f"player_count must be one of {PLAYER_COUNTS}")
+    if (
+        isinstance(target_score, bool)
+        or not isinstance(target_score, int)
+        or target_score < MIN_TARGET_SCORE
+        or target_score > MAX_TARGET_SCORE
+    ):
+        raise IllegalMove(
+            f"target_score must be between {MIN_TARGET_SCORE} and {MAX_TARGET_SCORE}"
+        )
+    return BriscolaState(
+        player_count=player_count,
+        target_score=target_score,
+        phase=PHASE_LOBBY,
+        players=[PlayerState(sub=creator_sub, name=creator_name, seat=0)],
+        hand_ack_timeout=hand_ack_timeout,
+        turn_timeout=turn_timeout,
+    )
+
+
+def join_game(state: BriscolaState, sub: str, name: str) -> None:
+    """Seat ``sub`` in the next free chair, starting the match when full."""
+    if state.phase != PHASE_LOBBY:
+        raise GameNotStarted("game has already started")
+    if state.seated(sub):
+        raise AlreadyJoined("already joined this game")
+    if len(state.players) >= state.player_count:
+        raise LobbyFull("game is full")
+    seat = len(state.players)
+    state.players.append(PlayerState(sub=sub, name=name, seat=seat))
+    if len(state.players) == state.player_count:
+        start_game(state)
+
+
+def start_game(state: BriscolaState) -> None:
+    """Deal the first hand and switch the game to playing."""
+    if len(state.players) != state.player_count:
+        raise GameNotStarted(
+            f"need exactly {state.player_count} players to start"
+        )
+    state.phase = PHASE_PLAYING
+    _deal(state)
+
+
+def _set_turn_deadline(state: BriscolaState) -> None:
+    """Arm the auto-play deadline for whoever is on turn."""
+    deadline = datetime.now(timezone.utc) + timedelta(seconds=state.turn_timeout)
+    state.turn_deadline = deadline.isoformat()
+
+
+def _deal(state: BriscolaState) -> None:
+    deck = shuffled_deck()
+    for player in state.players:
+        player.hand = []
+        player.captured = []
+    state.trick = []
+    state.last_trick = None
+    state.briscola_card = None
+    # Dealer rotates each deal; the first card is played by the player to
+    # the dealer's left.
+    state.turn = (state.dealer + 1) % state.player_count
+    state.trick_leader = state.turn
+    for _ in range(HAND_SIZE):
+        for offset in range(state.player_count):
+            player = _player_at(
+                state, (state.dealer + 1 + offset) % state.player_count
+            )
+            player.hand.append(deck.pop())
+    # The turned-up card is the last card drawn: keep it separate from the
+    # face-down stock and hand it out once the stock is exhausted.
+    state.briscola_card = deck.pop()
+    state.briscola_suit = state.briscola_card.suit
+    state.stock = deck
+    _set_turn_deadline(state)
+    log.debug(
+        "deal %d dealt (dealer seat %d, briscola %s)",
+        state.hand_number,
+        state.dealer,
+        state.briscola_card.code,
+    )
+
+
+def _player_at(state: BriscolaState, seat: int) -> PlayerState:
+    for player in state.players:
+        if player.seat == seat:
+            return player
+    raise IllegalMove(f"no player in seat {seat}")
+
+
+def play(state: BriscolaState, sub: str, card_code: str) -> None:
+    """Apply one move by the player identified by ``sub``.
+
+    Any card in hand is a legal play; only turn order and phase are
+    validated. Raises a :class:`~tavolo.platform.errors.GameError`
+    subclass on any violation.
+    """
+    if state.phase == PHASE_FINISHED:
+        raise GameFinished("the match is over")
+    if state.phase == PHASE_HAND_END:
+        raise IllegalMove("the deal is over; acknowledge the summary to continue")
+    if state.phase != PHASE_PLAYING:
+        raise GameNotStarted("the game has not started yet")
+
+    player = state.player_for(sub)
+    if player is None or player.seat != state.turn:
+        raise NotYourTurn("it is not your turn")
+
+    card = parse_card(card_code)
+    if card not in player.hand:
+        raise CardNotInHand(f"card {card.code} is not in your hand")
+
+    player.hand.remove(card)
+    state.trick.append(TrickCard(seat=player.seat, card=card.code))
+    log.debug(
+        "deal %d: seat %d played %s (%d/%d in the trick)",
+        state.hand_number,
+        player.seat,
+        card.code,
+        len(state.trick),
+        state.player_count,
+    )
+
+    if len(state.trick) == state.player_count:
+        _resolve_trick(state)
+    else:
+        state.turn = (state.turn + 1) % state.player_count
+        _set_turn_deadline(state)
+
+
+def _resolve_trick(state: BriscolaState) -> None:
+    """Score the completed trick, draw and hand the lead to the winner."""
+    winner = _trick_winner(state)
+    taken = [parse_card(t.card) for t in state.trick]
+    _player_at(state, winner).captured.extend(taken)
+    state.last_trick = Trick(winner=winner, cards=list(state.trick))
+    state.trick = []
+    state.trick_leader = winner
+    state.turn = winner
+    log.debug(
+        "deal %d: seat %d takes the trick with %s",
+        state.hand_number,
+        winner,
+        [t.card for t in state.last_trick.cards],
+    )
+
+    if all(not player.hand for player in state.players):
+        _end_deal(state)
+        return
+    _draw(state, winner)
+    _set_turn_deadline(state)
+
+
+def _trick_winner(state: BriscolaState) -> int:
+    """The seat winning the current (complete) trick."""
+    played = [(t.seat, parse_card(t.card)) for t in state.trick]
+    leader_suit = played[0][1].suit
+    trumps = [(seat, card) for seat, card in played if card.suit == state.briscola_suit]
+    pool = trumps or [
+        (seat, card) for seat, card in played if card.suit == leader_suit
+    ]
+    return max(pool, key=lambda item: TRICK_STRENGTH[item[1].rank])[0]
+
+
+def _draw(state: BriscolaState, winner: int) -> None:
+    """Draw back up to ``HAND_SIZE`` cards, winner first, then turn order."""
+    for offset in range(state.player_count):
+        player = _player_at(state, (winner + offset) % state.player_count)
+        if state.stock:
+            player.hand.append(state.stock.pop())
+        elif state.briscola_card is not None:
+            # The face-up briscola is the last card of the stock: the first
+            # player who needs a card when only it remains takes it.
+            player.hand.append(state.briscola_card)
+            state.briscola_card = None
+
+
+def auto_play(state: BriscolaState, rng: Optional[random.Random] = None) -> None:
+    """Play a random card for the player currently on turn.
+
+    Every card in hand is legal, so one is drawn at random. Delegates to
+    :func:`play`, so the move is fully validated and can end the deal or
+    the match. Pass ``rng`` for deterministic tests.
+    """
+    if state.phase != PHASE_PLAYING:
+        raise GameNotStarted("the game has not started yet")
+    player = _player_at(state, state.turn)
+    if not player.hand:
+        raise IllegalMove("the player on turn has no cards")
+    chooser = rng or _rng
+    card = chooser.choice(player.hand)
+    play(state, player.sub, card.code)
+
+
+def _end_deal(state: BriscolaState) -> None:
+    """Score the deal and either finish the match or pause for the summary.
+
+    A 60-60 deal is a patta: its points do not count and the deal is
+    replayed. If the match continues, the game pauses in the ``hand_end``
+    phase so every player can read the summary; the next deal is dealt by
+    :func:`acknowledge_hand` once all players have acknowledged (or by the
+    hand-end timeout fired by the platform's deadline scheduler).
+    """
+    state.turn_deadline = None
+    points, details = deal_points(state)
+    patta = points[0] == points[1]
+    if not patta:
+        state.scores[0] += points[0]
+        state.scores[1] += points[1]
+    entry: Dict[str, Any] = {
+        "deal": state.hand_number,
+        "patta": patta,
+        "points": details["points"],
+        "cards": details["cards"],
+        "totals": {"A": state.scores[0], "B": state.scores[1]},
+    }
+    state.hand_scores.append(entry)
+
+    a, b = state.scores
+    log.debug(
+        "deal %d scored A+%d B+%d%s (totals %d-%d)",
+        state.hand_number,
+        points[0],
+        points[1],
+        " patta" if patta else "",
+        a,
+        b,
+    )
+    if not patta and max(a, b) >= state.target_score and a != b:
+        state.phase = PHASE_FINISHED
+        state.winner = 0 if a > b else 1
+        log.info("match ended, team %s wins", TEAM_NAMES[state.winner])
+        return
+
+    # Pause for the deal summary instead of dealing immediately.
+    state.phase = PHASE_HAND_END
+    state.acked = []
+    deadline = datetime.now(timezone.utc) + timedelta(seconds=state.hand_ack_timeout)
+    state.hand_end_deadline = deadline.isoformat()
+
+
+def acknowledge_hand(state: BriscolaState, sub: str) -> None:
+    """Record that ``sub`` has read the deal summary.
+
+    When every player has acknowledged, the next deal is dealt.
+    Acknowledging twice is a no-op; acknowledging outside the ``hand_end``
+    phase raises an error.
+    """
+    if state.phase != PHASE_HAND_END:
+        raise IllegalMove("no deal summary is waiting for acknowledgement")
+    player = state.player_for(sub)
+    if player is None:
+        raise NotYourTurn("you are not seated in this game")
+    if player.seat in state.acked:
+        return
+    state.acked.append(player.seat)
+    if len(state.acked) < state.player_count:
+        return
+
+    state.hand_number += 1
+    state.dealer = (state.dealer + 1) % state.player_count
+    state.acked = []
+    state.hand_end_deadline = None
+    state.phase = PHASE_PLAYING
+    _deal(state)
+
+
+def deal_points(state: BriscolaState) -> Tuple[List[int], Dict[str, object]]:
+    """Compute the deal points for both teams (index 0 = team A)."""
+    piles: List[List[Card]] = [[], []]
+    for player in state.players:
+        piles[player.team].extend(player.captured)
+    points = [
+        sum(card_points(card) for card in pile) for pile in piles
+    ]
+    details: Dict[str, object] = {
+        "points": {"A": points[0], "B": points[1]},
+        "cards": {"A": len(piles[0]), "B": len(piles[1])},
+    }
+    return points, details
+
+
+def state_for_player(state: BriscolaState, sub: Optional[str]) -> Dict[str, object]:
+    """Serialize ``state`` hiding other players' hands.
+
+    Hands are reduced to a count, except for the requesting player's own
+    hand. Non-seated viewers — including spectators, for whom ``sub`` is
+    ``None`` — simply see no hand at all. The platform merges the session
+    envelope (``id``, ``join_code`` for seated players, ``game_type``,
+    ``spectator``) into the view itself.
+    """
+    viewer = state.player_for(sub)
+    players: List[Dict[str, object]] = []
+    for player in state.players:
+        view: Dict[str, object] = {
+            "sub": player.sub,
+            "name": player.name,
+            "seat": player.seat,
+            "team": TEAM_NAMES[player.team],
+            "cards_left": len(player.hand),
+            "captured_count": len(player.captured),
+            "points": sum(card_points(card) for card in player.captured),
+        }
+        if viewer is not None and viewer.seat == player.seat:
+            view["hand"] = [c.code for c in player.hand]
+        players.append(view)
+
+    payload: Dict[str, object] = {
+        "phase": state.phase,
+        "target_score": state.target_score,
+        "player_count": state.player_count,
+        "hand_number": state.hand_number,
+        "dealer": state.dealer,
+        "turn": state.turn,
+        "scores": {"A": state.scores[0], "B": state.scores[1]},
+        "winner": None if state.winner is None else TEAM_NAMES[state.winner],
+        "briscola_suit": state.briscola_suit,
+        "briscola_card": (
+            state.briscola_card.code if state.briscola_card is not None else None
+        ),
+        "stock_count": len(state.stock),
+        "trick": [t.to_json() for t in state.trick],
+        "trick_leader": state.trick_leader,
+        "last_trick": state.last_trick.to_json() if state.last_trick else None,
+        "players": players,
+        "last_deal": state.hand_scores[-1] if state.hand_scores else None,
+        "acknowledged": list(state.acked),
+        "hand_end_deadline": state.hand_end_deadline,
+        "turn_deadline": state.turn_deadline,
+    }
+    if (
+        viewer is not None
+        and state.phase == PHASE_PLAYING
+        and viewer.seat == state.turn
+    ):
+        payload["your_turn"] = True
+    return payload

server/packages/tavolo-briscola/src/tavolo/briscola/errors.py

@@ -0,0 +1,34 @@
+"""Briscola errors.
+
+Most failure modes are game-independent and live in
+:mod:`tavolo.platform.errors`; only genuinely briscola-specific errors
+are defined here.
+"""
+from __future__ import annotations
+
+from tavolo.platform.errors import (
+    AlreadyJoined,
+    GameError,
+    GameFinished,
+    GameNotFound,
+    GameNotStarted,
+    IllegalMove,
+    LobbyFull,
+    NotYourTurn,
+)
+
+__all__ = [
+    "AlreadyJoined",
+    "CardNotInHand",
+    "GameError",
+    "GameFinished",
+    "GameNotFound",
+    "GameNotStarted",
+    "IllegalMove",
+    "LobbyFull",
+    "NotYourTurn",
+]
+
+
+class CardNotInHand(GameError):
+    """The played card is not held by the player."""

server/packages/tavolo-briscola/src/tavolo/briscola/plugin.py

@@ -0,0 +1,279 @@
+"""The platform-facing adapter for briscola.
+
+Two :class:`~tavolo.platform.engine.GameEngine` implementations share one
+rules core (:mod:`tavolo.briscola.engine`): classic two-player
+:class:`BriscolaEngine` and four-player fixed-partnership
+:class:`BriscolaQuattroEngine`. They translate platform calls (create,
+join, websocket actions, deadlines) into rules-engine calls and back,
+keeping all briscola knowledge inside this package. Nothing outside
+``tavolo.briscola`` needs to know about phases, tricks or deal scoring.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from logging import getLogger
+from typing import Any, Dict, Mapping, Optional
+
+from tavolo.platform.engine import (
+    Deadline,
+    GameEngine,
+    GameSession,
+    MatchResult,
+    PlayerResult,
+    Seat,
+)
+from tavolo.platform.errors import GameError, IllegalMove
+
+from . import engine
+from .state import (
+    DEFAULT_HAND_ACK_TIMEOUT_SECONDS,
+    DEFAULT_TARGET_SCORE,
+    DEFAULT_TURN_TIMEOUT_SECONDS,
+    MAX_TARGET_SCORE,
+    MIN_TARGET_SCORE,
+    PHASE_FINISHED,
+    PHASE_HAND_END,
+    PHASE_LOBBY,
+    PHASE_PLAYING,
+    TEAM_NAMES,
+    BriscolaState,
+)
+
+log = getLogger(__name__)
+
+
+def _deadline_ms(iso: Optional[str]) -> Optional[int]:
+    """Epoch milliseconds for an ISO-8601 deadline, ``None`` when absent
+    or unparseable."""
+    if not iso:
+        return None
+    try:
+        return int(datetime.fromisoformat(iso).timestamp() * 1000)
+    except ValueError:
+        return None
+
+
+class _BriscolaBase(GameEngine):
+    """Shared platform adapter for the two briscola table sizes."""
+
+    #: 2 (classic) or 4 (fixed partnerships); set by the subclasses.
+    player_count: int
+
+    options_schema = {
+        "type": "object",
+        "properties": {
+            "target_score": {
+                "type": "integer",
+                "minimum": MIN_TARGET_SCORE,
+                "maximum": MAX_TARGET_SCORE,
+                "default": DEFAULT_TARGET_SCORE,
+                "description": "Match points the winning team must reach.",
+            },
+        },
+    }
+
+    def __init__(
+        self,
+        turn_timeout_seconds: int = DEFAULT_TURN_TIMEOUT_SECONDS,
+        hand_ack_timeout_seconds: int = DEFAULT_HAND_ACK_TIMEOUT_SECONDS,
+    ) -> None:
+        self._turn_timeout = turn_timeout_seconds
+        self._hand_ack_timeout = hand_ack_timeout_seconds
+
+    # -- lobby ------------------------------------------------------------
+
+    def create(self, session: GameSession, options: Mapping[str, Any]) -> None:
+        target_score = options.get("target_score", DEFAULT_TARGET_SCORE)
+        if isinstance(target_score, bool) or not isinstance(target_score, int):
+            raise IllegalMove("target_score must be an integer")
+        creator = session.players[0]
+        session.state = engine.create_game(
+            creator_sub=creator.user_sub,
+            creator_name=creator.display_name,
+            player_count=self.player_count,
+            target_score=target_score,
+            hand_ack_timeout=self._hand_ack_timeout,
+            turn_timeout=self._turn_timeout,
+        )
+        # The creator takes seat 0, i.e. team A.
+        session.players[0] = Seat(
+            user_sub=creator.user_sub,
+            display_name=creator.display_name,
+            team=TEAM_NAMES[0],
+        )
+
+    def join(self, session: GameSession, user_sub: str, display_name: str) -> None:
+        seat = len(session.players)
+        engine.join_game(session.state, user_sub, display_name)
+        # join_game raises before appending on any violation, so the seat
+        # list stays in sync with the engine's players.
+        session.players.append(
+            Seat(
+                user_sub=user_sub,
+                display_name=display_name,
+                team=TEAM_NAMES[seat % 2],
+            )
+        )
+
+    def in_lobby(self, session: GameSession) -> bool:
+        return session.state.phase == PHASE_LOBBY
+
+    def lobby_view(self, session: GameSession) -> Dict[str, Any]:
+        state: BriscolaState = session.state
+        return {
+            "phase": state.phase,
+            "target_score": state.target_score,
+        }
+
+    # -- play -------------------------------------------------------------
+
+    def handle_action(
+        self, session: GameSession, user_sub: str, action: str, payload: Mapping[str, Any]
+    ) -> None:
+        state: BriscolaState = session.state
+        if action == "play":
+            card = payload.get("card")
+            if not isinstance(card, str):
+                raise IllegalMove("'card' must be a card code string")
+            try:
+                engine.play(state, user_sub, card)
+            except ValueError:
+                raise IllegalMove("invalid card code")
+        elif action == "ack":
+            engine.acknowledge_hand(state, user_sub)
+        else:
+            raise IllegalMove(f"unknown action: {action!r}")
+
+    def view_for(self, session: GameSession, user_sub: Optional[str]) -> Dict[str, Any]:
+        return engine.state_for_player(session.state, user_sub)
+
+    def is_finished(self, session: GameSession) -> bool:
+        return session.state.phase == PHASE_FINISHED
+
+    def game_over_view(self, session: GameSession, user_sub: Optional[str]) -> Dict[str, Any]:
+        state: BriscolaState = session.state
+        return {
+            "scores": {"A": state.scores[0], "B": state.scores[1]},
+            "winner": None if state.winner is None else TEAM_NAMES[state.winner],
+        }
+
+    # -- (de)serialization -------------------------------------------------
+
+    def state_to_json(self, state: Any) -> Dict[str, Any]:
+        assert isinstance(state, BriscolaState)
+        return state.to_json()
+
+    def state_from_json(self, data: Mapping[str, Any]) -> Any:
+        return BriscolaState.from_json(dict(data))
+
+    # -- deadlines ----------------------------------------------------------
+
+    def next_deadline(self, session: GameSession) -> Optional[Deadline]:
+        state: BriscolaState = session.state
+        if state.phase == PHASE_PLAYING and state.turn_deadline:
+            due_ms = _deadline_ms(state.turn_deadline)
+            if due_ms is None:
+                return None
+            return Deadline(
+                kind="turn",
+                due_at=datetime.fromtimestamp(due_ms / 1000, tz=timezone.utc),
+                token=f"turn:{state.hand_number}:{state.turn}:{due_ms}",
+            )
+        if state.phase == PHASE_HAND_END and state.hand_end_deadline:
+            due_ms = _deadline_ms(state.hand_end_deadline)
+            if due_ms is None:
+                return None
+            return Deadline(
+                kind="hand_end",
+                due_at=datetime.fromtimestamp(due_ms / 1000, tz=timezone.utc),
+                token=f"hand_end:{state.hand_number}:{due_ms}",
+            )
+        return None
+
+    def fire_deadline(self, session: GameSession, kind: str, token: str) -> None:
+        current = self.next_deadline(session)
+        if current is None or current.kind != kind or current.token != token:
+            # Overtaken by events (a play landed in time, the deal was
+            # acknowledged, the deadline moved): nothing to do.
+            raise GameError("stale deadline")
+        state: BriscolaState = session.state
+        if kind == "turn":
+            seat = state.turn
+            engine.auto_play(state)
+            log.info(
+                "auto-played for seat %s (turn timeout, deal %d)",
+                seat,
+                state.hand_number,
+            )
+        elif kind == "hand_end":
+            for player in state.players:
+                engine.acknowledge_hand(state, player.sub)
+            log.info(
+                "deal %d auto-advanced after the acknowledgement timeout",
+                state.hand_number,
+            )
+        else:  # pragma: no cover - next_deadline never emits other kinds
+            raise GameError(f"unknown deadline kind: {kind!r}")
+
+    # -- results -------------------------------------------------------------
+
+    def result(self, session: GameSession) -> MatchResult:
+        state: BriscolaState = session.state
+        if state.winner is None:
+            raise GameError("no result: the match is not finished")
+        teams = [
+            [p.sub for p in state.players if p.team == 0],
+            [p.sub for p in state.players if p.team == 1],
+        ]
+        return MatchResult(
+            teams=teams,
+            winner_team=state.winner,
+            players=[
+                PlayerResult(
+                    user_sub=player.sub,
+                    seat=player.seat,
+                    won=player.team == state.winner,
+                    team=TEAM_NAMES[player.team],
+                    score=float(state.scores[player.team]),
+                    details={"captured_cards": len(player.captured)},
+                )
+                for player in state.players
+            ],
+            summary={
+                "team_a_score": state.scores[0],
+                "team_b_score": state.scores[1],
+                "winner_team": TEAM_NAMES[state.winner],
+                "target_score": state.target_score,
+                "deals_played": state.hand_number,
+                "deal_scores": state.hand_scores,
+            },
+        )
+
+
+class BriscolaEngine(_BriscolaBase):
+    """Classic two-player briscola as a platform game engine."""
+
+    id = "briscola"
+    name = "Briscola"
+    description = (
+        "The classic two-player Italian trick-taking game: three cards "
+        "each, a trump suit and 120 points per deal. First to the target "
+        "score wins."
+    )
+    min_players = 2
+    max_players = 2
+    player_count = 2
+
+
+class BriscolaQuattroEngine(_BriscolaBase):
+    """Four-player fixed-partnership briscola as a platform game engine."""
+
+    id = "briscola_a_quattro"
+    name = "Briscola a quattro"
+    description = (
+        "Briscola played in two fixed partnerships of two, three cards "
+        "each and a trump suit. First team to the target score wins."
+    )
+    min_players = 4
+    max_players = 4
+    player_count = 4

server/packages/tavolo-briscola/src/tavolo/briscola/state.py

@@ -0,0 +1,279 @@
+"""In-memory representation of a briscola game.
+
+The whole mutable game lives in :class:`BriscolaState`, which is
+serialized to and from plain JSON for storage inside the platform's
+session envelope (see :mod:`tavolo.platform.store`). Keeping the
+representation JSON-native means the store needs no custom codecs and the
+state is inspectable with ``redis-cli``.
+
+The state contains only game data: the platform owns the session envelope
+(id, join code, seats, timestamps, stats persistence) — see
+:class:`tavolo.platform.engine.GameSession`.
+
+Deck convention: a 40-card Italian deck. Suits are ``D`` (denari),
+``C`` (coppe), ``S`` (spade) and ``B`` (bastoni); ranks are ``1``..``10``.
+A card is rendered as ``RRSUIT`` (e.g. ``07D``).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+SUITS = ("D", "C", "S", "B")
+RANKS = tuple(range(1, 11))
+
+# Teams are derived from the seat: seats 0 and 2 form team A (index 0),
+# seats 1 and 3 form team B (index 1). In the two-player variant the teams
+# are simply the two players; in briscola a quattro the partners sit
+# opposite each other.
+TEAM_A = 0
+TEAM_B = 1
+TEAM_NAMES = ("A", "B")
+
+PHASE_LOBBY = "lobby"
+PHASE_PLAYING = "playing"
+# Between deals of an unfinished match: deal summary shown to every
+# player; the next deal is dealt once all players acknowledge (or the
+# hand-end timeout elapses).
+PHASE_HAND_END = "hand_end"
+PHASE_FINISHED = "finished"
+
+# Supported table sizes: classic head-to-head and four-player partnerships.
+PLAYER_COUNTS = (2, 4)
+
+DEFAULT_TARGET_SCORE = 61
+MIN_TARGET_SCORE = 61
+MAX_TARGET_SCORE = 120
+
+# Cards dealt to each player at the start of a deal.
+HAND_SIZE = 3
+
+# Default seconds the between-deals summary waits before dealing anyway.
+# Games carry their own copy in ``BriscolaState.hand_ack_timeout``.
+DEFAULT_HAND_ACK_TIMEOUT_SECONDS = 30
+
+# Default seconds a player has to play before the server plays a random
+# card for them. Games carry their own copy in
+# ``BriscolaState.turn_timeout``.
+DEFAULT_TURN_TIMEOUT_SECONDS = 30
+
+
+def team_of(seat: int) -> int:
+    return seat % 2
+
+
+@dataclass(frozen=True)
+class Card:
+    rank: int
+    suit: str
+
+    def __post_init__(self) -> None:
+        if self.suit not in SUITS:
+            raise ValueError(f"invalid suit: {self.suit!r}")
+        if self.rank not in RANKS:
+            raise ValueError(f"invalid rank: {self.rank!r}")
+
+    @property
+    def code(self) -> str:
+        return f"{self.rank:02d}{self.suit}"
+
+    @staticmethod
+    def parse(code: str) -> "Card":
+        code = str(code).upper()
+        if len(code) != 3 or not code[:2].isdigit():
+            raise ValueError(f"invalid card code: {code!r}")
+        return Card(rank=int(code[:2]), suit=code[2])
+
+    def to_json(self) -> str:
+        return self.code
+
+    @staticmethod
+    def from_json(value: Any) -> "Card":
+        return Card.parse(str(value))
+
+
+def parse_card(code: Any) -> Card:
+    """Parse a card code, raising :class:`ValueError` on malformed input."""
+    return Card.parse(str(code))
+
+
+@dataclass
+class TrickCard:
+    """One card played in the current trick, in play order."""
+
+    seat: int
+    card: str
+
+    def to_json(self) -> Dict[str, Any]:
+        return {"seat": self.seat, "card": self.card}
+
+    @staticmethod
+    def from_json(data: Dict[str, Any]) -> "TrickCard":
+        return TrickCard(seat=int(data["seat"]), card=str(data["card"]))
+
+
+@dataclass
+class Trick:
+    """A completed trick: the winner's seat and the cards it captured."""
+
+    winner: int
+    cards: List[TrickCard] = field(default_factory=list)
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "winner": self.winner,
+            "cards": [c.to_json() for c in self.cards],
+        }
+
+    @staticmethod
+    def from_json(data: Dict[str, Any]) -> "Trick":
+        return Trick(
+            winner=int(data["winner"]),
+            cards=[TrickCard.from_json(c) for c in data.get("cards", [])],
+        )
+
+
+@dataclass
+class PlayerState:
+    sub: str
+    name: str
+    seat: int
+    hand: List[Card] = field(default_factory=list)
+    captured: List[Card] = field(default_factory=list)
+
+    @property
+    def team(self) -> int:
+        return team_of(self.seat)
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "sub": self.sub,
+            "name": self.name,
+            "seat": self.seat,
+            "hand": [c.to_json() for c in self.hand],
+            "captured": [c.to_json() for c in self.captured],
+        }
+
+    @staticmethod
+    def from_json(data: Dict[str, Any]) -> "PlayerState":
+        return PlayerState(
+            sub=str(data["sub"]),
+            name=str(data["name"]),
+            seat=int(data["seat"]),
+            hand=[Card.from_json(c) for c in data.get("hand", [])],
+            captured=[Card.from_json(c) for c in data.get("captured", [])],
+        )
+
+
+@dataclass
+class BriscolaState:
+    player_count: int = 2
+    target_score: int = DEFAULT_TARGET_SCORE
+    phase: str = PHASE_LOBBY
+    players: List[PlayerState] = field(default_factory=list)
+    # Face-down draw pile; cards are drawn from the end.
+    stock: List[Card] = field(default_factory=list)
+    # The face-up card turned at deal time: its suit is the trump suit for
+    # the whole deal, and it is the last card drawn from the stock.
+    briscola_card: Optional[Card] = None
+    briscola_suit: str = ""
+    dealer: int = 0
+    turn: int = 0
+    # 1-based deal counter, used in the audit trail and deadlines.
+    hand_number: int = 1
+    # Cards of the trick in progress, in play order.
+    trick: List[TrickCard] = field(default_factory=list)
+    trick_leader: int = 0
+    # The most recently completed trick, for the table announcement.
+    last_trick: Optional[Trick] = None
+    # Match points accumulated across deals (patta deals do not count).
+    scores: List[int] = field(default_factory=lambda: [0, 0])
+    winner: Optional[int] = None
+    # Per-deal points awarded, for a compact audit trail in the API.
+    hand_scores: List[Dict[str, Any]] = field(default_factory=list)
+    # While phase == "hand_end": seats that acknowledged the summary, and
+    # when the auto-continue timeout fires.
+    acked: List[int] = field(default_factory=list)
+    hand_end_deadline: Optional[str] = None
+    # Seconds the deal summary waits before dealing anyway.
+    hand_ack_timeout: int = DEFAULT_HAND_ACK_TIMEOUT_SECONDS
+    # While phase == "playing": when the server plays a random card for
+    # the player on turn.
+    turn_deadline: Optional[str] = None
+    turn_timeout: int = DEFAULT_TURN_TIMEOUT_SECONDS
+
+    # -- serialization ----------------------------------------------------
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "player_count": self.player_count,
+            "target_score": self.target_score,
+            "phase": self.phase,
+            "players": [p.to_json() for p in self.players],
+            "stock": [c.to_json() for c in self.stock],
+            "briscola_card": (
+                self.briscola_card.to_json() if self.briscola_card else None
+            ),
+            "briscola_suit": self.briscola_suit,
+            "dealer": self.dealer,
+            "turn": self.turn,
+            "hand_number": self.hand_number,
+            "trick": [t.to_json() for t in self.trick],
+            "trick_leader": self.trick_leader,
+            "last_trick": self.last_trick.to_json() if self.last_trick else None,
+            "scores": list(self.scores),
+            "winner": self.winner,
+            "hand_scores": list(self.hand_scores),
+            "acked": list(self.acked),
+            "hand_end_deadline": self.hand_end_deadline,
+            "hand_ack_timeout": self.hand_ack_timeout,
+            "turn_deadline": self.turn_deadline,
+            "turn_timeout": self.turn_timeout,
+        }
+
+    @staticmethod
+    def from_json(data: Dict[str, Any]) -> "BriscolaState":
+        return BriscolaState(
+            player_count=int(data.get("player_count", 2)),
+            target_score=int(data.get("target_score", DEFAULT_TARGET_SCORE)),
+            phase=str(data.get("phase", PHASE_LOBBY)),
+            players=[PlayerState.from_json(p) for p in data.get("players", [])],
+            stock=[Card.from_json(c) for c in data.get("stock", [])],
+            briscola_card=(
+                Card.from_json(data["briscola_card"])
+                if data.get("briscola_card")
+                else None
+            ),
+            briscola_suit=str(data.get("briscola_suit", "")),
+            dealer=int(data.get("dealer", 0)),
+            turn=int(data.get("turn", 0)),
+            hand_number=int(data.get("hand_number", 1)),
+            trick=[TrickCard.from_json(t) for t in data.get("trick", [])],
+            trick_leader=int(data.get("trick_leader", 0)),
+            last_trick=(
+                Trick.from_json(data["last_trick"]) if data.get("last_trick") else None
+            ),
+            scores=[int(x) for x in data.get("scores", [0, 0])],
+            winner=data.get("winner"),
+            hand_scores=list(data.get("hand_scores", [])),
+            acked=[int(s) for s in data.get("acked", [])],
+            hand_end_deadline=data.get("hand_end_deadline"),
+            hand_ack_timeout=int(
+                data.get("hand_ack_timeout", DEFAULT_HAND_ACK_TIMEOUT_SECONDS)
+            ),
+            turn_deadline=data.get("turn_deadline"),
+            turn_timeout=int(
+                data.get("turn_timeout", DEFAULT_TURN_TIMEOUT_SECONDS)
+            ),
+        )
+
+    # -- helpers ----------------------------------------------------------
+
+    def player_for(self, sub: Optional[str]) -> Optional[PlayerState]:
+        for player in self.players:
+            if player.sub == sub:
+                return player
+        return None
+
+    def seated(self, sub: str) -> bool:
+        return self.player_for(sub) is not None

server/packages/tavolo-briscola/tests/test_engine.py

@@ -0,0 +1,691 @@
+"""Rule engine tests: deals, tricks, draws, scoring and full-match simulation."""
+from __future__ import annotations
+
+import random
+import unittest
+
+from tavolo.briscola import engine
+from tavolo.briscola.errors import (
+    CardNotInHand,
+    GameFinished,
+    GameNotStarted,
+    IllegalMove,
+    NotYourTurn,
+)
+from tavolo.briscola.state import (
+    HAND_SIZE,
+    PHASE_FINISHED,
+    PHASE_HAND_END,
+    PHASE_PLAYING,
+    BriscolaState,
+    Card,
+    PlayerState,
+)
+
+
+def card(code: str) -> Card:
+    return Card.parse(code)
+
+
+def make_state(
+    hands,
+    *,
+    briscola_suit: str = "S",
+    briscola_card: str | None = None,
+    stock=None,
+    captured=None,
+    turn: int = 0,
+    dealer: int = 0,
+    target: int = 61,
+    scores=None,
+    phase: str = PHASE_PLAYING,
+) -> BriscolaState:
+    """Build a controlled game state directly (bypassing the deal)."""
+    state = BriscolaState(
+        player_count=len(hands),
+        target_score=target,
+        phase=phase,
+        dealer=dealer,
+        turn=turn,
+        briscola_suit=briscola_suit,
+        briscola_card=card(briscola_card) if briscola_card else None,
+        stock=[card(c) for c in (stock or [])],
+        scores=list(scores or [0, 0]),
+    )
+    for seat, hand in enumerate(hands):
+        state.players.append(
+            PlayerState(sub=f"p{seat}", name=f"p{seat}", seat=seat,
+                        hand=[card(c) for c in hand])
+        )
+    if captured is not None:
+        for player, codes in zip(state.players, captured):
+            player.captured = [card(c) for c in codes]
+    return state
+
+
+def trick_cards(state: BriscolaState) -> list[str]:
+    return [t.card for t in state.trick]
+
+
+def play_all(state: BriscolaState) -> None:
+    """Play every card of the current trick in turn order."""
+    for _ in range(state.player_count):
+        player = next(p for p in state.players if p.seat == state.turn)
+        engine.play(state, player.sub, player.hand[0].code)
+
+
+class DeckTest(unittest.TestCase):
+    def test_full_deck_has_40_unique_cards(self) -> None:
+        deck = engine.full_deck()
+        self.assertEqual(40, len(deck))
+        self.assertEqual(40, len({c.code for c in deck}))
+        self.assertEqual(4, len({c.suit for c in deck}))
+
+    def test_shuffled_deck_is_permutation(self) -> None:
+        deck = engine.shuffled_deck()
+        self.assertEqual(
+            sorted(c.code for c in engine.full_deck()),
+            sorted(c.code for c in deck),
+        )
+
+    def test_card_points_add_up_to_120(self) -> None:
+        self.assertEqual(
+            120, sum(engine.card_points(c) for c in engine.full_deck())
+        )
+        self.assertEqual(11, engine.card_points(card("01D")))
+        self.assertEqual(10, engine.card_points(card("03C")))
+        self.assertEqual(4, engine.card_points(card("10S")))
+        self.assertEqual(3, engine.card_points(card("09B")))
+        self.assertEqual(2, engine.card_points(card("08D")))
+        self.assertEqual(0, engine.card_points(card("07C")))
+
+
+class DealTest(unittest.TestCase):
+    def test_two_player_deal(self) -> None:
+        state = engine.create_game("p0", "p0")
+        engine.join_game(state, "p1", "p1")
+        self.assertEqual(PHASE_PLAYING, state.phase)
+        for player in state.players:
+            self.assertEqual(HAND_SIZE, len(player.hand))
+        # 40 - 3*2 - 1 face-up = 33 face-down.
+        self.assertEqual(33, len(state.stock))
+        self.assertIsNotNone(state.briscola_card)
+        assert state.briscola_card is not None
+        self.assertEqual(state.briscola_card.suit, state.briscola_suit)
+        self.assertEqual(1, state.turn)  # dealer is seat 0
+        self.assertEqual([], state.trick)
+
+    def test_four_player_deal(self) -> None:
+        state = engine.create_game("p0", "p0", player_count=4)
+        for i in range(1, 4):
+            engine.join_game(state, f"p{i}", f"p{i}")
+        self.assertEqual(PHASE_PLAYING, state.phase)
+        for player in state.players:
+            self.assertEqual(HAND_SIZE, len(player.hand))
+        self.assertEqual(40 - 3 * 4 - 1, len(state.stock))
+        self.assertEqual(1, state.turn)
+
+    def test_deal_cards_are_unique_and_leave_nothing_out(self) -> None:
+        state = engine.create_game("p0", "p0", player_count=4)
+        for i in range(1, 4):
+            engine.join_game(state, f"p{i}", f"p{i}")
+        dealt = [c.code for p in state.players for c in p.hand]
+        assert state.briscola_card is not None
+        dealt.append(state.briscola_card.code)
+        dealt.extend(c.code for c in state.stock)
+        self.assertEqual(40, len(dealt))
+        self.assertEqual(40, len(set(dealt)))
+
+    def test_unsupported_player_count(self) -> None:
+        with self.assertRaises(IllegalMove):
+            engine.create_game("p0", "p0", player_count=3)
+
+    def test_target_score_bounds(self) -> None:
+        with self.assertRaises(IllegalMove):
+            engine.create_game("p0", "p0", target_score=60)
+        with self.assertRaises(IllegalMove):
+            engine.create_game("p0", "p0", target_score=121)
+        with self.assertRaises(IllegalMove):
+            engine.create_game("p0", "p0", target_score=True)
+        state = engine.create_game("p0", "p0", target_score=101)
+        self.assertEqual(101, state.target_score)
+
+
+class TrickTest(unittest.TestCase):
+    def test_higher_card_of_led_suit_wins(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        engine.play(state, "p0", "02D")
+        engine.play(state, "p1", "05D")
+        self.assertEqual(1, state.last_trick.winner)
+        self.assertEqual(["02D", "05D"],
+                         [c.code for c in state.players[1].captured])
+
+    def test_trump_beats_a_higher_led_card(self) -> None:
+        state = make_state([["07D"], ["02C"]], briscola_suit="C")
+        engine.play(state, "p0", "07D")
+        engine.play(state, "p1", "02C")
+        self.assertEqual(1, state.last_trick.winner)
+
+    def test_higher_trump_wins_among_trumps(self) -> None:
+        state = make_state([["02C"], ["05C"]], briscola_suit="C")
+        engine.play(state, "p0", "02C")
+        engine.play(state, "p1", "05C")
+        self.assertEqual(1, state.last_trick.winner)
+
+    def test_off_suit_non_trump_loses(self) -> None:
+        state = make_state([["04D"], ["01C"]], briscola_suit="B")
+        engine.play(state, "p0", "04D")
+        engine.play(state, "p1", "01C")
+        self.assertEqual(0, state.last_trick.winner)
+
+    def test_rank_strength_order(self) -> None:
+        # (winner card, loser card) pairs of the led suit, strongest first:
+        # ace > three > king > horse > jack > 7 > 6 > 5 > 4 > 2.
+        pairs = [
+            ("01D", "03D"),  # ace beats three
+            ("03D", "10D"),  # three beats king
+            ("10D", "09D"),  # king beats horse
+            ("09D", "08D"),  # horse beats jack
+            ("08D", "07D"),  # jack beats seven
+            ("07D", "06D"),
+            ("06D", "05D"),
+            ("05D", "04D"),
+            ("04D", "02D"),
+        ]
+        for winner, loser in pairs:
+            state = make_state([["02D"], ["05D"]], briscola_suit="B")
+            state.players[0].hand = [card(winner)]
+            state.players[1].hand = [card(loser)]
+            engine.play(state, "p0", winner)
+            engine.play(state, "p1", loser)
+            self.assertEqual(
+                0, state.last_trick.winner, f"{winner} should beat {loser}"
+            )
+
+    def test_four_player_trick(self) -> None:
+        state = make_state(
+            [["02D"], ["05D"], ["04D"], ["07D"]], briscola_suit="S"
+        )
+        for seat in range(4):
+            engine.play(state, f"p{seat}", state.players[seat].hand[0].code)
+        self.assertEqual(3, state.last_trick.winner)
+
+    def test_four_player_trump_beats_all(self) -> None:
+        state = make_state(
+            [["02D"], ["02C"], ["04D"], ["07D"]], briscola_suit="C"
+        )
+        for seat in range(4):
+            engine.play(state, f"p{seat}", state.players[seat].hand[0].code)
+        self.assertEqual(1, state.last_trick.winner)
+
+    def test_winner_leads_the_next_trick(self) -> None:
+        state = make_state(
+            [["02D"], ["05D"], ["04D"], ["07D"]],
+            briscola_suit="S",
+            stock=["01B", "02B", "03B", "04B"],
+        )
+        for seat in range(4):
+            engine.play(state, f"p{seat}", state.players[seat].hand[0].code)
+        self.assertEqual(3, state.turn)
+        self.assertEqual(3, state.trick_leader)
+        self.assertEqual([], state.trick)
+
+    def test_turn_advances_within_a_trick(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        engine.play(state, "p0", "02D")
+        self.assertEqual(1, state.turn)
+        self.assertEqual(["02D"], trick_cards(state))
+
+    def test_not_your_turn(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S", turn=1)
+        with self.assertRaises(NotYourTurn):
+            engine.play(state, "p0", "02D")
+
+    def test_card_not_in_hand(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        with self.assertRaises(CardNotInHand):
+            engine.play(state, "p0", "07D")
+
+    def test_finished_and_hand_end_reject_plays(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        state.phase = PHASE_FINISHED
+        with self.assertRaises(GameFinished):
+            engine.play(state, "p0", "02D")
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        state.phase = PHASE_HAND_END
+        with self.assertRaises(IllegalMove):
+            engine.play(state, "p0", "02D")
+
+
+class DrawTest(unittest.TestCase):
+    def test_winner_draws_first(self) -> None:
+        # The stock is drawn from its end: 04B first, then 03B, ...
+        state = make_state(
+            [["02D", "09C"], ["05D", "09B"]],
+            briscola_suit="S",
+            stock=["01B", "02B", "03B", "04B"],
+        )
+        engine.play(state, "p0", "02D")
+        engine.play(state, "p1", "05D")
+        hands = {p.seat: [c.code for c in p.hand] for p in state.players}
+        self.assertEqual(["09C", "03B"], hands[0])
+        self.assertEqual(["09B", "04B"], hands[1])
+
+    def test_face_up_briscola_is_drawn_last(self) -> None:
+        state = make_state(
+            [["02D", "09C"], ["05D", "09B"]],
+            briscola_suit="C",
+            briscola_card="05C",
+            stock=["03B"],
+        )
+        engine.play(state, "p0", "02D")
+        engine.play(state, "p1", "05D")
+        hands = {p.seat: [c.code for c in p.hand] for p in state.players}
+        # The winner draws first and takes the last face-down card; the
+        # other player then takes the face-up briscola.
+        self.assertEqual(["09B", "03B"], hands[1])
+        self.assertEqual(["09C", "05C"], hands[0])
+        self.assertIsNone(state.briscola_card)
+
+    def test_no_draw_when_stock_is_empty(self) -> None:
+        state = make_state(
+            [["02D", "03D"], ["05D", "06D"]], briscola_suit="S", stock=[]
+        )
+        engine.play(state, "p0", "02D")
+        engine.play(state, "p1", "05D")
+        # p1 wins the trick; with no stock nobody draws and the hands
+        # shrink for the rest of the deal.
+        for player in state.players:
+            self.assertEqual(1, len(player.hand))
+
+    def test_hands_stay_at_three_until_stock_runs_out(self) -> None:
+        state = engine.create_game("p0", "p0")
+        engine.join_game(state, "p1", "p1")
+        while state.stock or state.briscola_card is not None:
+            play_all(state)
+            for player in state.players:
+                self.assertEqual(HAND_SIZE, len(player.hand))
+        self.assertEqual(0, len(state.stock))
+        self.assertIsNone(state.briscola_card)
+
+
+class ScoringTest(unittest.TestCase):
+    def test_deal_points_group_by_team(self) -> None:
+        state = make_state(
+            [[], [], [], []],
+            briscola_suit="S",
+            captured=[
+                ["01D", "07C"],   # seat 0, team A: 11
+                ["03C", "08D"],   # seat 1, team B: 10
+                ["10S"],          # seat 2, team A: 4
+                ["09B"],          # seat 3, team B: 3
+            ],
+        )
+        points, details = engine.deal_points(state)
+        self.assertEqual([15, 15], points)
+        self.assertEqual({"A": 15, "B": 15}, details["points"])
+        self.assertEqual({"A": 3, "B": 3}, details["cards"])
+
+    def test_full_deal_scores_120(self) -> None:
+        state = engine.create_game("p0", "p0", player_count=4)
+        for i in range(1, 4):
+            engine.join_game(state, f"p{i}", f"p{i}")
+        while state.phase == PHASE_PLAYING:
+            player = next(p for p in state.players if p.seat == state.turn)
+            engine.play(state, player.sub, player.hand[0].code)
+        points, _ = engine.deal_points(state)
+        self.assertEqual(120, sum(points))
+
+    def test_match_ends_when_target_reached(self) -> None:
+        # p0 captures the ace of denari (11) on the last trick: 60+11 >= 61.
+        state = make_state(
+            [["02D"], ["05D"]],
+            briscola_suit="S",
+            stock=[],
+            captured=[["01C"], ["10C"]],
+            scores=[60, 50],
+            target=61,
+        )
+        # p0's pile is worth 11+0 = 11; p1's 4. p0 wins the trick with a
+        # higher card: 02D vs 05D -> p1 would win, so give p0 the five.
+        state.players[0].hand = [card("05D")]
+        state.players[1].hand = [card("02D")]
+        engine.play(state, "p0", "05D")
+        engine.play(state, "p1", "02D")
+        self.assertEqual(PHASE_FINISHED, state.phase)
+        self.assertEqual(0, state.winner)
+        self.assertEqual([71, 54], state.scores)
+
+    def test_tie_at_target_is_broken_by_another_deal(self) -> None:
+        # 65-55 before the deal; this deal gives A 55 and B 65: both reach
+        # 120 and tie, so another deal must be played.
+        a_cards = [f"{rank:02d}D" for rank in range(1, 11)] + ["01C", "03C", "10C"]
+        b_cards = ["09C", "08C", "07C", "06C", "05C", "04C", "02C"] + [
+            f"{rank:02d}S" for rank in range(1, 11)
+        ] + [f"{rank:02d}B" for rank in range(1, 11)]
+        state = make_state(
+            [[], []],
+            briscola_suit="S",
+            stock=[],
+            captured=[a_cards, b_cards],
+            scores=[65, 55],
+            target=120,
+        )
+        engine._end_deal(state)
+        self.assertEqual(PHASE_HAND_END, state.phase)
+        self.assertEqual([120, 120], state.scores)
+        self.assertIsNone(state.winner)
+
+    def test_patta_is_discarded_and_replayed(self) -> None:
+        a_cards = [f"{rank:02d}D" for rank in range(1, 11)] + [
+            f"{rank:02d}C" for rank in range(1, 11)
+        ]
+        b_cards = [f"{rank:02d}S" for rank in range(1, 11)] + [
+            f"{rank:02d}B" for rank in range(1, 11)
+        ]
+        state = make_state(
+            [["02D"], ["02S"]],
+            briscola_suit="S",
+            stock=[],
+            captured=[a_cards, b_cards],
+            scores=[10, 20],
+            target=61,
+        )
+        engine._end_deal(state)
+        self.assertEqual(PHASE_HAND_END, state.phase)
+        # The 60-60 deal does not count: totals are unchanged.
+        self.assertEqual([10, 20], state.scores)
+        entry = state.hand_scores[-1]
+        self.assertTrue(entry["patta"])
+        self.assertEqual({"A": 60, "B": 60}, entry["points"])
+        # The next deal is played at the same cumulative totals.
+        engine.acknowledge_hand(state, "p0")
+        engine.acknowledge_hand(state, "p1")
+        self.assertEqual(PHASE_PLAYING, state.phase)
+        self.assertEqual(2, state.hand_number)
+        self.assertEqual([10, 20], state.scores)
+
+    def test_audit_trail_records_each_deal(self) -> None:
+        state = make_state(
+            [["02D"], ["05D"]],
+            briscola_suit="S",
+            stock=[],
+            captured=[["01C"], []],
+            scores=[0, 0],
+        )
+        engine._end_deal(state)
+        entry = state.hand_scores[-1]
+        self.assertEqual(1, entry["deal"])
+        self.assertFalse(entry["patta"])
+        self.assertEqual({"A": 11, "B": 0}, entry["points"])
+        self.assertEqual({"A": 11, "B": 0}, entry["totals"])
+        self.assertEqual({"A": 1, "B": 0}, entry["cards"])
+
+
+class MatchFlowTest(unittest.TestCase):
+    def test_join_starts_when_full(self) -> None:
+        state = engine.create_game("p0", "p0")
+        self.assertEqual(1, len(state.players))
+        engine.join_game(state, "p1", "p1")
+        self.assertEqual(PHASE_PLAYING, state.phase)
+
+        state = engine.create_game("p0", "p0", player_count=4)
+        for i in range(1, 3):
+            engine.join_game(state, f"p{i}", f"p{i}")
+        self.assertEqual("lobby", state.phase)
+        engine.join_game(state, "p3", "p3")
+        self.assertEqual(PHASE_PLAYING, state.phase)
+
+    def test_join_errors(self) -> None:
+        from tavolo.platform.errors import AlreadyJoined, GameNotStarted
+
+        state = engine.create_game("p0", "p0")
+        with self.assertRaises(AlreadyJoined):
+            engine.join_game(state, "p0", "p0")
+        engine.join_game(state, "p1", "p1")
+        with self.assertRaises(GameNotStarted):
+            engine.join_game(state, "p2", "p2")
+
+    def test_full_random_two_player_match(self) -> None:
+        self._random_match(player_count=2)
+
+    def test_full_random_four_player_match(self) -> None:
+        self._random_match(player_count=4)
+
+    def _random_match(self, player_count: int) -> None:
+        state = engine.create_game("p0", "p0", player_count=player_count)
+        for i in range(1, player_count):
+            engine.join_game(state, f"p{i}", f"p{i}")
+        rng = random.Random(2026)
+        moves = 0
+        while state.phase != PHASE_FINISHED and moves < 200000:
+            if state.phase == PHASE_HAND_END:
+                for player in state.players:
+                    engine.acknowledge_hand(state, player.sub)
+                continue
+            player = next(p for p in state.players if p.seat == state.turn)
+            engine.play(state, player.sub, rng.choice(player.hand).code)
+            moves += 1
+
+        self.assertEqual(PHASE_FINISHED, state.phase)
+        self.assertIn(state.winner, (0, 1))
+        self.assertEqual([], state.trick)
+        self.assertTrue(all(not p.hand for p in state.players))
+        self.assertEqual(
+            40, sum(len(p.captured) for p in state.players)
+        )
+        # Every counted deal totals 120 points, and the winner reached the
+        # target with a clear lead.
+        winner_score = state.scores[state.winner]
+        loser_score = state.scores[1 - state.winner]
+        self.assertGreaterEqual(winner_score, state.target_score)
+        self.assertGreater(winner_score, loser_score)
+        self.assertEqual(0, (winner_score + loser_score) % 120)
+
+
+class AckTest(unittest.TestCase):
+    def _hand_end_state(self) -> BriscolaState:
+        state = make_state(
+            [["02D"], ["05D"]],
+            briscola_suit="S",
+            stock=[],
+            captured=[["01C"], []],
+            target=120,
+        )
+        engine._end_deal(state)
+        return state
+
+    def test_ack_all_deals_the_next_deal(self) -> None:
+        state = self._hand_end_state()
+        dealer_before = state.dealer
+        engine.acknowledge_hand(state, "p0")
+        self.assertEqual([0], state.acked)
+        self.assertEqual(PHASE_HAND_END, state.phase)
+        engine.acknowledge_hand(state, "p1")
+        self.assertEqual(PHASE_PLAYING, state.phase)
+        self.assertEqual(2, state.hand_number)
+        self.assertEqual((dealer_before + 1) % 2, state.dealer)
+        self.assertEqual((dealer_before + 2) % 2, state.turn)
+        self.assertEqual([], state.acked)
+        self.assertIsNone(state.hand_end_deadline)
+        for player in state.players:
+            self.assertEqual(HAND_SIZE, len(player.hand))
+            self.assertEqual([], player.captured)
+
+    def test_double_ack_is_idempotent(self) -> None:
+        state = self._hand_end_state()
+        engine.acknowledge_hand(state, "p0")
+        engine.acknowledge_hand(state, "p0")
+        self.assertEqual([0], state.acked)
+
+    def test_ack_outside_hand_end_is_rejected(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        with self.assertRaises(IllegalMove):
+            engine.acknowledge_hand(state, "p0")
+
+    def test_ack_by_non_player_is_rejected(self) -> None:
+        state = self._hand_end_state()
+        with self.assertRaises(NotYourTurn):
+            engine.acknowledge_hand(state, "mallory")
+
+
+class AutoPlayTest(unittest.TestCase):
+    def test_auto_play_plays_a_card_and_advances_turn(self) -> None:
+        state = make_state(
+            [["02D", "03C"], ["05D"]],
+            briscola_suit="S",
+            stock=["01B", "02B"],
+            briscola_card="03B",
+        )
+        engine.auto_play(state, random.Random(7))
+        self.assertEqual(1, state.turn)
+        self.assertEqual(1, len(state.players[0].hand))
+        self.assertEqual(1, len(state.trick))
+
+    def test_auto_play_can_end_the_deal(self) -> None:
+        state = make_state(
+            [["02D"], ["05D"]],
+            briscola_suit="S",
+            stock=[],
+            captured=[["01C"], []],
+            target=120,
+        )
+        # Both players are on their last card: two auto-plays complete the
+        # trick and the deal, scored A=11 / B=0.
+        engine.auto_play(state)
+        engine.auto_play(state)
+        self.assertEqual(PHASE_HAND_END, state.phase)
+        self.assertIsNone(state.turn_deadline)
+        self.assertTrue(state.hand_end_deadline)
+
+    def test_auto_play_requires_playing_phase(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        state.phase = PHASE_HAND_END
+        with self.assertRaises(GameNotStarted):
+            engine.auto_play(state)
+
+
+class ViewTest(unittest.TestCase):
+    def test_state_for_player_hides_other_hands(self) -> None:
+        state = make_state(
+            [["02D", "03C"], ["04D"], ["05D"], ["06D"]],
+            briscola_suit="D",
+            briscola_card="07D",
+            stock=["01B", "02B"],
+        )
+        view = engine.state_for_player(state, "p0")
+        players = {p["seat"]: p for p in view["players"]}
+        self.assertEqual(["02D", "03C"], players[0]["hand"])
+        self.assertNotIn("hand", players[1])
+        self.assertEqual(1, players[1]["cards_left"])
+        self.assertEqual("D", view["briscola_suit"])
+        self.assertEqual("07D", view["briscola_card"])
+        self.assertEqual(2, view["stock_count"])
+        self.assertTrue(view.get("your_turn"))
+
+    def test_spectator_sees_public_info_only(self) -> None:
+        state = make_state(
+            [["02D"], ["04D"]],
+            briscola_suit="D",
+            briscola_card="07D",
+        )
+        view = engine.state_for_player(state, None)
+        for player in view["players"]:
+            self.assertNotIn("hand", player)
+        self.assertNotIn("your_turn", view)
+        self.assertEqual("07D", view["briscola_card"])
+        self.assertEqual({"A": 0, "B": 0}, view["scores"])
+
+    def test_player_points_are_public(self) -> None:
+        state = make_state(
+            [["02D"], ["04D"]],
+            briscola_suit="D",
+            captured=[["01C", "03B"], ["10D"]],
+        )
+        view = engine.state_for_player(state, "p0")
+        players = {p["seat"]: p for p in view["players"]}
+        self.assertEqual(21, players[0]["points"])
+        self.assertEqual(4, players[1]["points"])
+        self.assertEqual(2, players[0]["captured_count"])
+
+    def test_hand_end_view_exposes_the_deal_summary(self) -> None:
+        state = make_state(
+            [["02D"], ["05D"]],
+            briscola_suit="S",
+            stock=[],
+            captured=[["01C"], []],
+            target=120,
+        )
+        engine._end_deal(state)
+        view = engine.state_for_player(state, "p0")
+        self.assertEqual(PHASE_HAND_END, view["phase"])
+        self.assertEqual(
+            {
+                "deal": 1,
+                "patta": False,
+                "points": {"A": 11, "B": 0},
+                "cards": {"A": 1, "B": 0},
+                "totals": {"A": 11, "B": 0},
+            },
+            view["last_deal"],
+        )
+        self.assertTrue(view["hand_end_deadline"])
+
+    def test_trick_is_public_in_play_order(self) -> None:
+        state = make_state(
+            [["02D"], ["05D"], ["04D"], ["07D"]], briscola_suit="S"
+        )
+        engine.play(state, "p0", "02D")
+        engine.play(state, "p1", "05D")
+        view = engine.state_for_player(state, None)
+        self.assertEqual(
+            [{"seat": 0, "card": "02D"}, {"seat": 1, "card": "05D"}],
+            view["trick"],
+        )
+
+
+class SerializationTest(unittest.TestCase):
+    def test_state_roundtrip(self) -> None:
+        state = engine.create_game("p0", "p0", player_count=4, target_score=101)
+        for i in range(1, 4):
+            engine.join_game(state, f"p{i}", f"p{i}")
+        engine.play(state, state.players[1].sub, state.players[1].hand[0].code)
+        restored = BriscolaState.from_json(state.to_json())
+        self.assertEqual(state.phase, restored.phase)
+        self.assertEqual(state.turn, restored.turn)
+        self.assertEqual(state.hand_number, restored.hand_number)
+        self.assertEqual(state.target_score, restored.target_score)
+        self.assertEqual(state.briscola_suit, restored.briscola_suit)
+        self.assertEqual(
+            state.briscola_card.code if state.briscola_card else None,
+            restored.briscola_card.code if restored.briscola_card else None,
+        )
+        self.assertEqual(
+            [c.code for c in state.stock], [c.code for c in restored.stock]
+        )
+        self.assertEqual(
+            [(t.seat, t.card) for t in state.trick],
+            [(t.seat, t.card) for t in restored.trick],
+        )
+        self.assertEqual(
+            [p.sub for p in state.players], [p.sub for p in restored.players]
+        )
+        self.assertEqual(
+            [[c.code for c in p.hand] for p in state.players],
+            [[c.code for c in p.hand] for p in restored.players],
+        )
+
+    def test_legacy_state_defaults(self) -> None:
+        state = make_state([["02D"], ["05D"]], briscola_suit="S")
+        data = state.to_json()
+        del data["player_count"]
+        del data["briscola_card"]
+        del data["last_trick"]
+        restored = BriscolaState.from_json(data)
+        self.assertEqual(2, restored.player_count)
+        self.assertIsNone(restored.briscola_card)
+        self.assertIsNone(restored.last_trick)
+
+
+if __name__ == "__main__":
+    unittest.main()

server/packages/tavolo-briscola/tests/test_plugin.py

@@ -0,0 +1,349 @@
+"""Adapter tests: the platform contract over the pure briscola rules."""
+from __future__ import annotations
+
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from tavolo.platform import GameSession, Seat
+from tavolo.platform.errors import (
+    AlreadyJoined,
+    GameError,
+    GameFinished,
+    GameNotStarted,
+    IllegalMove,
+)
+from tavolo.briscola import BriscolaEngine, BriscolaQuattroEngine
+from tavolo.briscola import engine as rules
+from tavolo.briscola.state import (
+    PHASE_FINISHED,
+    PHASE_HAND_END,
+    PHASE_PLAYING,
+    BriscolaState,
+)
+
+
+def _session(engine, **options) -> GameSession:
+    session = GameSession(
+        id="b1",
+        game_type=engine.id,
+        join_code="CODE01",
+        creator_sub="alice",
+        players=[Seat(user_sub="alice", display_name="Alice")],
+    )
+    engine.create(session, options)
+    return session
+
+
+def _started(engine, **options) -> GameSession:
+    session = _session(engine, **options)
+    for i in range(1, engine.max_players):
+        name = f"p{i}"
+        engine.join(session, name, name.capitalize())
+    return session
+
+
+def _drive_to_finish(engine, session: GameSession, limit: int = 200000) -> None:
+    moves = 0
+    while not engine.is_finished(session) and moves < limit:
+        state = session.state
+        if state.phase == PHASE_HAND_END:
+            for player in state.players:
+                engine.handle_action(session, player.sub, "ack", {})
+            continue
+        player = next(p for p in state.players if p.seat == state.turn)
+        engine.handle_action(
+            session, player.sub, "play", {"card": player.hand[0].code}
+        )
+        moves += 1
+
+
+class MetadataTest(unittest.TestCase):
+    def test_two_player_metadata(self) -> None:
+        engine = BriscolaEngine()
+        self.assertEqual("briscola", engine.id)
+        self.assertEqual("Briscola", engine.name)
+        self.assertTrue(engine.description)
+        self.assertEqual(2, engine.min_players)
+        self.assertEqual(2, engine.max_players)
+        target = engine.options_schema["properties"]["target_score"]
+        self.assertEqual("integer", target["type"])
+        self.assertEqual(61, target["minimum"])
+        self.assertEqual(120, target["maximum"])
+        self.assertEqual(61, target["default"])
+
+    def test_four_player_metadata(self) -> None:
+        engine = BriscolaQuattroEngine()
+        self.assertEqual("briscola_a_quattro", engine.id)
+        self.assertEqual("Briscola a quattro", engine.name)
+        self.assertTrue(engine.description)
+        self.assertEqual(4, engine.min_players)
+        self.assertEqual(4, engine.max_players)
+        self.assertIn("target_score", engine.options_schema["properties"])
+
+
+class CreateTest(unittest.TestCase):
+    def test_create_seats_creator_on_team_a(self) -> None:
+        engine = BriscolaEngine()
+        session = _session(engine)
+        self.assertEqual("A", session.players[0].team)
+        self.assertIsInstance(session.state, BriscolaState)
+        self.assertEqual(61, session.state.target_score)
+        self.assertEqual(2, session.state.player_count)
+
+    def test_create_options(self) -> None:
+        engine = BriscolaQuattroEngine()
+        session = _session(engine, target_score=101)
+        self.assertEqual(101, session.state.target_score)
+        self.assertEqual(4, session.state.player_count)
+
+    def test_create_rejects_bad_options(self) -> None:
+        engine = BriscolaEngine()
+        with self.assertRaises(IllegalMove):
+            _session(engine, target_score=60)
+        with self.assertRaises(IllegalMove):
+            _session(engine, target_score=121)
+        with self.assertRaises(IllegalMove):
+            _session(engine, target_score="sixtyone")
+        with self.assertRaises(IllegalMove):
+            _session(engine, target_score=True)
+
+    def test_timeouts_come_from_the_engine(self) -> None:
+        engine = BriscolaEngine(turn_timeout_seconds=7, hand_ack_timeout_seconds=9)
+        session = _session(engine)
+        self.assertEqual(7, session.state.turn_timeout)
+        self.assertEqual(9, session.state.hand_ack_timeout)
+
+
+class JoinTest(unittest.TestCase):
+    def test_two_player_join_starts(self) -> None:
+        engine = BriscolaEngine()
+        session = _session(engine)
+        self.assertTrue(engine.in_lobby(session))
+        engine.join(session, "bob", "Bob")
+        self.assertEqual("B", session.players[-1].team)
+        self.assertFalse(engine.in_lobby(session))
+        self.assertEqual(PHASE_PLAYING, session.state.phase)
+
+    def test_four_player_teams_alternate(self) -> None:
+        engine = BriscolaQuattroEngine()
+        session = _session(engine)
+        teams = []
+        for name in ("bob", "carol", "dave"):
+            engine.join(session, name, name.capitalize())
+            teams.append(session.players[-1].team)
+        self.assertEqual(["B", "A", "B"], teams)
+        self.assertEqual(PHASE_PLAYING, session.state.phase)
+
+    def test_join_errors(self) -> None:
+        engine = BriscolaEngine()
+        session = _session(engine)
+        with self.assertRaises(AlreadyJoined):
+            engine.join(session, "alice", "Alice")
+        engine.join(session, "bob", "Bob")
+        with self.assertRaises(GameNotStarted):
+            engine.join(session, "carol", "Carol")
+
+
+class ActionTest(unittest.TestCase):
+    def test_unknown_action_rejected(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        with self.assertRaises(IllegalMove):
+            engine.handle_action(session, "alice", "dance", {})
+
+    def test_play_validates_payload(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        with self.assertRaises(IllegalMove):
+            engine.handle_action(session, "p1", "play", {"card": 42})
+        with self.assertRaises(IllegalMove):
+            engine.handle_action(session, "p1", "play", {})
+        with self.assertRaises(IllegalMove):
+            engine.handle_action(session, "p1", "play", {"card": "nope"})
+
+    def test_play_advances_the_trick(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        state = session.state
+        self.assertEqual(1, state.turn)
+        card = state.players[1].hand[0].code
+        engine.handle_action(session, "p1", "play", {"card": card})
+        self.assertEqual([{"seat": 1, "card": card}], engine.view_for(session, "p1")["trick"])
+
+    def test_play_out_of_turn_rejected(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        state = session.state
+        card = state.players[0].hand[0].code
+        with self.assertRaises(GameError):
+            engine.handle_action(session, "alice", "play", {"card": card})
+
+    def test_ack_outside_hand_end_rejected(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        with self.assertRaises(IllegalMove):
+            engine.handle_action(session, "alice", "ack", {})
+
+    def test_finished_match_rejects_actions(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        _drive_to_finish(engine, session)
+        self.assertTrue(engine.is_finished(session))
+        with self.assertRaises(GameFinished):
+            engine.handle_action(session, "alice", "play", {"card": "01D"})
+
+    def test_ack_all_deals_next(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine, target_score=120)
+        state = session.state
+        # Force the deal-end phase: both players keep 3 cards, so the
+        # match continues after the summary.
+        state.phase = PHASE_HAND_END
+        state.acked = []
+        state.hand_end_deadline = (
+            datetime.now(timezone.utc) + timedelta(seconds=60)
+        ).isoformat()
+        engine.handle_action(session, "alice", "ack", {})
+        self.assertEqual(PHASE_HAND_END, state.phase)
+        engine.handle_action(session, "p1", "ack", {})
+        self.assertEqual(PHASE_PLAYING, state.phase)
+        self.assertEqual(2, state.hand_number)
+
+
+class ViewTest(unittest.TestCase):
+    def test_view_for_hides_other_hands(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        view = engine.view_for(session, "alice")
+        players = {p["seat"]: p for p in view["players"]}
+        self.assertIn("hand", players[0])
+        self.assertNotIn("hand", players[1])
+        # The envelope is the platform's job, not the view's.
+        self.assertNotIn("id", view)
+        self.assertNotIn("join_code", view)
+        self.assertNotIn("game_type", view)
+        self.assertIn("briscola_suit", view)
+        self.assertIn("stock_count", view)
+
+    def test_view_for_spectator_hides_all_hands(self) -> None:
+        engine = BriscolaQuattroEngine()
+        session = _started(engine)
+        view = engine.view_for(session, None)
+        for player in view["players"]:
+            self.assertNotIn("hand", player)
+        self.assertNotIn("your_turn", view)
+        self.assertEqual({"A": 0, "B": 0}, view["scores"])
+
+    def test_lobby_view(self) -> None:
+        engine = BriscolaEngine()
+        session = _session(engine, target_score=101)
+        lobby = engine.lobby_view(session)
+        self.assertEqual("lobby", lobby["phase"])
+        self.assertEqual(101, lobby["target_score"])
+
+
+class SerializationTest(unittest.TestCase):
+    def test_state_roundtrip(self) -> None:
+        engine = BriscolaQuattroEngine()
+        session = _started(engine)
+        restored = engine.state_from_json(engine.state_to_json(session.state))
+        self.assertIsInstance(restored, BriscolaState)
+        self.assertEqual(session.state.phase, restored.phase)
+        self.assertEqual(session.state.turn, restored.turn)
+        self.assertEqual(
+            [p.sub for p in session.state.players],
+            [p.sub for p in restored.players],
+        )
+
+
+class DeadlineTest(unittest.TestCase):
+    def test_no_deadline_in_lobby(self) -> None:
+        engine = BriscolaEngine()
+        self.assertIsNone(engine.next_deadline(_session(engine)))
+
+    def test_turn_deadline_and_revalidation(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        deadline = engine.next_deadline(session)
+        assert deadline is not None
+        self.assertEqual("turn", deadline.kind)
+        with self.assertRaises(GameError):
+            engine.fire_deadline(session, "turn", "turn:1:1:0")
+        turn_before = session.state.turn
+        engine.fire_deadline(session, deadline.kind, deadline.token)
+        self.assertNotEqual(turn_before, session.state.turn)
+
+    def test_stale_deadline_after_play(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        deadline = engine.next_deadline(session)
+        assert deadline is not None
+        state = session.state
+        player = next(p for p in state.players if p.seat == state.turn)
+        engine.handle_action(session, player.sub, "play", {"card": player.hand[0].code})
+        with self.assertRaises(GameError):
+            engine.fire_deadline(session, deadline.kind, deadline.token)
+
+    def test_hand_end_deadline_advances(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine, target_score=120)
+        state = session.state
+        state.phase = PHASE_HAND_END
+        state.hand_end_deadline = (
+            datetime.now(timezone.utc) + timedelta(seconds=60)
+        ).isoformat()
+        deadline = engine.next_deadline(session)
+        assert deadline is not None
+        self.assertEqual("hand_end", deadline.kind)
+        engine.fire_deadline(session, deadline.kind, deadline.token)
+        self.assertEqual(PHASE_PLAYING, session.state.phase)
+        self.assertEqual(2, session.state.hand_number)
+
+
+class ResultTest(unittest.TestCase):
+    def test_result_of_finished_match(self) -> None:
+        engine = BriscolaQuattroEngine()
+        session = _started(engine)
+        _drive_to_finish(engine, session)
+        result = engine.result(session)
+        self.assertEqual(2, len(result.teams))
+        self.assertEqual([2, 2], [len(team) for team in result.teams])
+        self.assertIn(result.winner_team, (0, 1))
+        self.assertEqual(4, len(result.players))
+        winner_name = "A" if result.winner_team == 0 else "B"
+        for player in result.players:
+            self.assertEqual(player.won, player.team == winner_name)
+            self.assertIn("captured_cards", player.details)
+        self.assertIn("team_a_score", result.summary)
+        self.assertIn("team_b_score", result.summary)
+        self.assertIn("winner_team", result.summary)
+        self.assertIn("target_score", result.summary)
+        self.assertIn("deals_played", result.summary)
+        self.assertIn("deal_scores", result.summary)
+
+    def test_two_player_result(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        _drive_to_finish(engine, session)
+        result = engine.result(session)
+        self.assertEqual([[session.players[0].user_sub], [session.players[1].user_sub]], result.teams)
+        self.assertEqual(2, len(result.players))
+
+    def test_result_requires_finished_match(self) -> None:
+        engine = BriscolaEngine()
+        with self.assertRaises(GameError):
+            engine.result(_started(engine))
+
+    def test_game_over_view(self) -> None:
+        engine = BriscolaEngine()
+        session = _started(engine)
+        session.state.phase = PHASE_FINISHED
+        session.state.winner = 1
+        session.state.scores = [55, 65]
+        over = engine.game_over_view(session, "alice")
+        self.assertEqual({"A": 55, "B": 65}, over["scores"])
+        self.assertEqual("B", over["winner"])
+
+
+if __name__ == "__main__":
+    unittest.main()

server/packages/tavolo-platform/README.md

@@ -48,8 +48,8 @@ itself ships no game.
 Implement `GameEngine` (see `engine.py` for the full contract), register
 it in a `GameRegistry`, and mount `PlatformMixin(Platform(...))` on a
 `KayaApp` — see the composition root in `tavolo.app`. The canonical
-example is
+examples are [`tavolo-scopone`](../tavolo-scopone/README.md) and
-[`tavolo-scopone`](../tavolo-scopone/README.md).
+[`tavolo-briscola`](../tavolo-briscola/README.md).
 
 ## Development (from `server/`)
 

server/packages/tavolo-platform/pyproject.toml

@@ -9,9 +9,9 @@ description = "Game-independent multiplayer game platform (lobby, live play, mat
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "kaya-core",
+    "kaya-core>=0.0.7",
     "kaya-session",
-    "kaya-oidc",
+    "kaya-oidc>=0.0.7",
     "kaya-openapi",
     "tortoise-orm",
     "redis",

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

@@ -9,7 +9,29 @@ from __future__ import annotations
 from typing import Any, Callable, Mapping, Optional
 
 from kaya.core import HttpContext, WebSocket
-from kaya.oidc import OIDCMixin, OIDCUser
+from kaya.oidc import OIDCProviders, OIDCUser
+from kaya.session import Session
+
+# kaya-oidc namespaces its session state per provider as
+# ``oidc:{provider}:user`` (since 0.0.6), so the lookup cannot assume a
+# fixed key or provider name.
+_OIDC_PREFIX = "oidc:"
+_USER_SUFFIX = ":user"
+
+
+def session_user(session: Session) -> Optional[OIDCUser]:
+    """Return the authenticated user stored in a session, if any.
+
+    The kaya-oidc mixin writes the userinfo at login under a per-provider
+    key, so any provider's user is accepted (the configured provider is
+    ``default`` unless the app says otherwise).
+    """
+    for key in session:
+        if key.startswith(_OIDC_PREFIX) and key.endswith(_USER_SUFFIX):
+            claims = session.get(key)
+            if isinstance(claims, Mapping):
+                return OIDCUser(claims)
+    return None
 
 
 def get_ws_user(ws: WebSocket) -> Optional[OIDCUser]:
@@ -21,10 +43,7 @@ def get_ws_user(ws: WebSocket) -> Optional[OIDCUser]:
     session = getattr(ws, "session", None)
     if session is None:
         return None
-    claims = session.get("oidc_user")
+    return session_user(session)
-    if not isinstance(claims, Mapping):
-        return None
-    return OIDCUser(claims)
 
 
 def display_name(user: OIDCUser) -> str:
@@ -36,7 +55,16 @@ def display_name(user: OIDCUser) -> str:
     return user.sub
 
 
-def require_auth(oidc: OIDCMixin) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+def current_user(oidc: OIDCProviders, ctx: HttpContext) -> Optional[OIDCUser]:
+    """Return the authenticated user of an HTTP request, if any.
+
+    Sessions are single-identity by default, so at most one provider has
+    a user; if several do, the first configured provider wins.
+    """
+    return next(iter(oidc.get_users(ctx).values()), None)
+
+
+def require_auth(oidc: OIDCProviders) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Build a decorator gating a handler on being authenticated.
 
     Responds ``401`` with a JSON error envelope when unauthenticated —
@@ -46,7 +74,7 @@ def require_auth(oidc: OIDCMixin) -> Callable[[Callable[..., Any]], Callable[...
 
     def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
         async def guarded(ctx: HttpContext, *args: Any, **kwargs: Any) -> None:
-            if oidc.get_user(ctx) is None:
+            if current_user(oidc, ctx) is None:
                 await ctx.send_bytes(
                     401,
                     b'{"error":"unauthenticated"}',

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

@@ -11,8 +11,11 @@ machinery; the *meaning* of each deadline belongs to the game engine:
   token), and the scheduler enqueues it in the store's shared deadline
   queue (a Redis sorted set in production, see
   :mod:`tavolo.platform.store`); enqueueing is idempotent;
-* a background consumer running on **every** worker polls the queue for
+* enqueueing a deadline announces it on a shared pub/sub channel, so
-  due entries and hands them to the engine's
+  every worker's consumer wakes immediately instead of waiting for its
+  next poll; the consumer also wakes on a slow heartbeat, which is the
+  backstop recovering notifications lost to a reconnect or a worker
+  crash. Due entries are handed to the engine's
   :meth:`~tavolo.platform.engine.GameEngine.fire_deadline` under the
   per-game lock; the engine revalidates the token against the live state
   and raises :class:`~tavolo.platform.errors.GameError` when the entry
@@ -65,8 +68,8 @@ class DeadlineScheduler:
     """Enqueue and fire the deadlines game engines ask for.
 
     Holds the store and the registry so a single instance serves every
-    game type. One consumer task (and its wake-up event) is kept per
+    game type. One consumer task, its listener task and its wake-up
-    event loop — tests run each test on a fresh loop.
+    event are kept per event loop — tests run each test on a fresh loop.
 
     ``context_binder`` is an optional async callable the consumer awaits
     before persisting a finished match. The consumer is a long-lived task
@@ -80,14 +83,19 @@ class DeadlineScheduler:
         store: GameStore,
         registry: GameRegistry,
         heartbeat_ms: int = 1000,
+        retry_ms: int = 1000,
         context_binder: Optional[Callable[[], Awaitable[None]]] = None,
     ) -> None:
         self._store = store
         self._registry = registry
         self._heartbeat = heartbeat_ms / 1000
+        # Backoff for entries that failed to process and for listener
+        # reconnects; deliberately independent of the (slow) heartbeat.
+        self._retry_delay = retry_ms / 1000
         self._context_binder = context_binder
         self._consumers: Dict[asyncio.AbstractEventLoop, asyncio.Task] = {}
         self._wake_events: Dict[asyncio.AbstractEventLoop, asyncio.Event] = {}
+        self._listeners: Dict[asyncio.AbstractEventLoop, asyncio.Task] = {}
 
     async def sync_deadline(self, session: GameSession) -> None:
         """Enqueue the deadline the current state implies, if any.
@@ -109,6 +117,16 @@ class DeadlineScheduler:
         self.ensure_consumer()
         due_at = deadline.due_at.timestamp()
         await self._store.add_deadline(encode(entry), due_at)
+        # Announce the enqueue so consumers on other workers wake up too.
+        # The entry is already queued, so a lost notification only delays
+        # their discovery to the next poll backstop.
+        try:
+            await self._store.notify_deadline()
+        except Exception:
+            log.warning(
+                "deadline enqueue notification failed; relying on the poll backstop",
+                exc_info=True,
+            )
         wake = self._wake_events.get(asyncio.get_running_loop())
         if wake is not None:
             wake.set()
@@ -190,15 +208,22 @@ class DeadlineScheduler:
             if old.is_closed():
                 self._consumers.pop(old, None)
                 self._wake_events.pop(old, None)
+                self._listeners.pop(old, None)
         task = self._consumers.get(loop)
         if task is None or task.done():
             self._wake_events[loop] = asyncio.Event()
             self._consumers[loop] = loop.create_task(self._run(loop))
+            listener = self._listeners.get(loop)
+            if listener is None or listener.done():
+                self._listeners[loop] = loop.create_task(self._listen(loop))
             log.debug("deadline consumer started")
 
     def stop_consumer(self, loop: asyncio.AbstractEventLoop) -> None:
         task = self._consumers.pop(loop, None)
         self._wake_events.pop(loop, None)
+        listener = self._listeners.pop(loop, None)
+        if listener is not None:
+            listener.cancel()
         if task is not None:
             task.cancel()
 
@@ -228,21 +253,48 @@ class DeadlineScheduler:
                 log.exception("deadline consumer: poll failed; retrying")
                 failed = True
             if failed:
-                # A failed entry is still due: back off to the heartbeat
+                # A failed entry is still due: back off briefly instead of
-                # instead of polling it again immediately.
+                # polling it again immediately. Kept independent of the
-                delay = self._heartbeat
+                # heartbeat, which is only a slow backstop.
+                delay = self._retry_delay
             try:
                 await asyncio.wait_for(wake.wait(), timeout=delay)
             except asyncio.TimeoutError:
                 pass
 
+    async def _listen(self, loop: asyncio.AbstractEventLoop) -> None:
+        """Wake the consumer on deadline-enqueue notifications.
+
+        The subscription is best effort: a dropped connection or a lost
+        message is recovered by the consumer's heartbeat backstop, so
+        this task only has to reconnect and keep forwarding signals.
+        """
+        while True:
+            try:
+                async with self._store.subscribe_deadlines() as events:
+                    async for _ in events:
+                        wake = self._wake_events.get(loop)
+                        if wake is None:
+                            # Shut down: the consumer is gone.
+                            return
+                        wake.set()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                log.exception("deadline listener failed; reconnecting")
+            try:
+                await asyncio.sleep(self._retry_delay)
+            except asyncio.CancelledError:
+                raise
+
 
 class DeadlineSchedulerMixin(KayaMixin):
     """Run the deadline consumer for the whole app lifetime.
 
-    Every worker (and every pod) runs the same consumer; coordination
+    Every worker (and every pod) runs the same consumer and listener;
-    happens exclusively through the shared deadline queue and the
+    coordination happens exclusively through the shared deadline queue,
-    per-game locks, so any worker may fire any game's deadline.
+    its notification channel and the per-game locks, so any worker may
+    fire any game's deadline.
     """
 
     def __init__(self, scheduler: DeadlineScheduler) -> None:

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

@@ -191,12 +191,17 @@ class GameEngine(ABC):
         """
 
     @abstractmethod
-    def view_for(self, session: GameSession, user_sub: str) -> Dict[str, Any]:
+    def view_for(self, session: GameSession, user_sub: Optional[str]) -> Dict[str, Any]:
-        """The personalized game view for one player.
+        """The personalized game view for one viewer.
 
-        Must hide information the player is not entitled to (e.g. other
+        Must hide information the viewer is not entitled to (e.g. other
-        players' hands). The platform merges in the envelope fields
+        players' hands). ``user_sub`` is ``None`` for a spectator — an
-        (``id``, ``join_code``, ``game_type``) itself.
+        anonymous user or an authenticated user who is not seated — and
+        the view must then contain no privileged information either (no
+        hand, no legal moves: only what everyone at the table can see).
+        The platform merges in the envelope fields (``id``,
+        ``join_code`` for seated players, ``game_type``, ``spectator``)
+        itself.
         """
 
     @abstractmethod
@@ -248,6 +253,13 @@ class GameEngine(ABC):
         ``kind``/``token`` no longer match the live state.
         """
 
-    def game_over_view(self, session: GameSession, user_sub: str) -> Dict[str, Any]:
+    def game_over_view(
-        """Extra fields merged into the ``game_over`` websocket message."""
+        self, session: GameSession, user_sub: Optional[str]
+    ) -> Dict[str, Any]:
+        """Extra fields merged into the ``game_over`` websocket message.
+
+        ``user_sub`` is ``None`` for a spectator (see :meth:`view_for`);
+        the default fields are public, so the default implementation
+        ignores it.
+        """
         return {}

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

@@ -2,7 +2,7 @@
 
 ``Platform`` bundles the collaborators every platform endpoint needs —
 the game registry, the live-game store, the deadline scheduler and the
-OIDC mixin used for authentication — so route and websocket modules
+OIDC providers used for authentication — so route and websocket modules
 never reach for module-global state. :class:`PlatformMixin` is a plain
 :class:`~kaya.core.KayaMixin`: applying it registers the lobby, stats
 and health HTTP routes plus the live-play websocket endpoint, and the
@@ -14,7 +14,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from kaya.core import KayaApp, KayaMixin
-from kaya.oidc import OIDCMixin
+from kaya.oidc import OIDCProviders
 
 from .deadlines import DeadlineScheduler
 from .registry import GameRegistry
@@ -28,7 +28,7 @@ class Platform:
     registry: GameRegistry
     game_store: GameStore
     scheduler: DeadlineScheduler
-    oidc: OIDCMixin
+    oidc: OIDCProviders
 
 
 class PlatformMixin(KayaMixin):
@@ -41,9 +41,10 @@ class PlatformMixin(KayaMixin):
         # Imported here so module import order stays acyclic: the route
         # modules reference Platform only for typing.
         from . import ws
-        from .routes import games, health, me, stats
+        from .routes import auth, games, health, me, stats
 
         health.register(app, self.platform)
+        auth.register(app, self.platform)
         me.register(app, self.platform)
         games.register(app, self.platform)
         stats.register(app, self.platform)

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

@@ -15,12 +15,15 @@ from __future__ import annotations
 import base64
 import json
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
 
 from tortoise.queryset import QuerySet
 
 from .http import extract_query_params
 
+if TYPE_CHECKING:
+    from tortoise.models import Model
+
 DEFAULT_LIMIT = 20
 MAX_LIMIT = 100
 MIN_LIMIT = 1
@@ -81,6 +84,28 @@ def parse_cursor_params(query_string: str) -> Cursor:
 Sort = List[Tuple[str, str]]
 
 
+def _coerce_sort_values(
+    model: "type[Model]", sort: Sort, after: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Restore the Python type of every decoded cursor value.
+
+    The cursor is JSON, so field values travel as strings (datetimes via
+    ``default=str``). asyncpg rejects strings where a ``timestamp``
+    parameter is expected, and sqlite only tolerates them by accident, so
+    each value is run through its model field's ``to_python_value`` before
+    it reaches the keyset filter.
+    """
+    fields = model._meta.fields_map
+    coerced: Dict[str, Any] = {}
+    for field, _ in sort:
+        value = after.get(field)
+        field_obj = fields.get(field)
+        if value is not None and field_obj is not None:
+            value = field_obj.to_python_value(value)
+        coerced[field] = value
+    return coerced
+
+
 def _keyset_where(sort: Sort, after: Dict[str, Any]):
     """Build a Tortoise ``Q`` filter from a cursor."""
     from tortoise.queryset import Q  # local to keep import edge narrow
@@ -116,7 +141,8 @@ async def paginate(
         order_by.append(field if direction == "ASC" else f"-{field}")
     qs = queryset.order_by(*order_by)
     if cursor.after:
-        qs = qs.filter(_keyset_where(sort, cursor.after))
+        after = _coerce_sort_values(queryset.model, sort, cursor.after)
+        qs = qs.filter(_keyset_where(sort, after))
     rows = await qs.limit(cursor.limit + 1)
     if len(rows) <= cursor.limit:
         return rows, None

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

@@ -0,0 +1,62 @@
+"""Authentication plumbing for the single-page app.
+
+kaya-oidc registers one login/callback/logout route per provider
+(``/auth/<provider>/...``); this module adds the provider-agnostic
+pieces:
+
+* ``GET /api/auth/providers`` lists the configured providers with their
+  login URLs, so the SPA can offer a choice without hardcoding names;
+* ``GET /auth/login`` redirects to the first configured provider;
+* ``GET /auth/logout`` redirects to the provider this session is logged
+  in with (or the SPA root when not logged in), so the UI can keep a
+  single logout link.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from kaya.core import HttpContext, KayaApp
+from kaya.openapi import operation
+
+from ..http import send_json
+
+if TYPE_CHECKING:
+    from ..mixin import Platform
+
+
+def _login_url(platform: "Platform", provider: str) -> str:
+    return f"{platform.oidc.base_path}/{provider}/login"
+
+
+def register(app: KayaApp, platform: "Platform") -> None:
+    providers = list(platform.oidc.providers)
+
+    @app.GET("/api/auth/providers")
+    @operation(summary="Configured login providers",
+               description="Names and login URLs of the configured OIDC "
+                           "providers, in configuration order.",
+               tags=["auth"],
+               responses={200: {"description": "The configured providers"}})
+    async def auth_providers(ctx: HttpContext) -> None:
+        await send_json(
+            ctx,
+            200,
+            {
+                "providers": [
+                    {"name": name, "login_url": _login_url(platform, name)}
+                    for name in providers
+                ]
+            },
+        )
+
+    @app.GET("/auth/login")
+    async def login(ctx: HttpContext) -> None:
+        await ctx.send_empty(302, {"Location": _login_url(platform, providers[0])})
+
+    @app.GET("/auth/logout")
+    async def logout(ctx: HttpContext) -> None:
+        logged_in = platform.oidc.logged_in_providers(ctx)
+        location = (
+            f"{platform.oidc.base_path}/{logged_in[0]}/logout" if logged_in else "/"
+        )
+        await ctx.send_empty(302, {"Location": location})

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

@@ -16,12 +16,12 @@ import secrets
 import uuid
 from datetime import datetime, timezone
 from logging import getLogger
-from typing import TYPE_CHECKING, Any, Dict
+from typing import TYPE_CHECKING, Any, Dict, Optional
 
 from kaya.core import HttpContext, KayaApp
 from kaya.openapi import operation
 
-from ..auth import display_name, require_auth
+from ..auth import current_user, display_name, require_auth
 from ..engine import GameSession, Seat
 from ..errors import GameError
 from ..http import (
@@ -71,19 +71,29 @@ def _lobby_payload(platform: "Platform", session: GameSession) -> Dict[str, Any]
             }
             for index, seat in enumerate(session.players)
         ],
-        "seats_open": engine.max_players - len(session.players),
+        "seats_open": max(0, engine.max_players - len(session.players)),
         **engine.lobby_view(session),
     }
 
 
-def _view_payload(platform: "Platform", session: GameSession, sub: str) -> Dict[str, Any]:
+def _view_payload(
+    platform: "Platform", session: GameSession, sub: Optional[str]
+) -> Dict[str, Any]:
     engine = platform.registry.require(session.game_type)
-    return {
+    seated = sub is not None and session.seated(sub)
+    payload: Dict[str, Any] = {
         "id": session.id,
-        "join_code": session.join_code,
         "game_type": session.game_type,
-        **engine.view_for(session, sub),
+        "spectator": not seated,
+        # Free chairs; the lobby view needs it for games with other player
+        # counts than four.
+        "seats_open": max(0, engine.max_players - len(session.players)),
     }
+    if seated:
+        # The join code is a credential: only players get it.
+        payload["join_code"] = session.join_code
+    payload.update(engine.view_for(session, sub))
+    return payload
 
 
 def _preview_payload(platform: "Platform", session: GameSession) -> Dict[str, Any]:
@@ -183,7 +193,7 @@ def register(app: KayaApp, platform: "Platform") -> None:
             await send_error(ctx, 400, "options must be an object")
             return
 
-        user = platform.oidc.get_user(ctx)
+        user = current_user(platform.oidc, ctx)
         assert user is not None  # enforced by @require_auth
         session = GameSession(
             id=str(uuid.uuid4()),
@@ -244,7 +254,7 @@ def register(app: KayaApp, platform: "Platform") -> None:
             await send_error(ctx, 400, "code is required")
             return
 
-        user = platform.oidc.get_user(ctx)
+        user = current_user(platform.oidc, ctx)
         assert user is not None
         existing = await platform.game_store.find_by_code(code)
         if existing is None:
@@ -310,24 +320,24 @@ def register(app: KayaApp, platform: "Platform") -> None:
 
     @app.GET("/api/games/${game_id}")
     @operation(summary="Get a game snapshot",
-               description="Only seated players may read a game; the view is "
+               description="Anyone who knows the game id may read a game. "
-                           "personalized by the engine (e.g. hidden hands).",
+                           "Seated players get the personalized view (their "
+                           "own hand plus the join code); everyone else — "
+                           "anonymous users and authenticated non-players — "
+                           "gets the read-only spectator view: no hands, no "
+                           "join code, just what is public at the table.",
                tags=["games"],
                responses={
-                   200: {"description": "The personalized game state"},
+                   200: {"description": "The personalized (player) or "
-                   401: {"description": "Authentication required"},
+                                        "read-only (spectator) game state"},
-                   403: {"description": "Not a player in this game"},
                    404: {"description": "Game not found"},
                })
-    @require_auth(platform.oidc)
     async def get_game(ctx: HttpContext, game_id: str) -> None:
         session = await platform.game_store.load(game_id)
         if session is None:
             await send_error(ctx, 404, "game not found")
             return
-        user = platform.oidc.get_user(ctx)
+        user = current_user(platform.oidc, ctx)
-        assert user is not None
+        await send_json(
-        if not session.seated(user.sub):
+            ctx, 200, _view_payload(platform, session, user.sub if user else None)
-            await send_error(ctx, 403, "forbidden")
+        )
-            return
-        await send_json(ctx, 200, _view_payload(platform, session, user.sub))

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

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING
 from kaya.core import HttpContext, KayaApp
 from kaya.openapi import operation
 
-from ..auth import display_name, require_auth
+from ..auth import current_user, display_name, require_auth
 from ..http import send_json
 
 if TYPE_CHECKING:
@@ -25,6 +25,6 @@ def register(app: KayaApp, platform: "Platform") -> None:
                })
     @require_auth(platform.oidc)
     async def me(ctx: HttpContext) -> None:
-        user = platform.oidc.get_user(ctx)
+        user = current_user(platform.oidc, ctx)
         assert user is not None  # enforced by @require_auth
         await send_json(ctx, 200, {"sub": user.sub, "name": display_name(user)})

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

@@ -8,12 +8,14 @@ verbatim through the ``result`` JSON column.
 """
 from __future__ import annotations
 
+from collections import defaultdict
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+from uuid import UUID
 
 from kaya.core import HttpContext, KayaApp
 from kaya.openapi import operation
 
-from ..auth import require_auth
+from ..auth import current_user, require_auth
 from ..elo import INITIAL_RATING
 from ..http import extract_query_params, send_error, send_json
 from ..models import Match, MatchPlayer, PlayerRating
@@ -48,8 +50,9 @@ def _parse_game_type(
     return game_type, None
 
 
-async def _serialize_match(match: Match, viewer: str) -> Dict[str, Any]:
+def _serialize_match(
-    participants = await MatchPlayer.filter(match_id=match.id).order_by("seat")
+    match: Match, viewer: str, participants: List[MatchPlayer]
+) -> Dict[str, Any]:
     return {
         "id": str(match.id),
         "game_type": match.game_type,
@@ -101,7 +104,7 @@ def register(app: KayaApp, platform: "Platform") -> None:
         if error is not None:
             await send_error(ctx, 400, error)
             return
-        user = platform.oidc.get_user(ctx)
+        user = current_user(platform.oidc, ctx)
         assert user is not None
         queryset = Match.filter(players__user_sub=user.sub).distinct()
         if game_type is not None:
@@ -109,7 +112,21 @@ def register(app: KayaApp, platform: "Platform") -> None:
         matches, next_cursor = await paginate(
             queryset, [("finished_at", "DESC"), ("id", "ASC")], cursor
         )
-        results = [await _serialize_match(m, user.sub) for m in matches]
+        # One participants query for the whole page instead of one per
+        # match; the grouping keeps each match's players seat-ordered.
+        by_match: Dict[UUID, List[MatchPlayer]] = defaultdict(list)
+        if matches:
+            participants = (
+                await MatchPlayer.filter(match_id__in=[m.id for m in matches])
+                .order_by("match_id", "seat")
+            )
+            for player in participants:
+                # Tortoise sets the FK's raw id on instances but does not
+                # declare it on the model class, hence the getattr.
+                by_match[getattr(player, "match_id")].append(player)
+        results = [
+            _serialize_match(m, user.sub, by_match.get(m.id, [])) for m in matches
+        ]
         await send_json(ctx, 200, {"results": results, "next_cursor": next_cursor})
 
     @app.GET("/api/leaderboard")
@@ -176,7 +193,7 @@ def register(app: KayaApp, platform: "Platform") -> None:
                })
     @require_auth(platform.oidc)
     async def my_ratings(ctx: HttpContext) -> None:
-        user = platform.oidc.get_user(ctx)
+        user = current_user(platform.oidc, ctx)
         assert user is not None
         rows = await PlayerRating.filter(user_sub=user.sub).order_by("game_type")
         await send_json(ctx, 200, {

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

@@ -26,8 +26,9 @@ signal (never the state) means updated state reaches connections on
 every worker without leaking hidden information into the channel.
 
 Timeouts are driven by a shared delayed-deadline queue: producers
-enqueue an opaque ``member`` string with a due timestamp, and a consumer
+enqueue an opaque ``member`` string with a due timestamp and announce it
-on every worker polls for due entries (see
+on a shared "deadline enqueued" channel, and a consumer on every worker
+wakes on that signal to process due entries (see
 :mod:`tavolo.platform.deadlines`). Delivery is at-least-once — entries
 are removed only after they are processed — so a worker dying
 mid-processing cannot lose a deadline; engines revalidate entries
@@ -38,6 +39,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import json
+import time
 from abc import ABC, abstractmethod
 from datetime import datetime
 from logging import getLogger
@@ -54,6 +56,13 @@ GAME_KEY_PREFIX = "tavolo:game:"
 CODE_KEY_PREFIX = "tavolo:code:"
 CHANNEL_PREFIX = "tavolo:game:"
 DEADLINES_KEY = "tavolo:deadlines"
+# Channel announcing newly enqueued deadline entries, so every worker's
+# consumer can wake immediately instead of polling on its heartbeat.
+DEADLINES_CHANNEL = "tavolo:deadlines:events"
+# Sorted set of running games (score = expiry timestamp), maintained by the
+# stores so the telemetry gauge can count ongoing matches without loading
+# every session. Finished games are removed on their final save.
+ONGOING_GAMES_KEY = "tavolo:games:ongoing"
 
 # Sentinel pushed into in-memory subscriber queues to signal a change.
 _BUMP = b"update"
@@ -120,6 +129,14 @@ class GameStore(ABC):
     async def find_by_code(self, code: str) -> Optional[GameSession]:
         """Return the live session for a join ``code`` or ``None``."""
 
+    @abstractmethod
+    async def count_ongoing(self) -> int:
+        """Return the number of live games that have not finished yet.
+
+        Lobbies and matches in progress count; matches that are over but
+        still retained for the final-board view do not.
+        """
+
     @abstractmethod
     def lock(self, game_id: str) -> AsyncContextManager[None]:
         """Async context manager serializing mutations of one game."""
@@ -152,6 +169,18 @@ class GameStore(ABC):
     async def remove_deadline(self, member: str) -> None:
         """Remove ``member`` from the queue; a no-op when absent."""
 
+    @abstractmethod
+    async def notify_deadline(self) -> None:
+        """Wake every worker's deadline consumer (best effort).
+
+        Notification is advisory: consumers stay correct when a signal
+        is lost, because their poll backstop recovers it.
+        """
+
+    @abstractmethod
+    def subscribe_deadlines(self) -> AsyncContextManager[AsyncIterator[None]]:
+        """Async context manager yielding deadline-enqueue signals."""
+
 
 def _channel(game_id: str) -> str:
     return f"{CHANNEL_PREFIX}{game_id}:events"
@@ -181,9 +210,15 @@ class RedisGameStore(GameStore):
 
     async def save(self, session: GameSession) -> None:
         payload = json.dumps(session_to_json(session, self._registry))
+        engine = self._registry.require(session.game_type)
         async with self._redis.pipeline(transaction=True) as pipe:
             pipe.set(f"{GAME_KEY_PREFIX}{session.id}", payload, ex=self._ttl)
             pipe.set(f"{CODE_KEY_PREFIX}{session.join_code}", session.id, ex=self._ttl)
+            if engine.is_finished(session):
+                pipe.zrem(ONGOING_GAMES_KEY, session.id)
+            else:
+                pipe.zadd(ONGOING_GAMES_KEY, {session.id: time.time() + self._ttl})
+                pipe.expire(ONGOING_GAMES_KEY, self._ttl)
             await pipe.execute()
         log.debug("redis save %s (game %s, ttl %ds)", session.id, session.game_type, self._ttl)
 
@@ -195,6 +230,17 @@ class RedisGameStore(GameStore):
             game_id = game_id.decode("utf-8")
         return await self.load(str(game_id))
 
+    async def count_ongoing(self) -> int:
+        # Prune entries whose game has expired since the last poll, then
+        # count what is left. Both commands run in one transaction so the
+        # count cannot see a half-pruned set.
+        now = time.time()
+        async with self._redis.pipeline(transaction=True) as pipe:
+            pipe.zremrangebyscore(ONGOING_GAMES_KEY, "-inf", now)
+            pipe.zcard(ONGOING_GAMES_KEY)
+            _, count = await pipe.execute()
+        return int(count)
+
     @contextlib.asynccontextmanager
     async def subscribe(self, game_id: str) -> AsyncIterator[AsyncIterator[None]]:
         pubsub = self._redis.pubsub()
@@ -214,10 +260,17 @@ class RedisGameStore(GameStore):
         await self._redis.zadd(DEADLINES_KEY, {member: due_at})
 
     async def due_deadlines(self, now: float, limit: int = 32) -> List[str]:
+        # ``ZRANGE ... BYSCORE`` is the non-deprecated spelling of the
+        # old ``ZRANGEBYSCORE``.
         members = cast(
             list,
-            await self._redis.zrangebyscore(
+            await self._redis.zrange(
-                DEADLINES_KEY, "-inf", now, start=0, num=limit
+                DEADLINES_KEY,
+                "-inf",
+                now,
+                byscore=True,
+                offset=0,
+                num=limit,
             ),
         )
         return [m.decode("utf-8") if isinstance(m, bytes) else m for m in members]
@@ -229,6 +282,20 @@ class RedisGameStore(GameStore):
     async def remove_deadline(self, member: str) -> None:
         await self._redis.zrem(DEADLINES_KEY, member)
 
+    async def notify_deadline(self) -> None:
+        await self._redis.publish(DEADLINES_CHANNEL, "deadline")
+
+    @contextlib.asynccontextmanager
+    async def subscribe_deadlines(self) -> AsyncIterator[AsyncIterator[None]]:
+        pubsub = self._redis.pubsub()
+        await pubsub.subscribe(DEADLINES_CHANNEL)
+        try:
+            yield _redis_events(pubsub)
+        finally:
+            with contextlib.suppress(Exception):
+                await pubsub.unsubscribe(DEADLINES_CHANNEL)
+                await pubsub.aclose()
+
 
 async def _redis_events(pubsub) -> AsyncIterator[None]:
     async for message in pubsub.listen():
@@ -243,9 +310,11 @@ class InMemoryGameStore(GameStore):
         self._registry = registry
         self._games: Dict[str, str] = {}
         self._codes: Dict[str, str] = {}
+        self._ongoing: Set[str] = set()
         self._locks: Dict[str, asyncio.Lock] = {}
         self._subscribers: Dict[str, Set[asyncio.Queue]] = {}
         self._deadlines: Dict[str, float] = {}
+        self._deadline_subscribers: Set[asyncio.Queue] = set()
 
     def _lock_for(self, game_id: str) -> asyncio.Lock:
         lock = self._locks.get(game_id)
@@ -268,6 +337,11 @@ class InMemoryGameStore(GameStore):
     async def save(self, session: GameSession) -> None:
         self._games[session.id] = json.dumps(session_to_json(session, self._registry))
         self._codes[session.join_code] = session.id
+        engine = self._registry.require(session.game_type)
+        if engine.is_finished(session):
+            self._ongoing.discard(session.id)
+        else:
+            self._ongoing.add(session.id)
 
     async def find_by_code(self, code: str) -> Optional[GameSession]:
         game_id = self._codes.get(code.upper())
@@ -275,6 +349,9 @@ class InMemoryGameStore(GameStore):
             return None
         return await self.load(game_id)
 
+    async def count_ongoing(self) -> int:
+        return len(self._ongoing)
+
     @contextlib.asynccontextmanager
     async def subscribe(self, game_id: str) -> AsyncIterator[AsyncIterator[None]]:
         queue: asyncio.Queue = asyncio.Queue()
@@ -306,6 +383,19 @@ class InMemoryGameStore(GameStore):
     async def remove_deadline(self, member: str) -> None:
         self._deadlines.pop(member, None)
 
+    async def notify_deadline(self) -> None:
+        for queue in list(self._deadline_subscribers):
+            queue.put_nowait(_BUMP)
+
+    @contextlib.asynccontextmanager
+    async def subscribe_deadlines(self) -> AsyncIterator[AsyncIterator[None]]:
+        queue: asyncio.Queue = asyncio.Queue()
+        self._deadline_subscribers.add(queue)
+        try:
+            yield _queue_events(queue)
+        finally:
+            self._deadline_subscribers.discard(queue)
+
 
 async def _queue_events(queue: asyncio.Queue) -> AsyncIterator[None]:
     while True:

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

@@ -2,12 +2,21 @@
 
 Clients connect to ``/ws/games/{game_id}`` using their session cookie
 (the OIDC login stores the user in the session, which the session mixin
-loads onto the websocket). Only seated players are accepted.
+loads onto the websocket). Anyone who knows the game id is accepted:
+seated players get their personalized view, everyone else — anonymous
+users and authenticated users who are not seated — is a read-only
+**spectator** receiving the view without privileged information (no
+hands, no legal moves). The game view carries ``spectator: true`` for
+them and never carries the join code. Spectator actions other than
+``state``/``sync`` are rejected with a ``forbidden`` error; seating is
+re-checked under the game lock so a viewer who joins mid-connection
+immediately gains (and, if they somehow left, would lose) the right to
+act.
 
-The platform owns the connection lifecycle — authentication, seat
+The platform owns the connection lifecycle — authentication, the
-check, the subscription/publish fan-out and the message envelope — and
+subscription/publish fan-out and the message envelope — and delegates
-delegates the game-specific actions to the engine registered for the
+the game-specific actions to the engine registered for the session's
-session's ``game_type``.
+``game_type``.
 
 Protocol
 --------
@@ -27,9 +36,10 @@ Client -> server messages are JSON objects::
 
 For scopone scientifico the game actions are ``play`` (with ``card``
 and optionally ``capture``) and ``ack`` — see
-:mod:`tavolo.scopone.plugin`. Because the whole message (minus
+:mod:`tavolo.scopone.plugin`; briscola uses ``play`` with just ``card``
-``action``) is handed to the engine as the payload, games define their
+plus ``ack`` — see :mod:`tavolo.briscola.plugin`. Because the whole
-own fields freely.
+message (minus ``action``) is handed to the engine as the payload, games
+define their own fields freely.
 
 Mutations run under the per-game lock; after a successful action the new
 session is saved and a change signal is published. Every connected
@@ -48,9 +58,9 @@ import asyncio
 import json
 from contextlib import suppress
 from logging import getLogger
-from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, Optional
 
-from kaya.core import KayaApp, WebSocket
+from kaya.core import KayaApp, WebSocket, WebSocketDisconnect
 
 from . import auth
 from .engine import GameSession
@@ -68,17 +78,39 @@ def _error(message: str, code: str = "invalid") -> Dict[str, Any]:
     return {"type": "error", "code": code, "message": message}
 
 
-def _state_message(platform: "Platform", session: GameSession, sub: str) -> Dict[str, Any]:
+async def _reject(ws: WebSocket, status: int) -> None:
+    """Refuse a websocket upgrade with the HTTP ``status``.
+
+    Rejections happen before :meth:`WebSocket.accept`, so ``close()``
+    carries the HTTP status of the refused upgrade rather than a
+    WebSocket close code: ASGI servers answer ``403`` per the spec, and
+    RSGI (granian) uses the value verbatim as the response status.
+    Passing a 4xxx close code here would panic granian's RSGI layer on
+    the invalid status — and since granian is built with
+    ``panic = "abort"``, that kills the worker and takes the whole app
+    down.
+    """
+    await ws.close(status)
+
+
+def _state_message(
+    platform: "Platform", session: GameSession, sub: Optional[str]
+) -> Dict[str, Any]:
     engine = platform.registry.require(session.game_type)
-    return {
+    seated = sub is not None and session.seated(sub)
-        "type": "state",
+    payload: Dict[str, Any] = {
-        "game": {
         "id": session.id,
-            "join_code": session.join_code,
         "game_type": session.game_type,
-            **engine.view_for(session, sub),
+        "spectator": not seated,
-        },
+        # Free chairs; the lobby view needs it for games with other player
+        # counts than four.
+        "seats_open": max(0, engine.max_players - len(session.players)),
     }
+    if seated:
+        # The join code is a credential: only players get it.
+        payload["join_code"] = session.join_code
+    payload.update(engine.view_for(session, sub))
+    return {"type": "state", "game": payload}
 
 
 def register(app: KayaApp, platform: "Platform") -> None:
@@ -86,32 +118,33 @@ def register(app: KayaApp, platform: "Platform") -> None:
 
     @app.websocket("/ws/games/${game_id}")
     async def game_socket(ws: WebSocket, game_id: str) -> None:
+        # Anonymous and non-seated viewers are welcome as read-only
+        # spectators; only an unknown game id is refused.
         user = auth.get_ws_user(ws)
-        if user is None:
+        sub: Optional[str] = user.sub if user is not None else None
-            log.debug("websocket %s rejected: no authenticated user", game_id)
-            await ws.close(4401)
-            return
 
         session = await platform.game_store.load(game_id)
         if session is None:
             log.debug("websocket rejected: unknown game %s", game_id)
-            await ws.close(4404)
+            await _reject(ws, 404)
-            return
-        if not session.seated(user.sub):
-            log.debug("websocket %s rejected: %s is not seated", game_id, user.sub)
-            await ws.close(4403)
             return
 
         await ws.accept()
-        log.info("%s connected to game %s", user.sub, game_id)
+        log.info("%s connected to game %s", sub or "spectator", game_id)
 
         send_lock = asyncio.Lock()
 
         async def send(payload: Dict[str, Any]) -> None:
             async with send_lock:
+                try:
                     await ws.send_text(json.dumps(payload))
+                except WebSocketDisconnect:
+                    # The peer went away without a close handshake: kaya
+                    # raises this from the transport, and the receive loop
+                    # ends momentarily.
+                    pass
 
-        await send(_state_message(platform, session, user.sub))
+        await send(_state_message(platform, session, sub))
         # Backstop: make sure the current deadline is queued even if its
         # entry was lost (e.g. the queue was flushed while the game lived
         # on thanks to its sliding TTL).
@@ -119,7 +152,7 @@ def register(app: KayaApp, platform: "Platform") -> None:
 
         async with platform.game_store.subscribe(game_id) as events:
             forward = asyncio.create_task(
-                _forward(platform, events, game_id, user.sub, send)
+                _forward(platform, events, game_id, sub, send)
             )
             try:
                 async for message in ws:
@@ -128,19 +161,19 @@ def register(app: KayaApp, platform: "Platform") -> None:
                     if message.kind != "text" or not isinstance(message.data, str):
                         await send(_error("expected a text frame with a JSON object"))
                         continue
-                    await _handle_message(platform, send, game_id, user.sub, message.data)
+                    await _handle_message(platform, send, game_id, sub, message.data)
             finally:
                 forward.cancel()
                 with suppress(asyncio.CancelledError):
                     await forward
-                log.debug("%s disconnected from game %s", user.sub, game_id)
+                log.debug("%s disconnected from game %s", sub or "spectator", game_id)
 
 
 async def _forward(
     platform: "Platform",
     events,
     game_id: str,
-    sub: str,
+    sub: Optional[str],
     send: Send,
 ) -> None:
     async for _ in events:
@@ -160,7 +193,7 @@ async def _forward(
 
 
 async def _handle_message(
-    platform: "Platform", send: Send, game_id: str, sub: str, raw: str
+    platform: "Platform", send: Send, game_id: str, sub: Optional[str], raw: str
 ) -> None:
     try:
         data = json.loads(raw)
@@ -189,7 +222,7 @@ async def _handle_action(
     platform: "Platform",
     send: Send,
     game_id: str,
-    sub: str,
+    sub: Optional[str],
     action: str,
     data: Dict[str, Any],
 ) -> None:
@@ -198,6 +231,13 @@ async def _handle_action(
         if session is None:
             await send(_error("game not found", code="not_found"))
             return
+        # Re-check seating under the lock: an anonymous spectator stays a
+        # spectator forever, while a logged-in viewer who joins the game
+        # mid-connection becomes a player and may act from then on.
+        if sub is None or not session.seated(sub):
+            log.debug("game %s: rejected %r from a spectator", game_id, action)
+            await send(_error("spectators cannot act on the game", code="forbidden"))
+            return
         engine = platform.registry.require(session.game_type)
         payload = {key: value for key, value in data.items() if key != "action"}
         try:

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

@@ -8,7 +8,7 @@ without importing any real game. Its rules: the first player to reach
 ``target`` plays wins the match.
 
 :func:`make_platform` builds a throwaway :class:`~kaya.core.KayaApp`
-wired with in-memory stores, a dummy OIDC mixin (patched per test) and
+wired with in-memory stores, dummy OIDC providers (patched per test) and
 a sqlite :class:`~tavolo.platform.tortoise_mixin.TortoiseMixin`, so
 tests construct their own app instead of importing a global one.
 """
@@ -22,7 +22,7 @@ from functools import wraps
 from typing import Any, Callable, Coroutine, Dict, Iterator, List, Mapping, Optional, Sequence, Tuple
 
 from kaya.core import KayaApp
-from kaya.oidc import OIDCConfig, OIDCMixin, OIDCUser
+from kaya.oidc import OIDCConfig, OIDCProviders, OIDCUser
 from kaya.openapi import OpenAPIMixin
 from kaya.session import InMemorySessionStore, SessionMixin
 
@@ -138,7 +138,7 @@ class DummyEngine(GameEngine):
             state["finished"] = True
             state["winner"] = user_sub
 
-    def view_for(self, session: GameSession, user_sub: str) -> Dict[str, Any]:
+    def view_for(self, session: GameSession, user_sub: Optional[str]) -> Dict[str, Any]:
         state = session.state
         return {
             "started": state["started"],
@@ -146,7 +146,7 @@ class DummyEngine(GameEngine):
             "winner": state["winner"],
             "plays": len(state["plays"]),
             "target": state["target"],
-            "viewer_seated": session.seated(user_sub),
+            "viewer_seated": user_sub is not None and session.seated(user_sub),
         }
 
     def lobby_view(self, session: GameSession) -> Dict[str, Any]:
@@ -220,20 +220,26 @@ class DummyEngine(GameEngine):
 
 def make_platform(
     engines: Sequence[GameEngine] = (DummyEngine(),),
+    heartbeat_ms: int = 50,
+    oidc_providers: Sequence[str] = ("default",),
 ) -> Tuple[KayaApp, Platform, TortoiseMixin]:
     """Build a throwaway app + platform wired with in-memory stores."""
     registry = GameRegistry(engines)
     game_store = InMemoryGameStore(registry)
     session_mixin = SessionMixin(InMemorySessionStore())
-    oidc_mixin = OIDCMixin(
+    oidc = OIDCProviders(
+        [
             OIDCConfig(
-            issuer="http://localhost:8180/tavolo",
+                provider=name,
+                issuer=f"http://localhost:8180/{name}",
                 client_id="tavolo",
                 client_secret=None,
-            redirect_uri="http://localhost:8080/auth/callback",
+                redirect_uri=f"http://localhost:8080/auth/{name}/callback",
                 post_login_redirect="/",
                 post_logout_redirect="/",
-        ),
+            )
+            for name in oidc_providers
+        ],
         session=session_mixin,
     )
     tortoise_mixin = TortoiseMixin(
@@ -251,19 +257,19 @@ def make_platform(
     scheduler = DeadlineScheduler(
         game_store,
         registry,
-        heartbeat_ms=50,
+        heartbeat_ms=heartbeat_ms,
         context_binder=tortoise_mixin.ensure_context,
     )
     platform = Platform(
         registry=registry,
         game_store=game_store,
         scheduler=scheduler,
-        oidc=oidc_mixin,
+        oidc=oidc,
     )
     app = KayaApp(
         mixins=[
             session_mixin,
-            oidc_mixin,
+            oidc,
             tortoise_mixin,
             openapi_mixin,
             PlatformMixin(platform),
@@ -319,10 +325,12 @@ def make_user(sub: str, name: Optional[str] = None) -> OIDCUser:
 
 
 @contextlib.contextmanager
-def oidc_user(oidc: OIDCMixin, sub: str, name: Optional[str] = None) -> Iterator[OIDCUser]:
+def oidc_user(oidc: OIDCProviders, sub: str, name: Optional[str] = None) -> Iterator[OIDCUser]:
-    """Context manager: patch ``oidc.get_user`` to return this user."""
+    """Context manager: make ``oidc.get_users`` return this user for the
+    first configured provider."""
     user = make_user(sub, name)
-    patcher = _mock.patch.object(oidc, "get_user", return_value=user)
+    provider = next(iter(oidc.providers))
+    patcher = _mock.patch.object(oidc, "get_users", return_value={provider: user})
     patcher.start()
     try:
         yield user

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

@@ -0,0 +1,152 @@
+"""Tests for the auth helpers' OIDC user lookup and gating.
+
+kaya-oidc (0.0.6) namespaces session state per provider as
+``oidc:{provider}:user`` and tavolo wires an :class:`OIDCProviders`; these
+tests pin both contracts so a kaya upgrade or a provider change cannot
+silently break HTTP or websocket authentication.
+"""
+from __future__ import annotations
+
+import unittest
+from types import SimpleNamespace
+from typing import Any
+
+from kaya.oidc import OIDCConfig, OIDCProviders
+from kaya.session import InMemorySessionStore, Session, SessionMixin
+
+from helpers import async_test
+from tavolo.platform.auth import current_user, get_ws_user, require_auth, session_user
+
+
+def _providers(*names: str) -> OIDCProviders:
+    session = SessionMixin(InMemorySessionStore())
+    return OIDCProviders(
+        [
+            OIDCConfig(
+                provider=name,
+                issuer=f"http://localhost:8180/{name}",
+                client_id="tavolo",
+                redirect_uri=f"http://localhost:8080/auth/{name}/callback",
+            )
+            for name in names
+        ],
+        session=session,
+    )
+
+
+def _ctx(data: Any) -> Any:
+    return SimpleNamespace(session=Session("sid", data))
+
+
+def _ws(session: Any) -> Any:
+    return SimpleNamespace(session=session)
+
+
+class SessionUserTest(unittest.TestCase):
+    def test_finds_default_provider_user(self) -> None:
+        user = session_user(Session("sid", {"oidc:default:user": {"sub": "alice"}}))
+        assert user is not None
+        self.assertEqual("alice", user.sub)
+
+    def test_finds_user_of_any_provider(self) -> None:
+        user = session_user(Session("sid", {"oidc:google:user": {"sub": "alice"}}))
+        assert user is not None
+        self.assertEqual("alice", user.sub)
+
+    def test_ignores_flow_state_and_tokens(self) -> None:
+        session = Session(
+            "sid",
+            {
+                "oidc:default:state": "state",
+                "oidc:default:id_token": "token",
+                "oidc:default:access_token": "token",
+            },
+        )
+        self.assertIsNone(session_user(session))
+
+    def test_ignores_legacy_unprefixed_user_key(self) -> None:
+        session = Session("sid", {"oidc_user": {"sub": "alice"}})
+        self.assertIsNone(session_user(session))
+
+    def test_ignores_malformed_user_claims(self) -> None:
+        session = Session("sid", {"oidc:default:user": "alice"})
+        self.assertIsNone(session_user(session))
+
+
+class GetWsUserTest(unittest.TestCase):
+    def test_returns_user_from_provider_namespaced_session(self) -> None:
+        session = Session(
+            "sid",
+            {"oidc:default:user": {"sub": "alice", "preferred_username": "Alice"}},
+        )
+        user = get_ws_user(_ws(session))
+        assert user is not None
+        self.assertEqual("alice", user.sub)
+
+    def test_missing_session_returns_none(self) -> None:
+        self.assertIsNone(get_ws_user(SimpleNamespace()))
+
+
+class CurrentUserTest(unittest.TestCase):
+    def test_anonymous_session_has_no_user(self) -> None:
+        self.assertIsNone(current_user(_providers("default"), _ctx({})))
+
+    def test_returns_the_authenticated_provider_user(self) -> None:
+        user = current_user(
+            _providers("default", "google"),
+            _ctx({"oidc:google:user": {"sub": "alice"}}),
+        )
+        assert user is not None
+        self.assertEqual("alice", user.sub)
+
+    def test_first_configured_provider_wins(self) -> None:
+        # Single-identity sessions never hold two users; this only pins the
+        # tie-break should they ever coexist.
+        user = current_user(
+            _providers("default", "google"),
+            _ctx(
+                {
+                    "oidc:default:user": {"sub": "alice"},
+                    "oidc:google:user": {"sub": "bob"},
+                }
+            ),
+        )
+        assert user is not None
+        self.assertEqual("alice", user.sub)
+
+
+class RequireAuthTest(unittest.TestCase):
+    @async_test
+    async def test_rejects_anonymous_requests(self) -> None:
+        oidc = _providers("default")
+        ctx = _ctx({})
+        sent = {}
+
+        async def send_bytes(*args: Any) -> None:
+            sent["status"] = args[0]
+
+        ctx.send_bytes = send_bytes
+        handled = []
+
+        @require_auth(oidc)
+        async def handler(_ctx: Any) -> None:
+            handled.append(True)
+
+        await handler(ctx)
+        self.assertEqual(401, sent["status"])
+        self.assertEqual([], handled)
+
+    @async_test
+    async def test_allows_authenticated_requests(self) -> None:
+        oidc = _providers("default")
+        ctx = _ctx({"oidc:default:user": {"sub": "alice"}})
+        handled = []
+
+        @require_auth(oidc)
+        async def handler(request_ctx: Any) -> None:
+            user = current_user(oidc, request_ctx)
+            assert user is not None
+            handled.append(user.sub)
+
+        await handler(ctx)
+        self.assertEqual(["alice"], handled)

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

@@ -112,6 +112,38 @@ async def _finished(store, game_id: str) -> Optional[GameSession]:
     return None
 
 
+class NotificationTest(unittest.TestCase):
+    """Deadline-enqueue notifications wake consumers on other workers."""
+
+    @async_test
+    async def test_notification_wakes_a_long_heartbeat_consumer(self) -> None:
+        # The consumer's heartbeat is a minute away and nothing sets its
+        # local wake event: only the pub/sub notification can deliver the
+        # deadline in time. This is the cross-worker path.
+        _, platform, _ = make_platform(heartbeat_ms=60_000)
+        store = platform.game_store
+        scheduler = platform.scheduler
+        session = _started_session(deadline_in_seconds=0.1)
+        await store.save(session)
+        scheduler.ensure_consumer()
+        # Let the listener task subscribe before announcing.
+        await asyncio.sleep(0.05)
+
+        engine = platform.registry.require(session.game_type)
+        deadline = engine.next_deadline(session)
+        assert deadline is not None
+        member = encode({
+            "game_id": session.id,
+            "kind": deadline.kind,
+            "token": deadline.token,
+        })
+        await store.add_deadline(member, deadline.due_at.timestamp())
+        await store.notify_deadline()
+
+        result = await _wait_for(lambda: _plays_is(store, session.id, 1))
+        self.assertIsNotNone(result, "notification did not wake the consumer")
+
+
 class ProcessDueTest(unittest.TestCase):
     """Direct ``process_due`` behaviour: engine revalidation and idempotency."""
 

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

@@ -0,0 +1,81 @@
+"""Keyset pagination tests: cursor values are restored to Python types.
+
+Cursors are JSON, so a cursor carrying a datetime reaches the next
+request as a string. Postgres/asyncpg rejects strings for timestamp
+parameters (sqlite silently coerces them), so ``paginate`` must run the
+decoded values through their model fields before building the WHERE
+clause.
+"""
+from __future__ import annotations
+
+import unittest
+import uuid
+from datetime import datetime, timezone
+from typing import Any, List
+
+from tavolo.platform.models import Match
+from tavolo.platform.pagination import Cursor, decode_cursor, encode_cursor, paginate
+
+from helpers import async_test
+
+SORT = [("finished_at", "DESC"), ("id", "ASC")]
+
+
+class _CapturingQuerySet:
+    """Minimal stand-in for a Tortoise QuerySet, recording its filter."""
+
+    model = Match
+
+    def __init__(self) -> None:
+        self.queryset_filter: Any = None
+
+    def order_by(self, *orderings: str) -> "_CapturingQuerySet":
+        return self
+
+    def filter(self, q: Any) -> "_CapturingQuerySet":
+        self.queryset_filter = q
+        return self
+
+    async def limit(self, count: int) -> List[Any]:
+        return []
+
+
+def _flatten_q(q: Any) -> List[Any]:
+    nodes = [q]
+    for child in q.children:
+        nodes.extend(_flatten_q(child))
+    return nodes
+
+
+def _filter_values(q: Any, key: str) -> List[Any]:
+    return [node.filters[key] for node in _flatten_q(q) if key in node.filters]
+
+
+class PaginateCursorTypesTest(unittest.TestCase):
+    @async_test
+    async def test_cursor_values_are_restored_before_filtering(self) -> None:
+        match_id = uuid.uuid4()
+        finished_at = datetime(2026, 9, 19, 5, 2, 50, 547904, tzinfo=timezone.utc)
+        # Round-trip through the wire format, exactly as a request does.
+        after = decode_cursor(
+            encode_cursor({"finished_at": finished_at, "id": match_id})
+        )
+        assert after is not None
+
+        qs = _CapturingQuerySet()
+        await paginate(qs, SORT, Cursor(limit=1, after=after))
+
+        assert qs.queryset_filter is not None
+        for key in ("finished_at", "finished_at__lt"):
+            values = _filter_values(qs.queryset_filter, key)
+            self.assertEqual(1, len(values))
+            self.assertIsInstance(values[0], datetime)
+            self.assertEqual(finished_at, values[0])
+        id_values = _filter_values(qs.queryset_filter, "id__gt")
+        self.assertEqual(1, len(id_values))
+        self.assertIsInstance(id_values[0], uuid.UUID)
+        self.assertEqual(match_id, id_values[0])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -44,10 +44,24 @@ class GamesRouteTest(unittest.TestCase):
             self.assertEqual(game_id, snap["id"])
             self.assertEqual("dummy", snap["game_type"])
             self.assertTrue(snap["viewer_seated"])
+            self.assertFalse(snap["spectator"])
+            self.assertIn("join_code", snap)
 
+            # A logged-in non-player is a read-only spectator: the view
+            # marks it and the join code is withheld.
             with oidc_user(platform.oidc, "mallory"):
-                forbidden = await client.get(f"/api/games/{game_id}")
+                watched = await client.get(f"/api/games/{game_id}")
-            self.assertEqual(403, forbidden.status_code)
+            self.assertEqual(200, watched.status_code)
+            spect = watched.json()
+            self.assertFalse(spect["viewer_seated"])
+            self.assertTrue(spect["spectator"])
+            self.assertNotIn("join_code", spect)
+
+            # Anonymous users may watch too.
+            anonymous = await client.get(f"/api/games/{game_id}")
+            self.assertEqual(200, anonymous.status_code)
+            self.assertTrue(anonymous.json()["spectator"])
+            self.assertNotIn("join_code", anonymous.json())
 
     @async_test
     async def test_join_starts_game(self) -> None:

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

@@ -0,0 +1,67 @@
+"""Tests for the provider-agnostic auth routes.
+
+``GET /api/auth/providers`` feeds the SPA's login buttons; ``/auth/login``
+and ``/auth/logout`` are the generic aliases that redirect to the right
+per-provider kaya route.
+"""
+from __future__ import annotations
+
+import unittest
+from unittest import mock
+
+from httpx import ASGITransport, AsyncClient
+
+from helpers import async_test, make_platform
+
+
+class AuthProvidersRouteTest(unittest.TestCase):
+    @async_test
+    async def test_lists_providers_in_configuration_order(self) -> None:
+        app, _platform, _tortoise = make_platform(oidc_providers=("default", "google"))
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            response = await client.get("/api/auth/providers")
+        self.assertEqual(200, response.status_code)
+        self.assertEqual(
+            {
+                "providers": [
+                    {"name": "default", "login_url": "/auth/default/login"},
+                    {"name": "google", "login_url": "/auth/google/login"},
+                ]
+            },
+            response.json(),
+        )
+
+
+class GenericAuthRedirectTest(unittest.TestCase):
+    @async_test
+    async def test_login_redirects_to_the_first_provider(self) -> None:
+        app, _platform, _tortoise = make_platform(oidc_providers=("google", "github"))
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            response = await client.get("/auth/login", follow_redirects=False)
+        self.assertEqual(302, response.status_code)
+        self.assertEqual("/auth/google/login", response.headers["location"])
+
+    @async_test
+    async def test_logout_redirects_to_the_logged_in_provider(self) -> None:
+        app, platform, _tortoise = make_platform()
+        with mock.patch.object(
+            platform.oidc, "logged_in_providers", return_value=["default"]
+        ):
+            transport = ASGITransport(app=app)
+            async with AsyncClient(
+                transport=transport, base_url="http://127.0.0.1"
+            ) as client:
+                response = await client.get("/auth/logout", follow_redirects=False)
+        self.assertEqual(302, response.status_code)
+        self.assertEqual("/auth/default/logout", response.headers["location"])
+
+    @async_test
+    async def test_logout_without_a_session_redirects_home(self) -> None:
+        app, _platform, _tortoise = make_platform()
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            response = await client.get("/auth/logout", follow_redirects=False)
+        self.assertEqual(302, response.status_code)
+        self.assertEqual("/", response.headers["location"])

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 import unittest
 import uuid
 from datetime import datetime, timezone
+from unittest import mock
 
 from httpx import ASGITransport, AsyncClient
 
@@ -197,6 +198,28 @@ class StatsRouteTest(unittest.TestCase):
                 second.json()["results"][0]["id"],
             )
 
+    @async_test
+    async def test_my_matches_fetches_participants_in_one_query(self) -> None:
+        app, platform, tortoise_mixin = make_platform()
+        await _seed_two_matches(tortoise_mixin)
+        transport = ASGITransport(app=app)
+        with mock.patch.object(
+            MatchPlayer, "filter", wraps=MatchPlayer.filter
+        ) as spy:
+            async with AsyncClient(
+                transport=transport, base_url="http://127.0.0.1"
+            ) as client:
+                with oidc_user(platform.oidc, "alice"):
+                    response = await client.get("/api/me/matches")
+        self.assertEqual(200, response.status_code)
+        # One query for all matches, not one per match row.
+        self.assertEqual(1, spy.call_count)
+        results = response.json()["results"]
+        self.assertEqual(2, len(results))
+        for result in results:
+            seats = [player["seat"] for player in result["players"]]
+            self.assertEqual([0, 1], seats)
+
     @async_test
     async def test_my_matches_requires_auth(self) -> None:
         app, _, _ = make_platform()

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

@@ -2,11 +2,18 @@
 from __future__ import annotations
 
 import asyncio
+import time
 import unittest
+from typing import Any, Optional, cast
 
 from tavolo.platform import GameSession, Seat
 from tavolo.platform.registry import GameRegistry
-from tavolo.platform.store import InMemoryGameStore
+from tavolo.platform.store import (
+    DEADLINES_KEY,
+    ONGOING_GAMES_KEY,
+    InMemoryGameStore,
+    RedisGameStore,
+)
 from helpers import DummyEngine, async_test
 
 
@@ -27,6 +34,110 @@ def _session(game_id: str = "g1", code: str = "CODE01") -> GameSession:
     return session
 
 
+class _FakePipeline:
+    """Records commands and applies them to the fake Redis on execute."""
+
+    def __init__(self, redis: "_FakeRedis") -> None:
+        self._redis = redis
+        self._ops: list = []
+
+    async def __aenter__(self) -> "_FakePipeline":
+        return self
+
+    async def __aexit__(self, *exc: object) -> bool:
+        return False
+
+    def set(self, key: str, value: str, ex: object = None) -> None:
+        self._ops.append(("set", key))
+
+    def zadd(self, key: str, mapping: dict) -> None:
+        self._ops.append(("zadd", key, mapping))
+
+    def zrem(self, key: str, member: str) -> None:
+        self._ops.append(("zrem", key, member))
+
+    def expire(self, key: str, ttl: int) -> None:
+        self._ops.append(("expire", key))
+
+    def zremrangebyscore(self, key: str, minimum: object, maximum: object) -> None:
+        self._ops.append(("zremrangebyscore", key))
+
+    def zcard(self, key: str) -> None:
+        self._ops.append(("zcard", key))
+
+    async def execute(self) -> list:
+        results = [self._redis.apply(op) for op in self._ops]
+        self._ops = []
+        return results
+
+
+class _FakeRedis:
+    """The slice of the Redis client the game store uses."""
+
+    def __init__(self) -> None:
+        self.keys: dict = {}
+        self.zsets: dict = {}
+        self.zrange_calls: list = []
+
+    def pipeline(self, transaction: bool = True) -> _FakePipeline:
+        return _FakePipeline(self)
+
+    async def zadd(self, key: str, mapping: dict) -> int:
+        return cast(int, self.apply(("zadd", key, mapping)))
+
+    async def zrem(self, key: str, member: str) -> int:
+        return cast(int, self.apply(("zrem", key, member)))
+
+    async def zrange(
+        self,
+        name: str,
+        start: Any,
+        end: Any,
+        byscore: bool = False,
+        offset: Optional[int] = None,
+        num: Optional[int] = None,
+        **kwargs: object,
+    ) -> list:
+        self.zrange_calls.append((name, start, end, byscore, offset, num))
+        members = sorted(
+            self.zsets.get(name, {}).items(), key=lambda item: item[1]
+        )
+        if byscore:
+            low = float("-inf") if start == "-inf" else float(start)
+            high = float("inf") if end == "+inf" else float(end)
+            members = [item for item in members if low <= item[1] <= high]
+        if offset is not None and num is not None:
+            members = members[offset : offset + num]
+        return [member for member, _ in members]
+
+    def apply(self, op: tuple) -> object:
+        name, *args = op
+        if name == "set":
+            self.keys[args[0]] = "payload"
+            return True
+        if name == "zadd":
+            self.zsets.setdefault(args[0], {}).update(args[1])
+            return 1
+        if name == "zrem":
+            self.zsets.get(args[0], {}).pop(args[1], None)
+            return 1
+        if name == "expire":
+            return True
+        if name == "zremrangebyscore":
+            zset = self.zsets.get(args[0], {})
+            for member in [
+                member
+                for member, score in zset.items()
+                if score <= time.time()
+            ]:
+                del zset[member]
+            return 0
+        if name == "zcard":
+            return len(self.zsets.get(args[0], {}))
+        raise AssertionError(f"unexpected command: {name}")
+
+
+
 class InMemoryGameStoreTest(unittest.TestCase):
     @async_test
     async def test_save_load_roundtrip(self) -> None:
@@ -114,6 +225,28 @@ class InMemoryGameStoreTest(unittest.TestCase):
             ["holder-enter", "holder-exit", "contender"], order
         )
 
+    @async_test
+    async def test_count_ongoing_tracks_unfinished_games(self) -> None:
+        store = InMemoryGameStore(_registry())
+        self.assertEqual(0, await store.count_ongoing())
+
+        session = _session()
+        await store.save(session)
+        self.assertEqual(1, await store.count_ongoing())
+
+        other = _session(game_id="g2", code="CODE02")
+        await store.save(other)
+        self.assertEqual(2, await store.count_ongoing())
+
+        # A finished match is retained for the final board but no longer
+        # counts as ongoing.
+        session.state["finished"] = True
+        await store.save(session)
+        self.assertEqual(1, await store.count_ongoing())
+        other.state["finished"] = True
+        await store.save(other)
+        self.assertEqual(0, await store.count_ongoing())
+
     @async_test
     async def test_deadline_queue(self) -> None:
         store = InMemoryGameStore(_registry())
@@ -137,6 +270,65 @@ class InMemoryGameStoreTest(unittest.TestCase):
         self.assertEqual(60.0, await store.next_deadline())
         self.assertEqual(["b"], await store.due_deadlines(now=100.0))
 
+    @async_test
+    async def test_deadline_notifications_reach_subscribers(self) -> None:
+        store = InMemoryGameStore(_registry())
+        async with store.subscribe_deadlines() as events:
+            await store.notify_deadline()
+            signal = await asyncio.wait_for(anext(events), timeout=1.0)
+            self.assertIsNone(signal)
+        # The subscription is gone after the context exits: notifying
+        # again is a no-op rather than an error.
+        await store.notify_deadline()
+
+
+class RedisGameStoreTest(unittest.TestCase):
+    @async_test
+    async def test_save_marks_games_ongoing_and_finished_ones_stop_counting(self) -> None:
+        redis = _FakeRedis()
+        store = RedisGameStore(redis, _registry(), ttl_seconds=3600)  # type: ignore[arg-type]
+        session = _session()
+
+        await store.save(session)
+        self.assertEqual(1, await store.count_ongoing())
+        score = redis.zsets[ONGOING_GAMES_KEY][session.id]
+        self.assertGreater(score, time.time())
+        self.assertLessEqual(score, time.time() + 3600)
+
+        session.state["finished"] = True
+        await store.save(session)
+        self.assertNotIn(session.id, redis.zsets[ONGOING_GAMES_KEY])
+        self.assertEqual(0, await store.count_ongoing())
+
+    @async_test
+    async def test_count_ongoing_prunes_expired_entries(self) -> None:
+        redis = _FakeRedis()
+        redis.zsets[ONGOING_GAMES_KEY] = {
+            "stale": time.time() - 10,
+            "live": time.time() + 100,
+        }
+        store = RedisGameStore(redis, _registry())  # type: ignore[arg-type]
+        self.assertEqual(1, await store.count_ongoing())
+        self.assertNotIn("stale", redis.zsets[ONGOING_GAMES_KEY])
+
+    @async_test
+    async def test_due_deadlines_uses_zrange_byscore(self) -> None:
+        redis = _FakeRedis()
+        store = RedisGameStore(redis, _registry())  # type: ignore[arg-type]
+        await store.add_deadline("b", due_at=50.0)
+        await store.add_deadline("a", due_at=10.0)
+        await store.add_deadline("c", due_at=200.0)
+        # Re-adding an existing member only updates its due time.
+        await store.add_deadline("b", due_at=60.0)
+
+        self.assertEqual(["a"], await store.due_deadlines(now=20.0))
+        self.assertEqual(
+            [(DEADLINES_KEY, "-inf", 20.0, True, 0, 32)], redis.zrange_calls
+        )
+        # Matches come back in due-time order and honour the limit.
+        self.assertEqual(["a"], await store.due_deadlines(now=100.0, limit=1))
+        self.assertEqual(["a", "b"], await store.due_deadlines(now=100.0))
+
 
 if __name__ == "__main__":
     unittest.main()

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

@@ -1,15 +1,92 @@
 """WebSocket live-play tests via kaya's ASGI websocket transport."""
 from __future__ import annotations
 
+import json
 import unittest
+from typing import Any, Dict, Mapping, Sequence
 
 from httpx import ASGITransport, AsyncClient
-from httpx_ws import WebSocketDisconnect, aconnect_ws
+from httpx_ws import WebSocketDisconnect as HttpxWebSocketDisconnect, aconnect_ws
 from httpx_ws.transport import ASGIWebSocketTransport
+from kaya.core import WebSocket, WebSocketDisconnect, WebSocketMessage
 
 from helpers import async_test, make_platform, make_user, oidc_user, ws_users
 
 
+class AbruptCloseSocket(WebSocket):
+    """A socket whose peer vanished without a close handshake.
+
+    kaya surfaces this from the transport: ``receive()`` reports a
+    ``close`` message so iteration ends normally, while sends raise
+    ``WebSocketDisconnect``.
+    """
+
+    def __init__(self, path: str, gone: bool = False) -> None:
+        self.path = path
+        self.query_string = ""
+        self.scheme = "ws"
+        self.headers: Mapping[str, Sequence[str]] = {}
+        self.client = ("127.0.0.1", 12345)
+        self.server = ("127.0.0.1", 80)
+        self.sent: list[Dict[str, Any]] = []
+        self.close_codes: list[int] = []
+        self.gone = gone
+
+    async def accept(self, headers: Any = None) -> None:
+        pass
+
+    async def receive(self) -> WebSocketMessage:
+        self.gone = True
+        return WebSocketMessage(kind="close")
+
+    async def send_text(self, data: str) -> None:
+        if self.gone:
+            raise WebSocketDisconnect(code=1006)
+        self.sent.append(json.loads(data))
+
+    async def send_bytes(self, data: bytes) -> None:
+        if self.gone:
+            raise WebSocketDisconnect(code=1006)
+
+    async def close(self, code: int = 1000) -> None:
+        self.close_codes.append(code)
+
+    async def __anext__(self) -> WebSocketMessage:
+        await self.receive()
+        raise StopAsyncIteration
+
+
+class RecordingSocket(WebSocket):
+    """A socket that only records pre-accept rejections."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self.query_string = ""
+        self.scheme = "ws"
+        self.headers: Mapping[str, Sequence[str]] = {}
+        self.client = ("127.0.0.1", 12345)
+        self.server = ("127.0.0.1", 80)
+        self.close_codes: list[int] = []
+
+    async def accept(self, headers: Any = None) -> None:
+        raise AssertionError("a rejected socket must not be accepted")
+
+    async def receive(self) -> WebSocketMessage:
+        raise AssertionError("a rejected socket must not receive")
+
+    async def send_text(self, data: str) -> None:
+        raise AssertionError("a rejected socket must not send")
+
+    async def send_bytes(self, data: bytes) -> None:
+        raise AssertionError("a rejected socket must not send")
+
+    async def close(self, code: int = 1000) -> None:
+        self.close_codes.append(code)
+
+    async def __anext__(self) -> WebSocketMessage:
+        raise AssertionError("a rejected socket must not receive")
+
+
 class WebSocketTest(unittest.TestCase):
     async def _started_game(self, client: AsyncClient, oidc, target: int = 3) -> dict:
         """Create a game and seat both players; return the started state."""
@@ -39,6 +116,9 @@ class WebSocketTest(unittest.TestCase):
                         self.assertEqual("dummy", first["game"]["game_type"])
                         self.assertEqual(0, first["game"]["plays"])
                         self.assertEqual(game_id, first["game"]["id"])
+                        # Seated players get the join code; spectators don't.
+                        self.assertIn("join_code", first["game"])
+                        self.assertFalse(first["game"]["spectator"])
 
                         async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as alice_ws:
                             alice_first = await alice_ws.receive_json()
@@ -52,6 +132,33 @@ class WebSocketTest(unittest.TestCase):
                             self.assertEqual("state", update["type"])
                             self.assertEqual(1, update["game"]["plays"])
 
+    @async_test
+    async def test_state_reports_open_seats(self) -> None:
+        app, platform, _ = make_platform()
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            with oidc_user(platform.oidc, "alice"):
+                created = await client.post("/api/games", json={})
+            game_id = created.json()["id"]
+            code = created.json()["join_code"]
+
+            ws_transport = ASGIWebSocketTransport(app=app)
+            async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+                with ws_users([make_user("alice")]):
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
+                        first = await ws.receive_json()
+                        self.assertEqual(1, first["game"]["seats_open"])
+
+            # Once the second player joins the match starts and no seat is
+            # left open.
+            with oidc_user(platform.oidc, "bob"):
+                await client.post("/api/games/join", json={"code": code})
+            async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+                with ws_users([make_user("alice")]):
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
+                        first = await ws.receive_json()
+                        self.assertEqual(0, first["game"]["seats_open"])
+
     @async_test
     async def test_unknown_action_returns_error(self) -> None:
         app, platform, _ = make_platform()
@@ -87,6 +194,38 @@ class WebSocketTest(unittest.TestCase):
                         resent = await bob_ws.receive_json()
                         self.assertEqual("state", resent["type"])
 
+    @async_test
+    async def test_abrupt_disconnect_is_not_an_error(self) -> None:
+        app, platform, _ = make_platform()
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_game(client, platform.oidc)
+        game_id = state["id"]
+
+        ws = AbruptCloseSocket(f"/ws/games/{game_id}")
+        with ws_users([make_user("bob")]):
+            # kaya reports a peer that vanished without a close handshake as
+            # a close message; the handler must exit cleanly.
+            await app.handle_websocket(ws)
+        self.assertEqual("state", ws.sent[0]["type"])
+        self.assertEqual([], ws.close_codes)
+
+    @async_test
+    async def test_send_on_vanished_peer_is_ignored(self) -> None:
+        app, platform, _ = make_platform()
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_game(client, platform.oidc)
+        game_id = state["id"]
+
+        ws = AbruptCloseSocket(f"/ws/games/{game_id}", gone=True)
+        with ws_users([make_user("bob")]):
+            # Sending raises WebSocketDisconnect; the handler swallows it
+            # rather than letting it escape the forward task.
+            await app.handle_websocket(ws)
+        self.assertEqual([], ws.sent)
+        self.assertEqual([], ws.close_codes)
+
     @async_test
     async def test_game_over_broadcast(self) -> None:
         app, platform, _ = make_platform()
@@ -121,13 +260,13 @@ class WebSocketTest(unittest.TestCase):
         ws_transport = ASGIWebSocketTransport(app=app)
         async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
             with ws_users([make_user("alice")]):
-                with self.assertRaises(WebSocketDisconnect) as caught:
+                with self.assertRaises(HttpxWebSocketDisconnect) as caught:
                     async with aconnect_ws("/ws/games/no-such-game", ws_client):
                         pass
-                self.assertEqual(4404, caught.exception.code)
+                self.assertEqual(404, caught.exception.code)
 
     @async_test
-    async def test_non_player_is_closed(self) -> None:
+    async def test_non_player_watches_as_spectator(self) -> None:
         app, platform, _ = make_platform()
         api_transport = ASGITransport(app=app)
         async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
@@ -137,21 +276,62 @@ class WebSocketTest(unittest.TestCase):
             ws_transport = ASGIWebSocketTransport(app=app)
             async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
                 with ws_users([make_user("mallory")]):
-                    with self.assertRaises(WebSocketDisconnect) as caught:
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
-                        async with aconnect_ws(f"/ws/games/{game_id}", ws_client):
+                        first = await ws.receive_json()
-                            pass
+                        self.assertEqual("state", first["type"])
-                    self.assertEqual(4403, caught.exception.code)
+                        self.assertTrue(first["game"]["spectator"])
+                        self.assertFalse(first["game"]["viewer_seated"])
+                        self.assertNotIn("join_code", first["game"])
+                        # Spectators may not act.
+                        await ws.send_json({"action": "play"})
+                        error = await ws.receive_json()
+                        self.assertEqual("error", error["type"])
+                        self.assertEqual("forbidden", error["code"])
 
     @async_test
-    async def test_unauthenticated_is_closed(self) -> None:
+    async def test_anonymous_user_watches_as_spectator(self) -> None:
-        app, _, _ = make_platform()
+        app, platform, _ = make_platform()
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_game(client, platform.oidc)
+            game_id = state["id"]
+
             ws_transport = ASGIWebSocketTransport(app=app)
             async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
                 with ws_users([]):
-                with self.assertRaises(WebSocketDisconnect) as caught:
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
-                    async with aconnect_ws("/ws/games/whatever", ws_client):
+                        first = await ws.receive_json()
-                        pass
+                        self.assertEqual("state", first["type"])
-                self.assertEqual(4401, caught.exception.code)
+                        self.assertTrue(first["game"]["spectator"])
+                        self.assertNotIn("join_code", first["game"])
+                        await ws.send_json({"action": "play"})
+                        error = await ws.receive_json()
+                        self.assertEqual("error", error["type"])
+                        self.assertEqual("forbidden", error["code"])
+
+
+class RejectionStatusTest(unittest.TestCase):
+    """Pre-accept rejections must carry HTTP statuses, not close codes.
+
+    Granian's RSGI layer uses the value passed to ``close()`` before
+    ``accept()`` as the HTTP status of the refused upgrade; a WebSocket
+    close code like 4401 is not a valid status and panics the worker
+    (``InvalidStatusCode``, and with ``panic = "abort"`` the whole app
+    dies). Drive the rejection through the app with a recording socket
+    so the invariant is checked without a real server. Spectators are
+    accepted, so the only pre-accept rejection left is an unknown game.
+    """
+
+    @async_test
+    async def test_unknown_game_rejection_is_an_http_status(self) -> None:
+        app, _, _ = make_platform()
+        for label, users in (("anonymous", []), ("logged in", [make_user("alice")])):
+            ws = RecordingSocket("/ws/games/no-such-game")
+            with ws_users(users):
+                await app.handle_websocket(ws)
+            self.assertEqual([404], ws.close_codes, label)
+            for code in ws.close_codes:
+                self.assertTrue(100 <= code <= 599, f"{label}: {code} is not an HTTP status")
 
 
 if __name__ == "__main__":

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

@@ -528,13 +528,14 @@ def hand_points(state: ScoponeState) -> Tuple[List[int], Dict[str, object]]:
     return points, details
 
 
-def state_for_player(state: ScoponeState, sub: str) -> Dict[str, object]:
+def state_for_player(state: ScoponeState, sub: Optional[str]) -> Dict[str, object]:
     """Serialize ``state`` hiding other players' hands.
 
     Hands are reduced to a count, except for the requesting player's own
-    hand. Non-seated viewers simply see no hand at all. The platform
+    hand. Non-seated viewers — including spectators, for whom ``sub`` is
-    merges the session envelope (``id``, ``join_code``, ``game_type``)
+    ``None`` — simply see no hand at all. The platform merges the session
-    into the view itself.
+    envelope (``id``, ``join_code`` for seated players, ``game_type``,
+    ``spectator``) into the view itself.
     """
     viewer = state.player_for(sub)
     players: List[Dict[str, object]] = []

server/packages/tavolo-scopone/src/tavolo/scopone/plugin.py

@@ -171,13 +171,13 @@ class ScoponeEngine(GameEngine):
         else:
             raise IllegalMove(f"unknown action: {action!r}")
 
-    def view_for(self, session: GameSession, user_sub: str) -> Dict[str, Any]:
+    def view_for(self, session: GameSession, user_sub: Optional[str]) -> Dict[str, Any]:
         return engine.state_for_player(session.state, user_sub)
 
     def is_finished(self, session: GameSession) -> bool:
         return session.state.phase == PHASE_FINISHED
 
-    def game_over_view(self, session: GameSession, user_sub: str) -> Dict[str, Any]:
+    def game_over_view(self, session: GameSession, user_sub: Optional[str]) -> Dict[str, Any]:
         state: ScoponeState = session.state
         return {
             "scores": {"A": state.scores[0], "B": state.scores[1]},

server/packages/tavolo-scopone/src/tavolo/scopone/state.py

@@ -239,7 +239,7 @@ class ScoponeState:
 
     # -- helpers ----------------------------------------------------------
 
-    def player_for(self, sub: str) -> Optional[PlayerState]:
+    def player_for(self, sub: Optional[str]) -> Optional[PlayerState]:
         for player in self.players:
             if player.sub == sub:
                 return player

server/packages/tavolo-scopone/tests/test_engine.py

@@ -574,6 +574,27 @@ class MatchFlowTest(unittest.TestCase):
         self.assertEqual(["07C"], view["table"])
         self.assertTrue(view.get("your_turn"))
 
+    def test_state_for_player_spectator_sees_public_info_only(self) -> None:
+        state = make_state(
+            [["02D", "03C"], ["04D"], ["05D"], ["06D"]],
+            table=["07C"],
+            captured=[["01D"], [], ["02C"], ["03B"]],
+            scope=[1, 0, 2, 0],
+        )
+        view = engine.state_for_player(state, None)
+        for player in view["players"]:
+            self.assertNotIn("hand", player)
+        self.assertNotIn("your_turn", view)
+        self.assertNotIn("legal_moves", view)
+        # The public table state is still fully visible.
+        self.assertEqual(["07C"], view["table"])
+        self.assertEqual({"A": 0, "B": 0}, view["scores"])
+        players = {p["seat"]: p for p in view["players"]}
+        self.assertEqual(1, players[0]["captured_count"])
+        self.assertEqual(1, players[0]["scope"])
+        self.assertEqual(2, players[2]["scope"])
+        self.assertEqual(1, players[1]["cards_left"])
+
     def test_legal_moves_only_for_player_on_turn(self) -> None:
         state = make_state([["02D", "03C"], ["04D"], ["05D"], ["06D"]],
                            table=["07C"])

server/packages/tavolo-scopone/tests/test_plugin.py

@@ -160,6 +160,17 @@ class ViewTest(unittest.TestCase):
         self.assertNotIn("join_code", view)
         self.assertNotIn("game_type", view)
 
+    def test_view_for_spectator_hides_all_hands(self) -> None:
+        engine = ScoponeEngine()
+        session = _started(engine)
+        view = engine.view_for(session, None)
+        for player in view["players"]:
+            self.assertNotIn("hand", player)
+        self.assertNotIn("your_turn", view)
+        self.assertNotIn("legal_moves", view)
+        self.assertIn("table", view)
+        self.assertEqual({"A": 0, "B": 0}, view["scores"])
+
     def test_lobby_view(self) -> None:
         engine = ScoponeEngine()
         session = _session(engine, target_score=16)

server/requirements.txt

@@ -4,10 +4,11 @@
 #
 #    pip-compile --allow-unsafe --extra otel --extra-index-url=https://pypi.org/simple --index-url=https://gitea.woggioni.net/api/packages/woggioni/pypi/simple --output-file=../../requirements.txt pyproject.toml
 #
-# NOTE: the tavolo-platform, tavolo-scopone and tavolo-app sibling packages
+# NOTE: the tavolo-platform, tavolo-scopone, tavolo-briscola and tavolo-app
-# are NOT pinned here: they are installed from ./packages in the Dockerfile
+# sibling packages are NOT pinned here: they are installed from ./packages in
-# and in development (pip install -e ./packages/tavolo-platform
+# the Dockerfile and in development (pip install -e ./packages/tavolo-platform
-# -e ./packages/tavolo-scopone -e ./packages/tavolo-app). All of their
+# -e ./packages/tavolo-scopone -e ./packages/tavolo-briscola
+# -e ./packages/tavolo-app). All of their
 # third-party dependencies are direct dependencies of tavolo-app, so this
 # lock covers the full closure. The otel extra (kaya-otel and its
 # OpenTelemetry dependencies) IS included, so OTEL_ENABLED works in the
@@ -63,7 +64,7 @@ idna==3.20
     #   httpx
 iso8601==2.1.0
     # via tortoise-orm
-kaya-core==0.0.4
+kaya-core==0.0.7
     # via
     #   kaya-cors
     #   kaya-oidc
@@ -72,27 +73,31 @@ kaya-core==0.0.4
     #   kaya-rsgi
     #   kaya-session
     #   tavolo-app (pyproject.toml)
-kaya-cors==0.0.4
+kaya-cors==0.0.7
     # via tavolo-app (pyproject.toml)
-kaya-oidc==0.0.4
+kaya-oidc==0.0.7
     # via tavolo-app (pyproject.toml)
-kaya-openapi==0.0.4
+kaya-openapi==0.0.7
     # via tavolo-app (pyproject.toml)
-kaya-otel==0.0.4
+kaya-otel==0.0.7
     # via tavolo-app (pyproject.toml)
-kaya-rsgi==0.0.4
+kaya-rsgi==0.0.7
     # via tavolo-app (pyproject.toml)
-kaya-session==0.0.4
+kaya-session==0.0.7
     # via
     #   kaya-oidc
     #   kaya-session-redis
     #   tavolo-app (pyproject.toml)
-kaya-session-redis==0.0.4
+kaya-session-redis==0.0.7
     # via tavolo-app (pyproject.toml)
 opentelemetry-api==1.45.0
     # via
     #   opentelemetry-exporter-http-transport
     #   opentelemetry-exporter-otlp-proto-http
+    #   opentelemetry-instrumentation
+    #   opentelemetry-instrumentation-asyncpg
+    #   opentelemetry-instrumentation-redis
+    #   opentelemetry-instrumentation-system-metrics
     #   opentelemetry-sdk
     #   opentelemetry-semantic-conventions
 opentelemetry-exporter-http-transport[urllib3]==0.66b0
@@ -103,6 +108,17 @@ opentelemetry-exporter-otlp-proto-common==1.45.0
     # via opentelemetry-exporter-otlp-proto-http
 opentelemetry-exporter-otlp-proto-http==1.45.0
     # via kaya-otel
+opentelemetry-instrumentation==0.66b0
+    # via
+    #   opentelemetry-instrumentation-asyncpg
+    #   opentelemetry-instrumentation-redis
+    #   opentelemetry-instrumentation-system-metrics
+opentelemetry-instrumentation-asyncpg==0.66b0
+    # via tavolo-app (pyproject.toml)
+opentelemetry-instrumentation-redis==0.66b0
+    # via tavolo-app (pyproject.toml)
+opentelemetry-instrumentation-system-metrics==0.66b0
+    # via tavolo-app (pyproject.toml)
 opentelemetry-proto==1.45.0
     # via
     #   opentelemetry-exporter-otlp-proto-common
@@ -113,11 +129,20 @@ opentelemetry-sdk==1.45.0
     #   opentelemetry-exporter-otlp-common
     #   opentelemetry-exporter-otlp-proto-http
 opentelemetry-semantic-conventions==0.66b0
-    # via opentelemetry-sdk
+    # via
+    #   opentelemetry-instrumentation
+    #   opentelemetry-instrumentation-asyncpg
+    #   opentelemetry-instrumentation-redis
+    #   opentelemetry-instrumentation-system-metrics
+    #   opentelemetry-sdk
+packaging==26.3
+    # via opentelemetry-instrumentation
 protobuf==7.36.2
     # via
     #   googleapis-common-protos
     #   opentelemetry-proto
+psutil==7.2.2
+    # via opentelemetry-instrumentation-system-metrics
 pwo==0.1.2
     # via
     #   kaya-core
@@ -126,7 +151,7 @@ pwo==0.1.2
     #   tavolo-app (pyproject.toml)
 pycparser==3.0
     # via cffi
-pyjwt[crypto]==2.14.0
+pyjwt[crypto]==2.15.1
     # via
     #   kaya-oidc
     #   tavolo-app (pyproject.toml)
@@ -151,3 +176,7 @@ typing-extensions==4.16.0
     #   pwo
 urllib3==2.8.0
     # via opentelemetry-exporter-http-transport
+wrapt==2.5.0
+    # via
+    #   opentelemetry-instrumentation
+    #   opentelemetry-instrumentation-redis

server/tests/__init__.py

@@ -10,8 +10,9 @@ from __future__ import annotations
 import os
 
 os.environ.setdefault("DATABASE_URL", "sqlite://:memory:")
-os.environ.setdefault("OIDC_ISSUER", "http://localhost:8180/tavolo")
+os.environ.setdefault("OIDC_0_PROVIDER", "default")
-os.environ.setdefault("OIDC_CLIENT_ID", "tavolo")
+os.environ.setdefault("OIDC_0_ISSUER", "http://localhost:8180/tavolo")
-os.environ.setdefault("OIDC_REDIRECT_URI", "http://localhost:8080/auth/callback")
+os.environ.setdefault("OIDC_0_CLIENT_ID", "tavolo")
+os.environ.setdefault("OIDC_0_REDIRECT_URI", "http://localhost:8080/auth/default/callback")
 # Unset REDIS_URL: sessions and live games use the in-memory fallbacks.
 os.environ.pop("REDIS_URL", None)

server/tests/helpers/oidc.py

@@ -1,8 +1,9 @@
 """Helpers for faking the OIDC authenticated user during tests.
 
-HTTP handlers funnel through ``oidc_mixin.get_user``; websocket handlers
+HTTP handlers funnel through ``OIDCProviders.get_users`` (wrapped by
-through :func:`tavolo.platform.auth.get_ws_user`. Patching those two entry
+``tavolo.platform.auth.current_user``); websocket handlers through
-points lets route and websocket tests run entirely in-process with no IdP.
+:func:`tavolo.platform.auth.get_ws_user`. Patching those two entry points
+lets route and websocket tests run entirely in-process with no IdP.
 """
 from __future__ import annotations
 
@@ -14,9 +15,13 @@ from kaya.oidc import OIDCUser
 
 # Import the app first: it pulls in the route modules, which import
 # ``tavolo.platform.auth`` themselves.
-from tavolo.app import oidc_mixin
+from tavolo.app import oidc
 from tavolo.platform import auth
 
+# The app's first configured provider (the test environment configures one
+# named "default").
+_PROVIDER = next(iter(oidc.providers))
+
 
 def make_user(sub: str, name: Optional[str] = None) -> OIDCUser:
     return OIDCUser({"sub": sub, "preferred_username": name or sub})
@@ -24,9 +29,9 @@ def make_user(sub: str, name: Optional[str] = None) -> OIDCUser:
 
 @contextlib.contextmanager
 def oidc_user(sub: str, name: Optional[str] = None) -> Iterator[OIDCUser]:
-    """Context manager: patch ``oidc_mixin.get_user`` to return this user."""
+    """Context manager: make ``oidc.get_users`` return this user."""
     user = make_user(sub, name)
-    patcher = _mock.patch.object(oidc_mixin, "get_user", return_value=user)
+    patcher = _mock.patch.object(oidc, "get_users", return_value={_PROVIDER: user})
     patcher.start()
     try:
         yield user

server/tests/test_briscola.py

@@ -0,0 +1,368 @@
+"""Briscola integration tests: lobby, websocket play, timeouts and summaries.
+
+The per-package suites cover the rules and the engine contract; these
+tests wire both briscola variants through the full platform stack (REST,
+WebSocket, deadline scheduler).
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import unittest
+
+from httpx import ASGITransport, AsyncClient
+from httpx_ws import aconnect_ws
+from httpx_ws.transport import ASGIWebSocketTransport
+
+from tavolo.app import app, game_store, platform
+from tavolo.briscola.state import (
+    PHASE_HAND_END,
+    PHASE_PLAYING,
+    BriscolaState,
+    Card,
+    PlayerState,
+)
+from tavolo.platform import GameSession, Seat
+from tests.helpers import async_test, make_user, oidc_user, ws_users
+
+
+class BriscolaRoutesTest(unittest.TestCase):
+    @async_test
+    async def test_create_and_start_two_player_game(self) -> None:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            with oidc_user("alice"):
+                created = await client.post(
+                    "/api/games",
+                    json={"game_type": "briscola", "options": {"target_score": 101}},
+                )
+            self.assertEqual(201, created.status_code)
+            body = created.json()
+            self.assertEqual("briscola", body["game_type"])
+            self.assertEqual("lobby", body["phase"])
+            self.assertEqual(1, body["seats_open"])
+            self.assertEqual(101, body["target_score"])
+            self.assertEqual("A", body["players"][0]["team"])
+            code = body["join_code"]
+
+            with oidc_user("bob"):
+                started = await client.post("/api/games/join", json={"code": code})
+            self.assertEqual(200, started.status_code)
+            state = started.json()
+            self.assertEqual("playing", state["phase"])
+            self.assertEqual(2, len(state["players"]))
+            self.assertEqual(["A", "B"], [p["team"] for p in state["players"]])
+            for participant in state["players"]:
+                self.assertEqual(3, participant["cards_left"])
+            self.assertEqual(1, state["turn"])
+            self.assertEqual(33, state["stock_count"])
+            self.assertTrue(state["briscola_suit"])
+            self.assertIsNotNone(state["briscola_card"])
+            # Bob's view carries his own hand only.
+            self.assertIn("hand", state["players"][1])
+            self.assertNotIn("hand", state["players"][0])
+
+            # A non-player watches without a hand or the join code.
+            watched = await client.get(f"/api/games/{state['id']}")
+            self.assertEqual(200, watched.status_code)
+            spectator = watched.json()
+            self.assertTrue(spectator["spectator"])
+            self.assertNotIn("join_code", spectator)
+            for participant in spectator["players"]:
+                self.assertNotIn("hand", participant)
+
+    @async_test
+    async def test_create_and_start_four_player_game(self) -> None:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            with oidc_user("alice"):
+                created = await client.post(
+                    "/api/games", json={"game_type": "briscola_a_quattro"}
+                )
+            self.assertEqual(201, created.status_code)
+            body = created.json()
+            self.assertEqual("briscola_a_quattro", body["game_type"])
+            self.assertEqual(3, body["seats_open"])
+            code = body["join_code"]
+
+            for player in ("bob", "carol"):
+                with oidc_user(player):
+                    joined = await client.post("/api/games/join", json={"code": code})
+                self.assertEqual("lobby", joined.json()["phase"])
+
+            with oidc_user("dave"):
+                started = await client.post("/api/games/join", json={"code": code})
+            state = started.json()
+            self.assertEqual("playing", state["phase"])
+            self.assertEqual(["A", "B", "A", "B"], [p["team"] for p in state["players"]])
+            for participant in state["players"]:
+                self.assertEqual(3, participant["cards_left"])
+            self.assertEqual(40 - 12 - 1, state["stock_count"])
+
+    @async_test
+    async def test_preview_shows_briscola_options(self) -> None:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            with oidc_user("alice"):
+                created = await client.post(
+                    "/api/games",
+                    json={"game_type": "briscola", "options": {"target_score": 101}},
+                )
+            code = created.json()["join_code"]
+            with oidc_user("bob"):
+                preview = await client.get(f"/api/games/preview?code={code}")
+            self.assertEqual(200, preview.status_code)
+            body = preview.json()
+            self.assertEqual("briscola", body["game_type"])
+            self.assertEqual("Briscola", body["game_name"])
+            self.assertTrue(body["game_description"])
+            self.assertEqual(101, body["target_score"])
+            self.assertEqual(1, body["seats_open"])
+
+    @async_test
+    async def test_create_rejects_bad_target_score(self) -> None:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            for bad in (60, 121, "sixtyone", True):
+                with oidc_user("alice"):
+                    response = await client.post(
+                        "/api/games",
+                        json={"game_type": "briscola", "options": {"target_score": bad}},
+                    )
+                self.assertEqual(400, response.status_code, bad)
+
+
+class BriscolaWebSocketTest(unittest.TestCase):
+    async def _started_two_player(self, client: AsyncClient) -> dict:
+        with oidc_user("alice"):
+            created = await client.post("/api/games", json={"game_type": "briscola"})
+        code = created.json()["join_code"]
+        with oidc_user("bob"):
+            started = await client.post("/api/games/join", json={"code": code})
+        return started.json()
+
+    @async_test
+    async def test_moves_resolve_the_trick(self) -> None:
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_two_player(client)
+            game_id = state["id"]
+            bob_card = state["players"][1]["hand"][0]
+            with oidc_user("alice"):
+                alice_view = await client.get(f"/api/games/{game_id}")
+            alice_card = alice_view.json()["players"][0]["hand"][0]
+
+            ws_transport = ASGIWebSocketTransport(app=app)
+            async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+                with ws_users([make_user("bob"), make_user("alice")]):
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as bob_ws:
+                        first = await bob_ws.receive_json()
+                        self.assertEqual("state", first["type"])
+                        self.assertEqual(1, first["game"]["turn"])
+                        self.assertTrue(first["game"].get("your_turn"))
+
+                        async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as alice_ws:
+                            await alice_ws.receive_json()
+                            await bob_ws.send_json(
+                                {"action": "play", "card": bob_card}
+                            )
+                            bob_update = await bob_ws.receive_json()
+                            alice_update = await alice_ws.receive_json()
+                            for update in (bob_update, alice_update):
+                                self.assertEqual("state", update["type"])
+                                self.assertEqual(0, update["game"]["turn"])
+                                self.assertEqual(
+                                    [{"seat": 1, "card": bob_card}],
+                                    update["game"]["trick"],
+                                )
+
+                            await alice_ws.send_json(
+                                {"action": "play", "card": alice_card}
+                            )
+                            bob_update = await bob_ws.receive_json()
+                            alice_update = await alice_ws.receive_json()
+                            for update in (bob_update, alice_update):
+                                self.assertEqual([], update["game"]["trick"])
+                                last = update["game"]["last_trick"]
+                                self.assertIsNotNone(last)
+                                self.assertIn(last["winner"], (0, 1))
+                                self.assertEqual(2, len(last["cards"]))
+                                self.assertEqual(last["winner"], update["game"]["turn"])
+
+    @async_test
+    async def test_illegal_move_returns_error(self) -> None:
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_two_player(client)
+            game_id = state["id"]
+
+            ws_transport = ASGIWebSocketTransport(app=app)
+            async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+                with ws_users([make_user("alice")]):
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as alice_ws:
+                        await alice_ws.receive_json()
+                        # Bob (seat 1) is on turn, not Alice.
+                        await alice_ws.send_json({"action": "play", "card": "01D"})
+                        error = await alice_ws.receive_json()
+                        self.assertEqual("error", error["type"])
+
+    @async_test
+    async def test_spectator_cannot_act(self) -> None:
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_two_player(client)
+            game_id = state["id"]
+
+            ws_transport = ASGIWebSocketTransport(app=app)
+            async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+                with ws_users([make_user("mallory")]):
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
+                        first = await ws.receive_json()
+                        self.assertTrue(first["game"]["spectator"])
+                        self.assertNotIn("join_code", first["game"])
+                        for player in first["game"]["players"]:
+                            self.assertNotIn("hand", player)
+                        await ws.send_json({"action": "play", "card": "01D"})
+                        error = await ws.receive_json()
+                        self.assertEqual("forbidden", error["code"])
+
+
+class BriscolaTurnTimeoutTest(unittest.TestCase):
+    @async_test
+    async def test_turn_timeout_auto_plays_a_card(self) -> None:
+        engine = platform.registry.require("briscola")
+        session = GameSession(
+            id="briscola-turn-timeout-1",
+            game_type=engine.id,
+            join_code="BT0001",
+            creator_sub="alice",
+            players=[
+                Seat(user_sub="alice", display_name="Alice", team="A"),
+            ],
+        )
+        engine.create(session, {})
+        session.state.turn_timeout = 1
+        engine.join(session, "bob", "Bob")
+        await game_store.save(session)
+
+        ws_transport = ASGIWebSocketTransport(app=app)
+        async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+            with ws_users([make_user("alice")]):
+                async with aconnect_ws(f"/ws/games/{session.id}", ws_client) as ws:
+                    first = await ws.receive_json()
+                    # Bob (seat 1) is first to act and never connects.
+                    self.assertEqual(1, first["game"]["turn"])
+                    self.assertIsNotNone(first["game"]["turn_deadline"])
+
+                    update = None
+                    for _ in range(20):
+                        try:
+                            update = await asyncio.wait_for(ws.receive_json(), timeout=2)
+                        except asyncio.TimeoutError:
+                            break
+                        if (
+                            update.get("type") == "state"
+                            and update["game"]["last_trick"] is not None
+                        ):
+                            break
+                    self.assertIsNotNone(update)
+                    assert update is not None
+                    # Both absent players were auto-played; the trick
+                    # resolved and the winner leads with a full hand.
+                    self.assertIn(update["game"]["last_trick"]["winner"], (0, 1))
+                    self.assertEqual([], update["game"]["trick"])
+                    for participant in update["game"]["players"]:
+                        self.assertEqual(3, participant["cards_left"])
+
+
+async def _seed_hand_end_state() -> str:
+    """Seed a game where a single trick ends the deal with target 120 so
+    the match continues to the summary."""
+    engine = platform.registry.require("briscola")
+    session = GameSession(
+        id="briscola-hand-end-1",
+        game_type=engine.id,
+        join_code="BH0001",
+        creator_sub="alice",
+        players=[
+            Seat(user_sub="alice", display_name="Alice", team="A"),
+            Seat(user_sub="bob", display_name="Bob", team="B"),
+        ],
+    )
+    session.state = BriscolaState(
+        player_count=2,
+        target_score=120,
+        phase=PHASE_PLAYING,
+        dealer=0,
+        turn=0,
+        briscola_suit="S",
+        players=[
+            PlayerState(
+                sub="alice", name="Alice", seat=0,
+                hand=[Card.parse("02D")], captured=[Card.parse("01C")],
+            ),
+            PlayerState(
+                sub="bob", name="Bob", seat=1,
+                hand=[Card.parse("05D")], captured=[Card.parse("10C")],
+            ),
+        ],
+        hand_ack_timeout=30,
+    )
+    await game_store.save(session)
+    return session.id
+
+
+class BriscolaHandEndTest(unittest.TestCase):
+    @async_test
+    async def test_deal_end_ack_flow(self) -> None:
+        game_id = await _seed_hand_end_state()
+        ws_transport = ASGIWebSocketTransport(app=app)
+        async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
+            async with contextlib.AsyncExitStack() as stack:
+                with ws_users([make_user("alice"), make_user("bob")]):
+                    sockets = [
+                        await stack.enter_async_context(
+                            aconnect_ws(f"/ws/games/{game_id}", ws_client)
+                        )
+                        for _ in range(2)
+                    ]
+                    for ws in sockets:
+                        await ws.receive_json()  # initial state
+
+                    # Alice leads, Bob takes the trick: the deal ends.
+                    await sockets[0].send_json(
+                        {"action": "play", "card": "02D"}
+                    )
+                    for ws in sockets:
+                        await ws.receive_json()
+                    await sockets[1].send_json(
+                        {"action": "play", "card": "05D"}
+                    )
+                    summaries = [await ws.receive_json() for ws in sockets]
+                    for summary in summaries:
+                        self.assertEqual("state", summary["type"])
+                        self.assertEqual(PHASE_HAND_END, summary["game"]["phase"])
+                        self.assertEqual([], summary["game"]["acknowledged"])
+                        self.assertIsNotNone(summary["game"]["hand_end_deadline"])
+                        deal = summary["game"]["last_deal"]
+                        self.assertEqual({"A": 11, "B": 4}, deal["points"])
+                        self.assertEqual({"A": 11, "B": 4}, deal["totals"])
+                        self.assertFalse(deal["patta"])
+
+                    # Both acknowledge; the second ack deals the next deal.
+                    await sockets[0].send_json({"action": "ack"})
+                    updates = [await ws.receive_json() for ws in sockets]
+                    for update in updates:
+                        self.assertEqual(PHASE_HAND_END, update["game"]["phase"])
+                        self.assertEqual([0], update["game"]["acknowledged"])
+                    await sockets[1].send_json({"action": "ack"})
+                    updates = [await ws.receive_json() for ws in sockets]
+                    for update in updates:
+                        self.assertEqual(PHASE_PLAYING, update["game"]["phase"])
+                        self.assertEqual(2, update["game"]["hand_number"])
+                        for player in update["game"]["players"]:
+                            self.assertEqual(3, player["cards_left"])
+
+
+if __name__ == "__main__":
+    unittest.main()

server/tests/test_config.py

@@ -164,6 +164,154 @@ class OTelSettingsTests(unittest.TestCase):
         settings = _settings({"OTEL_EXCLUDED_PATHS": "/api/health, /metrics"})
         self.assertEqual(("/api/health", "/metrics"), settings.otel_excluded_paths)
 
+    def test_otel_interval_defaults(self):
+        settings = _settings({})
+        self.assertEqual(60000, settings.otel_metric_export_interval_millis)
+        self.assertEqual(15, settings.otel_metrics_poll_interval_seconds)
+
+    def test_otel_intervals_parse(self):
+        settings = _settings({
+            "OTEL_METRIC_EXPORT_INTERVAL_MILLIS": "5000",
+            "OTEL_METRICS_POLL_INTERVAL_SECONDS": "3",
+        })
+        self.assertEqual(5000, settings.otel_metric_export_interval_millis)
+        self.assertEqual(3, settings.otel_metrics_poll_interval_seconds)
+
+
+class OidcSettingsTests(unittest.TestCase):
+    def test_defaults_to_the_dev_mock_provider(self):
+        settings = _settings({})
+        self.assertEqual(1, len(settings.oidc_providers))
+        provider = settings.oidc_providers[0]
+        self.assertEqual("default", provider.provider)
+        self.assertEqual("http://localhost:8180/tavolo", provider.issuer)
+        self.assertEqual("tavolo", provider.client_id)
+        self.assertIsNone(provider.client_secret)
+        self.assertEqual(
+            "http://localhost:8080/auth/default/callback", provider.redirect_uri
+        )
+        self.assertEqual("/", provider.post_login_redirect)
+        self.assertEqual("/", provider.post_logout_redirect)
+
+    def test_single_indexed_provider_defaults(self):
+        settings = _settings({
+            "OIDC_0_PROVIDER": "google",
+            "OIDC_0_ISSUER": "https://accounts.google.com",
+            "OIDC_0_CLIENT_ID": "client-id",
+            "OIDC_0_CLIENT_SECRET": "client-secret",
+        })
+        self.assertEqual(1, len(settings.oidc_providers))
+        provider = settings.oidc_providers[0]
+        self.assertEqual("google", provider.provider)
+        self.assertEqual("https://accounts.google.com", provider.issuer)
+        self.assertEqual("client-id", provider.client_id)
+        self.assertEqual("client-secret", provider.client_secret)
+        # The callback default mirrors kaya's /auth/<provider>/callback.
+        self.assertEqual(
+            "http://localhost:8080/auth/google/callback", provider.redirect_uri
+        )
+        self.assertEqual("/", provider.post_login_redirect)
+        self.assertEqual("/", provider.post_logout_redirect)
+
+    def test_multiple_providers_are_ordered_by_index(self):
+        settings = _settings({
+            "OIDC_0_PROVIDER": "google",
+            "OIDC_0_ISSUER": "https://accounts.google.com",
+            "OIDC_0_CLIENT_ID": "g",
+            "OIDC_1_PROVIDER": "github",
+            "OIDC_1_ISSUER": "https://github.com/login/oauth",
+            "OIDC_1_CLIENT_ID": "h",
+            "OIDC_1_REDIRECT_URI": "https://tavolo.example/auth/github/callback",
+            "OIDC_1_POST_LOGIN_REDIRECT": "/lobby",
+            "OIDC_1_POST_LOGOUT_REDIRECT": "/bye",
+        })
+        self.assertEqual(
+            ["google", "github"], [p.provider for p in settings.oidc_providers]
+        )
+        github = settings.oidc_providers[1]
+        self.assertEqual(
+            "https://tavolo.example/auth/github/callback", github.redirect_uri
+        )
+        self.assertEqual("/lobby", github.post_login_redirect)
+        self.assertEqual("/bye", github.post_logout_redirect)
+
+    def test_empty_optional_values_fall_back_to_defaults(self):
+        settings = _settings({
+            "OIDC_0_PROVIDER": "google",
+            "OIDC_0_ISSUER": "https://accounts.google.com",
+            "OIDC_0_CLIENT_ID": "g",
+            "OIDC_0_CLIENT_SECRET": "",
+            "OIDC_0_REDIRECT_URI": "",
+        })
+        provider = settings.oidc_providers[0]
+        self.assertIsNone(provider.client_secret)
+        self.assertEqual(
+            "http://localhost:8080/auth/google/callback", provider.redirect_uri
+        )
+
+    def test_missing_provider_name(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_0_PROVIDER"):
+            _settings({"OIDC_0_ISSUER": "https://idp", "OIDC_0_CLIENT_ID": "c"})
+
+    def test_missing_issuer(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_0_ISSUER"):
+            _settings({"OIDC_0_PROVIDER": "google", "OIDC_0_CLIENT_ID": "c"})
+
+    def test_missing_client_id(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_0_CLIENT_ID"):
+            _settings({"OIDC_0_PROVIDER": "google", "OIDC_0_ISSUER": "https://idp"})
+
+    def test_indices_must_start_at_zero(self):
+        with self.assertRaisesRegex(RuntimeError, "contiguous"):
+            _settings({
+                "OIDC_3_PROVIDER": "google",
+                "OIDC_3_ISSUER": "https://idp",
+                "OIDC_3_CLIENT_ID": "c",
+            })
+
+    def test_indices_must_be_contiguous(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_1_"):
+            _settings({
+                "OIDC_0_PROVIDER": "google",
+                "OIDC_0_ISSUER": "https://idp",
+                "OIDC_0_CLIENT_ID": "c",
+                "OIDC_2_PROVIDER": "github",
+                "OIDC_2_ISSUER": "https://idp2",
+                "OIDC_2_CLIENT_ID": "c2",
+            })
+
+    def test_duplicate_provider_names_are_rejected(self):
+        with self.assertRaisesRegex(RuntimeError, "duplicate"):
+            _settings({
+                "OIDC_0_PROVIDER": "google",
+                "OIDC_0_ISSUER": "https://idp",
+                "OIDC_0_CLIENT_ID": "c",
+                "OIDC_1_PROVIDER": "google",
+                "OIDC_1_ISSUER": "https://idp2",
+                "OIDC_1_CLIENT_ID": "c2",
+            })
+
+    def test_invalid_provider_name_is_rejected(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_0_PROVIDER"):
+            _settings({
+                "OIDC_0_PROVIDER": "not a name",
+                "OIDC_0_ISSUER": "https://idp",
+                "OIDC_0_CLIENT_ID": "c",
+            })
+
+    def test_unknown_indexed_variable_is_rejected(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_0_ISUER"):
+            _settings({
+                "OIDC_0_PROVIDER": "google",
+                "OIDC_0_ISSUER": "https://idp",
+                "OIDC_0_CLIENT_ID": "c",
+                "OIDC_0_ISUER": "typo",
+            })
+
+    def test_legacy_unindexed_variables_get_a_migration_hint(self):
+        with self.assertRaisesRegex(RuntimeError, "OIDC_ISSUER -> OIDC_0_ISSUER"):
+            _settings({"OIDC_ISSUER": "https://idp", "OIDC_CLIENT_ID": "c"})
+
 
 if __name__ == "__main__":
     unittest.main()

server/tests/test_logging_config.py

@@ -18,12 +18,15 @@ class LoggingConfigTest(unittest.TestCase):
         self._root_level = root.level
         tavolo = logging.getLogger("tavolo")
         self._tavolo_level = tavolo.level
+        pool = logging.getLogger("urllib3.connectionpool")
+        self._pool_level = pool.level
 
     def tearDown(self) -> None:
         root = logging.getLogger()
         root.handlers = self._root_handlers
         root.level = self._root_level
         logging.getLogger("tavolo").level = self._tavolo_level
+        logging.getLogger("urllib3.connectionpool").level = self._pool_level
 
     def test_default_config_when_unset(self) -> None:
         configure_logging(None)
@@ -33,6 +36,12 @@ class LoggingConfigTest(unittest.TestCase):
             any(isinstance(h, logging.StreamHandler) for h in root.handlers),
             "default config installs a console stream handler",
         )
+        # The noisy per-request HTTP logger is capped at INFO while the
+        # root stays at DEBUG.
+        self.assertEqual(
+            logging.INFO,
+            logging.getLogger("urllib3.connectionpool").getEffectiveLevel(),
+        )
 
     def test_yaml_config_is_applied(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:

server/tests/test_otel.py

@@ -16,6 +16,7 @@ from unittest.mock import patch
 
 from tavolo.app import otel_mixin_from_settings
 from tavolo.config import Settings
+from tavolo.telemetry import session_tag_hook
 
 
 def _settings(env: dict) -> Settings:
@@ -58,8 +59,17 @@ class OTelMixinFromSettingsTests(unittest.TestCase):
             "endpoint": "http://collector:4318",
             "headers": {"Authorization": "Bearer t", "X-Tenant": "one"},
             "excluded_paths": ("/api/health",),
+            "server_response_hook": session_tag_hook,
+            "websocket_close_hook": session_tag_hook,
         }, mixin.kwargs)
 
+    def test_session_tag_hooks_are_wired(self):
+        with _stub_kaya_otel():
+            mixin = otel_mixin_from_settings(_settings({"OTEL_ENABLED": "1"}))
+        assert isinstance(mixin, _StubOTelMixin)
+        self.assertIs(session_tag_hook, mixin.kwargs["server_response_hook"])
+        self.assertIs(session_tag_hook, mixin.kwargs["websocket_close_hook"])
+
     def test_defaults_when_only_enabled(self):
         with _stub_kaya_otel():
             mixin = otel_mixin_from_settings(_settings({"OTEL_ENABLED": "on"}))
@@ -69,6 +79,24 @@ class OTelMixinFromSettingsTests(unittest.TestCase):
         self.assertIsNone(mixin.kwargs["headers"])
         self.assertEqual(("/api/health",), mixin.kwargs["excluded_paths"])
 
+    def test_meter_provider_is_passed_through(self):
+        with _stub_kaya_otel():
+            provider = object()
+            mixin = otel_mixin_from_settings(
+                _settings({"OTEL_ENABLED": "1"}), meter_provider=provider
+            )
+        assert isinstance(mixin, _StubOTelMixin)
+        self.assertIs(provider, mixin.kwargs["meter_provider"])
+
+    def test_tracer_provider_is_passed_through(self):
+        with _stub_kaya_otel():
+            provider = object()
+            mixin = otel_mixin_from_settings(
+                _settings({"OTEL_ENABLED": "1"}), tracer_provider=provider
+            )
+        assert isinstance(mixin, _StubOTelMixin)
+        self.assertIs(provider, mixin.kwargs["tracer_provider"])
+
     def test_excluded_paths_are_passed_through(self):
         with _stub_kaya_otel():
             mixin = otel_mixin_from_settings(_settings({

server/tests/test_routes_auth.py

@@ -0,0 +1,35 @@
+"""Auth routes on the fully wired application.
+
+The integration suite's app is built from the indexed test environment
+(one provider named ``default``); these tests pin the public surface the
+SPA and bookmarks rely on.
+"""
+from __future__ import annotations
+
+import unittest
+
+from httpx import ASGITransport, AsyncClient
+
+from tavolo.app import app
+from tests.helpers import async_test
+
+
+class AuthRoutesTest(unittest.TestCase):
+    @async_test
+    async def test_providers_endpoint_reports_the_configured_provider(self) -> None:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            response = await client.get("/api/auth/providers")
+        self.assertEqual(200, response.status_code)
+        self.assertEqual(
+            {"providers": [{"name": "default", "login_url": "/auth/default/login"}]},
+            response.json(),
+        )
+
+    @async_test
+    async def test_generic_login_redirects_to_the_provider(self) -> None:
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            response = await client.get("/auth/login", follow_redirects=False)
+        self.assertEqual(302, response.status_code)
+        self.assertEqual("/auth/default/login", response.headers["location"])

server/tests/test_routes_games.py

@@ -1,4 +1,4 @@
-"""Game lobby route tests via kaya's ASGI transport (scopone game)."""
+"""Game lobby route tests via kaya's ASGI transport (all registered games)."""
 from __future__ import annotations
 
 import unittest
@@ -39,9 +39,19 @@ class GamesRouteTest(unittest.TestCase):
             self.assertEqual(200, snapshot.status_code)
             self.assertEqual("alice", snapshot.json()["players"][0]["sub"])
 
+            # A logged-in non-player is a read-only spectator: no join
+            # code, and the view is marked as a spectator view.
             with oidc_user("mallory"):
-                forbidden = await client.get(f"/api/games/{game_id}")
+                watched = await client.get(f"/api/games/{game_id}")
-            self.assertEqual(403, forbidden.status_code)
+            self.assertEqual(200, watched.status_code)
+            self.assertTrue(watched.json()["spectator"])
+            self.assertNotIn("join_code", watched.json())
+
+            # Anonymous users may watch too.
+            anonymous = await client.get(f"/api/games/{game_id}")
+            self.assertEqual(200, anonymous.status_code)
+            self.assertTrue(anonymous.json()["spectator"])
+            self.assertNotIn("join_code", anonymous.json())
 
     @async_test
     async def test_join_fills_seats_and_starts_game(self) -> None:
@@ -61,6 +71,7 @@ class GamesRouteTest(unittest.TestCase):
                 started = await client.post("/api/games/join", json={"code": code})
             self.assertEqual(200, started.status_code)
             state = started.json()
+            game_id = state["id"]
             self.assertEqual("playing", state["phase"])
             self.assertEqual(4, len(state["players"]))
             self.assertEqual([], state["table"])
@@ -72,6 +83,21 @@ class GamesRouteTest(unittest.TestCase):
             self.assertNotIn("hand", state["players"][0])
             self.assertEqual(1, state["turn"])
 
+            # A spectator sees the table, the score and each player's
+            # captured count and scope — but no hand at all.
+            watched = await client.get(f"/api/games/{game_id}")
+            self.assertEqual(200, watched.status_code)
+            spect = watched.json()
+            self.assertTrue(spect["spectator"])
+            self.assertNotIn("join_code", spect)
+            self.assertEqual([], spect["table"])
+            self.assertEqual({"A": 0, "B": 0}, spect["scores"])
+            for participant in spect["players"]:
+                self.assertNotIn("hand", participant)
+                self.assertEqual(10, participant["cards_left"])
+                self.assertEqual(0, participant["captured_count"])
+                self.assertEqual(0, participant["scope"])
+
     @async_test
     async def test_create_napola_option(self) -> None:
         transport = ASGITransport(app=app)
@@ -227,16 +253,32 @@ class GameTypesRouteTest(unittest.TestCase):
             response = await client.get("/api/game-types")
         self.assertEqual(200, response.status_code)
         results = response.json()["results"]
-        self.assertEqual(["scopone_scientifico"], [g["id"] for g in results])
+        self.assertEqual(
-        self.assertEqual("Scopone scientifico", results[0]["name"])
+            ["scopone_scientifico", "briscola", "briscola_a_quattro"],
-        self.assertTrue(results[0]["description"])
+            [g["id"] for g in results],
-        self.assertEqual(4, results[0]["min_players"])
-        self.assertEqual(4, results[0]["max_players"])
-        self.assertIn("target_score", results[0]["options_schema"]["properties"])
-        self.assertIn("napola", results[0]["options_schema"]["properties"])
-        self.assertIn(
-            "asso_pigliatutto", results[0]["options_schema"]["properties"]
         )
+        scopone = results[0]
+        self.assertEqual("Scopone scientifico", scopone["name"])
+        self.assertTrue(scopone["description"])
+        self.assertEqual(4, scopone["min_players"])
+        self.assertEqual(4, scopone["max_players"])
+        self.assertIn("target_score", scopone["options_schema"]["properties"])
+        self.assertIn("napola", scopone["options_schema"]["properties"])
+        self.assertIn(
+            "asso_pigliatutto", scopone["options_schema"]["properties"]
+        )
+        briscola = results[1]
+        self.assertEqual("Briscola", briscola["name"])
+        self.assertTrue(briscola["description"])
+        self.assertEqual(2, briscola["min_players"])
+        self.assertEqual(2, briscola["max_players"])
+        self.assertIn("target_score", briscola["options_schema"]["properties"])
+        quattro = results[2]
+        self.assertEqual("Briscola a quattro", quattro["name"])
+        self.assertTrue(quattro["description"])
+        self.assertEqual(4, quattro["min_players"])
+        self.assertEqual(4, quattro["max_players"])
+        self.assertIn("target_score", quattro["options_schema"]["properties"])
 
     @async_test
     async def test_create_defaults_game_type(self) -> None:
@@ -268,7 +310,7 @@ class GameTypesRouteTest(unittest.TestCase):
         transport = ASGITransport(app=app)
         async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
             with oidc_user("alice"):
-                unknown = await client.post("/api/games", json={"game_type": "briscola"})
+                unknown = await client.post("/api/games", json={"game_type": "tresette"})
                 non_string = await client.post("/api/games", json={"game_type": 42})
             self.assertEqual(400, unknown.status_code)
             self.assertEqual(400, non_string.status_code)

server/tests/test_stats.py

@@ -136,5 +136,91 @@ class ScoponeStatsTest(unittest.TestCase):
             self.assertTrue(all(r["matches"] == 1 for r in by_sub.values()))
 
 
+async def _finished_briscola_session() -> GameSession:
+    engine = platform.registry.require("briscola")
+    session = GameSession(
+        id="stats-briscola-1",
+        game_type=engine.id,
+        join_code="BS0001",
+        creator_sub="alice",
+        players=[Seat(user_sub="alice", display_name="Alice")],
+    )
+    engine.create(session, {})
+    engine.join(session, "bob", "Bob")
+    moves = 0
+    while not engine.is_finished(session) and moves < 200000:
+        state = session.state
+        if state.phase == "hand_end":
+            for player in state.players:
+                engine.handle_action(session, player.sub, "ack", {})
+            continue
+        player = next(p for p in state.players if p.seat == state.turn)
+        engine.handle_action(
+            session, player.sub, "play", {"card": player.hand[0].code}
+        )
+        moves += 1
+    assert engine.is_finished(session)
+    return session
+
+
+class BriscolaStatsTest(unittest.TestCase):
+    @async_test
+    async def test_finished_briscola_match_persisted_with_summary(self) -> None:
+        await tortoise_mixin._bind()
+        ctx = tortoise_mixin._ctx
+        assert ctx is not None
+        engine = platform.registry.require("briscola")
+        session = await _finished_briscola_session()
+        with ctx:
+            await save_match_result(session, engine)
+            self.assertEqual(1, await Match.all().count())
+            self.assertEqual(2, await MatchPlayer.all().count())
+
+            match = await Match.all().first()
+            assert match is not None
+            self.assertEqual("briscola", match.game_type)
+            summary = match.result
+            self.assertIn("team_a_score", summary)
+            self.assertIn("team_b_score", summary)
+            self.assertIn("winner_team", summary)
+            self.assertIn("target_score", summary)
+            self.assertIn("deals_played", summary)
+            self.assertIn("deal_scores", summary)
+
+            winner_team = summary["winner_team"]
+            players = {p.user_sub: p for p in await MatchPlayer.all()}
+            for row in players.values():
+                if row.won:
+                    self.assertEqual(winner_team, row.team)
+                else:
+                    self.assertNotEqual(winner_team, row.team)
+            # A two-player match moves Elo by 16 points each.
+            ratings = {r.user_sub: r.rating for r in await PlayerRating.all()}
+            self.assertEqual(2, len(ratings))
+            self.assertEqual(
+                {INITIAL_RATING + 16, INITIAL_RATING - 16}, set(ratings.values())
+            )
+
+    @async_test
+    async def test_history_exposes_briscola_result(self) -> None:
+        await tortoise_mixin._bind()
+        ctx = tortoise_mixin._ctx
+        assert ctx is not None
+        engine = platform.registry.require("briscola")
+        session = await _finished_briscola_session()
+        with ctx:
+            await save_match_result(session, engine)
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://127.0.0.1") as client:
+            with oidc_user("alice"):
+                history = await client.get("/api/me/matches")
+            self.assertEqual(200, history.status_code)
+            results = history.json()["results"]
+            self.assertEqual(1, len(results))
+            self.assertEqual("briscola", results[0]["game_type"])
+            self.assertIn("team_a_score", results[0]["result"])
+            self.assertEqual(2, len(results[0]["players"]))
+
+
 if __name__ == "__main__":
     unittest.main()

server/tests/test_telemetry.py

@@ -0,0 +1,427 @@
+"""Telemetry unit tests: app gauges, process metrics, log export and counts.
+
+The OpenTelemetry packages are an optional extra (``tavolo-app[otel]``),
+so the provider-dependent tests skip when they are not installed.
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import sys
+import unittest
+from types import SimpleNamespace
+from typing import Optional
+from unittest.mock import patch
+
+from kaya.session import Session
+from tavolo.telemetry import (
+    CountingInMemorySessionStore,
+    CountingRedisSessionStore,
+    TelemetryMixin,
+    _NoOtelLogs,
+    session_tag_hook,
+    telemetry_from_settings,
+)
+from tavolo.config import Settings
+
+from tests.helpers import async_test
+
+try:
+    from opentelemetry.sdk._logs import LoggingHandler, LoggerProvider
+    from opentelemetry.sdk._logs.export import (
+        InMemoryLogRecordExporter,
+        SimpleLogRecordProcessor,
+    )
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics.export import InMemoryMetricReader
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+    from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+        InMemorySpanExporter,
+    )
+
+    HAVE_OTEL = True
+except ImportError:  # pragma: no cover - installs without the otel extra
+    HAVE_OTEL = False
+
+
+def _settings(env: dict) -> Settings:
+    with patch.dict(os.environ, env, clear=True):
+        return Settings.from_env()
+
+
+class _FakeSessions:
+    def __init__(self, count: int = 0) -> None:
+        self.value: Optional[int] = count
+        self.error: Optional[Exception] = None
+
+    async def count(self) -> int:
+        if self.error is not None:
+            raise self.error
+        assert self.value is not None
+        return self.value
+
+
+class _FakeGames:
+    def __init__(self, count: int = 0) -> None:
+        self.value: Optional[int] = count
+
+    async def count_ongoing(self) -> int:
+        assert self.value is not None
+        return self.value
+
+
+class _FakeRedis:
+    """Minimal async Redis double covering the session-count scan."""
+
+    def __init__(self, keys: list) -> None:
+        self.keys = keys
+
+    async def scan_iter(self, match: str = "", count: int = 0):
+        prefix = match.rstrip("*")
+        for key in self.keys:
+            if key.startswith(prefix):
+                yield key
+
+
+class TelemetrySetupTest(unittest.TestCase):
+    def test_disabled_returns_none(self) -> None:
+        self.assertIsNone(
+            telemetry_from_settings(
+                _settings({}), _FakeSessions(), _FakeGames()
+            )
+        )
+
+    def test_missing_otel_dependencies_raise(self) -> None:
+        settings = _settings({"OTEL_ENABLED": "true"})
+        missing = "opentelemetry.exporter.otlp.proto.http._log_exporter"
+        with patch.dict(sys.modules, {missing: None}):
+            with self.assertRaises(RuntimeError):
+                telemetry_from_settings(settings, _FakeSessions(), _FakeGames())
+
+
+class SessionCountTest(unittest.TestCase):
+    @async_test
+    async def test_in_memory_counts_live_sessions(self) -> None:
+        now = [1000.0]
+        store = CountingInMemorySessionStore(clock=lambda: now[0])
+        await store.save("a", Session("a", {"user": "alice"}), max_age=10)
+        await store.save("b", Session("b", {"user": "bob"}), max_age=10)
+        await store.save("c", Session("c", {"user": "carol"}))  # no expiry
+        self.assertEqual(3, await store.count())
+
+        now[0] += 11  # a and b have expired
+        self.assertEqual(1, await store.count())
+        await store.delete("c")
+        self.assertEqual(0, await store.count())
+
+    @async_test
+    async def test_redis_counts_only_session_keys(self) -> None:
+        store = CountingRedisSessionStore(
+            _FakeRedis(["kaya:session:a", "kaya:session:b", "tavolo:code:X"])
+        )
+        self.assertEqual(2, await store.count())
+
+
+class NoOtelLogsFilterTest(unittest.TestCase):
+    def test_filters_opentelemetry_records_only(self) -> None:
+        filter_ = _NoOtelLogs()
+        self.assertFalse(
+            filter_.filter(logging.makeLogRecord({"name": "opentelemetry.sdk"}))
+        )
+        self.assertTrue(
+            filter_.filter(logging.makeLogRecord({"name": "tavolo.app"}))
+        )
+        self.assertTrue(
+            filter_.filter(logging.makeLogRecord({"name": "granian.server"}))
+        )
+
+
+class _RecordedSpan:
+    def __init__(self) -> None:
+        self.attributes: dict = {}
+
+    def set_attribute(self, key: str, value) -> None:
+        self.attributes[key] = value
+
+
+class SessionTagHookTest(unittest.TestCase):
+    def test_tags_authenticated_session(self) -> None:
+        span = _RecordedSpan()
+        carrier = SimpleNamespace(
+            session=Session("sid", {"oidc:default:user": {"sub": "alice"}})
+        )
+        session_tag_hook(span, carrier)
+        self.assertEqual(
+            hashlib.sha256(b"sid").hexdigest()[:16],
+            span.attributes["session.id"],
+        )
+        self.assertEqual("alice", span.attributes["user.id"])
+
+    def test_tags_user_of_any_provider(self) -> None:
+        span = _RecordedSpan()
+        carrier = SimpleNamespace(
+            session=Session("sid", {"oidc:google:user": {"sub": "alice"}})
+        )
+        session_tag_hook(span, carrier)
+        self.assertEqual("alice", span.attributes["user.id"])
+
+    def test_ignores_legacy_unprefixed_user_key(self) -> None:
+        span = _RecordedSpan()
+        carrier = SimpleNamespace(
+            session=Session("sid", {"oidc_user": {"sub": "alice"}})
+        )
+        session_tag_hook(span, carrier)
+        self.assertIn("session.id", span.attributes)
+        self.assertNotIn("user.id", span.attributes)
+
+    def test_tags_session_without_user(self) -> None:
+        span = _RecordedSpan()
+        session_tag_hook(span, SimpleNamespace(session=Session("sid", {})))
+        self.assertIn("session.id", span.attributes)
+        self.assertNotIn("user.id", span.attributes)
+
+    def test_tags_user_when_session_id_not_yet_minted(self) -> None:
+        span = _RecordedSpan()
+        carrier = SimpleNamespace(
+            session=Session(None, {"oidc:default:user": {"sub": "alice"}})
+        )
+        session_tag_hook(span, carrier)
+        self.assertNotIn("session.id", span.attributes)
+        self.assertEqual("alice", span.attributes["user.id"])
+
+    def test_missing_session_is_a_noop(self) -> None:
+        span = _RecordedSpan()
+        session_tag_hook(span, SimpleNamespace())
+        self.assertEqual({}, span.attributes)
+
+    def test_malformed_user_is_ignored(self) -> None:
+        span = _RecordedSpan()
+        carrier = SimpleNamespace(session=Session("sid", {"oidc:default:user": "alice"}))
+        session_tag_hook(span, carrier)
+        self.assertIn("session.id", span.attributes)
+        self.assertNotIn("user.id", span.attributes)
+
+
+@unittest.skipUnless(HAVE_OTEL, "tavolo-app[otel] not installed")
+class SessionTagIntegrationTest(unittest.TestCase):
+    """The hook is wired as kaya-otel's response hook, so it sees the
+    session after the session mixin persisted and minted it."""
+
+    @async_test
+    async def test_spans_carry_hashed_session_and_oidc_sub(self) -> None:
+        from httpx import ASGITransport, AsyncClient
+        from kaya.core import HttpContext, KayaApp
+        from kaya.otel import OTelMixin
+        from kaya.session import InMemorySessionStore, SessionMixin
+
+        span_exporter = InMemorySpanExporter()
+        tracer_provider = TracerProvider(
+            resource=Resource.create({"service.name": "test"})
+        )
+        tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
+        app = KayaApp(
+            mixins=[
+                OTelMixin(
+                    service_name="test",
+                    tracer_provider=tracer_provider,
+                    meter_provider=MeterProvider(
+                        metric_readers=[InMemoryMetricReader()]
+                    ),
+                    server_response_hook=session_tag_hook,
+                    websocket_close_hook=session_tag_hook,
+                ),
+                SessionMixin(InMemorySessionStore()),
+            ]
+        )
+
+        @app.GET("/login")
+        async def login(ctx: HttpContext) -> None:
+            session = ctx.session
+            assert session is not None
+            session["oidc:default:user"] = {"sub": "alice"}
+            await ctx.send_str(200, "ok")
+
+        @app.GET("/me")
+        async def me(ctx: HttpContext) -> None:
+            await ctx.send_str(200, "ok")
+
+        transport = ASGITransport(app=app)  # type: ignore[arg-type]
+        async with AsyncClient(
+            transport=transport, base_url="http://127.0.0.1"
+        ) as client:
+            first = await client.get("/login")
+            second = await client.get("/me")
+            self.assertEqual(200, first.status_code)
+            self.assertEqual(200, second.status_code)
+        # The cookie value is the session id; only its digest is exported.
+        cookie = first.cookies["session_id"]
+        digest = hashlib.sha256(cookie.encode()).hexdigest()[:16]
+
+        spans = {span.name: span for span in span_exporter.get_finished_spans()}
+        self.assertEqual({"GET /login", "GET /me"}, set(spans))
+        for name, span in spans.items():
+            attributes = span.attributes
+            assert attributes is not None
+            self.assertEqual(digest, attributes["session.id"], name)
+            self.assertEqual("alice", attributes["user.id"], name)
+
+
+def _metric_points(reader) -> dict:
+    """Map metric name -> list of (attributes, value) data points."""
+    data = reader.get_metrics_data()
+    assert data is not None
+    points = {}
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                points[metric.name] = [
+                    (dict(point.attributes), point.value)
+                    for point in metric.data.data_points
+                ]
+    return points
+
+
+@unittest.skipUnless(HAVE_OTEL, "tavolo-app[otel] not installed")
+class MetricExportTest(unittest.TestCase):
+    # The instrumentation packages are process-wide singletons whose
+    # callbacks cannot be re-registered, so the providers and mixin are
+    # built once for the whole class (as the application does).
+    sessions = _FakeSessions(0)
+    games = _FakeGames(0)
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        resource = Resource.create({"service.name": "test"})
+        cls.reader = InMemoryMetricReader()
+        cls.provider = MeterProvider(resource=resource, metric_readers=[cls.reader])
+        cls.span_exporter = InMemorySpanExporter()
+        cls.tracer_provider = TracerProvider(resource=resource)
+        cls.tracer_provider.add_span_processor(
+            SimpleSpanProcessor(cls.span_exporter)
+        )
+        cls.mixin = TelemetryMixin(
+            meter_provider=cls.provider,
+            tracer_provider=cls.tracer_provider,
+            logger_provider=None,
+            log_handler=None,
+            session_store=cls.sessions,
+            game_store=cls.games,
+            poll_interval_seconds=1,
+        )
+        cls.mixin.apply(None)  # type: ignore[arg-type]
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.mixin.shutdown(None)  # type: ignore[arg-type]
+
+    @async_test
+    async def test_app_gauges_report_polled_counts(self) -> None:
+        self.sessions.value = 3
+        self.sessions.error = None
+        self.games.value = 2
+        await self.mixin.refresh_counts()
+        points = _metric_points(self.reader)
+        self.assertEqual([({}, 3)], points["tavolo.active_users"])
+        self.assertEqual([({}, 2)], points["tavolo.ongoing_games"])
+
+    @async_test
+    async def test_failed_refresh_keeps_last_value(self) -> None:
+        self.sessions.value = 5
+        self.sessions.error = None
+        await self.mixin.refresh_counts()
+        self.sessions.error = RuntimeError("redis down")
+        await self.mixin.refresh_counts()
+        points = _metric_points(self.reader)
+        self.assertEqual([({}, 5)], points["tavolo.active_users"])
+
+    @async_test
+    async def test_process_and_gc_metrics_are_exported(self) -> None:
+        await self.mixin.refresh_counts()
+        points = _metric_points(self.reader)
+        for name in (
+            "process.cpu.time",
+            "process.cpu.utilization",
+            "process.memory.usage",
+            "process.memory.virtual",
+            "cpython.gc.collections",
+            "cpython.gc.collected_objects",
+            "cpython.gc.uncollectable_objects",
+        ):
+            self.assertIn(name, points)
+        self.assertGreater(points["process.memory.usage"][0][1], 0)
+        modes = {attrs["type"] for attrs, _ in points["process.cpu.time"]}
+        self.assertEqual({"user", "system"}, modes)
+        generations = {
+            attrs["cpython.gc.generation"]
+            for attrs, _ in points["cpython.gc.collections"]
+        }
+        self.assertEqual({0, 1, 2}, generations)
+        # Host-level metrics are deliberately not configured.
+        self.assertNotIn("system.cpu.time", points)
+
+    @async_test
+    async def test_database_clients_are_instrumented(self) -> None:
+        import asyncpg.connection
+        import redis.asyncio
+
+        self.assertTrue(hasattr(redis.asyncio.Redis.execute_command, "__wrapped__"))
+        self.assertTrue(hasattr(asyncpg.connection.Connection.fetch, "__wrapped__"))
+
+        # Exercise each wrapper through stubs: the downstream call fails (no
+        # server), but the span is recorded before it does.
+        client = object.__new__(redis.asyncio.Redis)
+        client.connection_pool = SimpleNamespace(
+            connection_kwargs={"host": "127.0.0.1", "port": 6379, "db": 0}
+        )
+        with self.assertRaises(AttributeError):
+            await client.execute_command("GET", "key")
+
+        connection = object.__new__(asyncpg.connection.Connection)
+        connection._aborted = True  # keep __del__ quiet on the stub
+        with self.assertRaises(Exception):
+            await connection.fetch("SELECT 1")
+
+        spans = {
+            span.name: span for span in self.span_exporter.get_finished_spans()
+        }
+        self.assertEqual("GET ?", spans["GET"].attributes["db.statement"])
+        self.assertEqual("redis", spans["GET"].attributes["db.system"])
+        self.assertEqual("SELECT 1", spans["SELECT"].attributes["db.statement"])
+        self.assertEqual("postgresql", spans["SELECT"].attributes["db.system"])
+
+
+@unittest.skipUnless(HAVE_OTEL, "tavolo-app[otel] not installed")
+class LogExportTest(unittest.TestCase):
+    def test_logs_are_exported_and_otel_records_filtered(self) -> None:
+        exporter = InMemoryLogRecordExporter()
+        resource = Resource.create({"service.name": "test"})
+        provider = LoggerProvider(resource=resource)
+        provider.add_log_record_processor(SimpleLogRecordProcessor(exporter))
+        handler = LoggingHandler(level=logging.NOTSET, logger_provider=provider)
+        handler.addFilter(_NoOtelLogs())
+        root = logging.getLogger()
+        previous_level = root.level
+        root.addHandler(handler)
+        root.setLevel(logging.DEBUG)
+        try:
+            logging.getLogger("tavolo.test").info("exported message")
+            logging.getLogger("opentelemetry.test").info("filtered message")
+            bodies = [r.log_record.body for r in exporter.get_finished_logs()]
+            self.assertIn("exported message", bodies)
+            self.assertNotIn("filtered message", bodies)
+            records = exporter.get_finished_logs()
+            self.assertEqual(
+                "test", records[0].resource.attributes["service.name"]
+            )
+        finally:
+            root.removeHandler(handler)
+            handler.close()
+            root.setLevel(previous_level)
+            provider.shutdown()
+
+
+if __name__ == "__main__":
+    unittest.main()

server/tests/test_websocket.py

@@ -131,10 +131,10 @@ class WebSocketTest(unittest.TestCase):
                 with self.assertRaises(WebSocketDisconnect) as caught:
                     async with aconnect_ws("/ws/games/no-such-game", ws_client):
                         pass
-                self.assertEqual(4404, caught.exception.code)
+                self.assertEqual(404, caught.exception.code)
 
     @async_test
-    async def test_non_player_is_closed(self) -> None:
+    async def test_non_player_watches_as_spectator(self) -> None:
         api_transport = ASGITransport(app=app)
         async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
             state = await self._started_game(client)
@@ -143,20 +143,42 @@ class WebSocketTest(unittest.TestCase):
             ws_transport = ASGIWebSocketTransport(app=app)
             async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
                 with ws_users([make_user("mallory")]):
-                    with self.assertRaises(WebSocketDisconnect) as caught:
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
-                        async with aconnect_ws(f"/ws/games/{game_id}", ws_client):
+                        first = await ws.receive_json()
-                            pass
+                        self.assertEqual("state", first["type"])
-                    self.assertEqual(4403, caught.exception.code)
+                        self.assertTrue(first["game"]["spectator"])
+                        self.assertNotIn("join_code", first["game"])
+                        self.assertIn("table", first["game"])
+                        self.assertEqual({"A": 0, "B": 0}, first["game"]["scores"])
+                        for player in first["game"]["players"]:
+                            self.assertNotIn("hand", player)
+                        # Spectators may not act.
+                        await ws.send_json({"action": "play", "card": "01D"})
+                        error = await ws.receive_json()
+                        self.assertEqual("error", error["type"])
+                        self.assertEqual("forbidden", error["code"])
 
     @async_test
-    async def test_unauthenticated_is_closed(self) -> None:
+    async def test_anonymous_user_watches_as_spectator(self) -> None:
+        api_transport = ASGITransport(app=app)
+        async with AsyncClient(transport=api_transport, base_url="http://127.0.0.1") as client:
+            state = await self._started_game(client)
+            game_id = state["id"]
+
             ws_transport = ASGIWebSocketTransport(app=app)
             async with AsyncClient(transport=ws_transport, base_url="http://testserver") as ws_client:
                 with ws_users([]):
-                with self.assertRaises(WebSocketDisconnect) as caught:
+                    async with aconnect_ws(f"/ws/games/{game_id}", ws_client) as ws:
-                    async with aconnect_ws("/ws/games/whatever", ws_client):
+                        first = await ws.receive_json()
-                        pass
+                        self.assertEqual("state", first["type"])
-                self.assertEqual(4401, caught.exception.code)
+                        self.assertTrue(first["game"]["spectator"])
+                        self.assertNotIn("join_code", first["game"])
+                        for player in first["game"]["players"]:
+                            self.assertNotIn("hand", player)
+                        await ws.send_json({"action": "play", "card": "01D"})
+                        error = await ws.receive_json()
+                        self.assertEqual("error", error["type"])
+                        self.assertEqual("forbidden", error["code"])
 
 
 async def _seed_last_play_state(hand_ack_timeout: int = 30) -> str:

web/src/api.rs

@@ -22,6 +22,19 @@ pub async fn me() -> Result<Option<User>, String> {
     resp.json().await.map(Some).map_err(|e| e.to_string())
 }
 
+/// Fetch the configured OIDC login providers (public endpoint).
+pub async fn auth_providers() -> Result<Vec<AuthProvider>, String> {
+    let resp = Request::get("/api/auth/providers")
+        .send()
+        .await
+        .map_err(|e| e.to_string())?;
+    if !resp.ok() {
+        return Err(server_error(resp.status()));
+    }
+    let page: AuthProvidersPage = resp.json().await.map_err(|e| e.to_string())?;
+    Ok(page.providers)
+}
+
 /// Fetch the card games the platform can host (for the creation dropdown).
 pub async fn game_types() -> Result<Vec<GameTypeInfo>, String> {
     let resp = Request::get("/api/game-types")
@@ -87,16 +100,32 @@ pub async fn join_preview(code: &str) -> Result<Option<JoinPreview>, String> {
     resp.json().await.map(Some).map_err(|e| e.to_string())
 }
 
-#[allow(dead_code)]
+/// Why a game connection failed before the first snapshot arrived.
-pub async fn game_state(game_id: &str) -> Result<GameView, String> {
+///
-    let resp = Request::get(&format!("/api/games/{game_id}"))
+/// A refused WebSocket handshake is invisible to the browser: the close
-        .send()
+/// event reports an abnormal closure (1006) with no HTTP status, so the
-        .await
+/// game page asks the REST API to tell a deliberate rejection from a
-        .map_err(|e| e.to_string())?;
+/// transient network problem. Anonymous users and non-players are
-    if !resp.ok() {
+/// welcome as spectators, so the only deliberate refusal is an unknown
-        return Err(server_error(resp.status()));
+/// game.
+pub enum GameEntry {
+    /// Unknown game (`404`): the id is wrong or the game's TTL expired.
+    Unavailable,
+    /// The API could not be asked (or answered unexpectedly): treat the
+    /// connection loss as transient and retry.
+    Transient,
+}
+
+/// Classify a failed game connection via `GET /api/games/{game_id}`,
+/// mirroring the status used to refuse the websocket upgrade.
+pub async fn probe_game(game_id: &str) -> GameEntry {
+    match Request::get(&format!("/api/games/{game_id}")).send().await {
+        Ok(resp) => match resp.status() {
+            404 => GameEntry::Unavailable,
+            _ => GameEntry::Transient,
+        },
+        Err(_) => GameEntry::Transient,
     }
-    resp.json().await.map_err(|e| e.to_string())
 }
 
 pub async fn my_matches(cursor: Option<&str>) -> Result<MatchesPage, String> {

web/src/components/briscola.rs

@@ -0,0 +1,190 @@
+//! The briscola deal-end summary screen.
+//!
+//! Shown when a deal finishes but the match continues: the points won in
+//! the deal just played, the running totals toward the target and the
+//! acknowledgement button (the server deals on when everyone is ready, or
+//! after the hand-end timeout).
+use sycamore::prelude::*;
+
+use crate::components::card::{card_back, card_img};
+use crate::model::{DealSummary, GameView};
+use crate::ws::GameSocket;
+
+/// One explanatory row: icon, title, plain-language sentence, points chip.
+fn summary_row(
+    icon: View,
+    title: &'static str,
+    text: String,
+    cls: &'static str,
+    chip: String,
+) -> View {
+    view! {
+        div(class=cls) {
+            div(class="score-icon") { (icon) }
+            div(class="score-body") {
+                div(class="score-title") { (title) }
+                div(class="score-text") { (text) }
+            }
+            div(class="score-points") { (chip) }
+        }
+    }
+}
+
+/// The scoring rows of one completed deal (also used by the final screen).
+pub fn deal_rows(summary: &DealSummary) -> View {
+    let a = summary.points.a;
+    let b = summary.points.b;
+    let cls = if summary.patta {
+        "score-row tie"
+    } else if a > b {
+        "score-row team-a"
+    } else {
+        "score-row team-b"
+    };
+    let chip = if summary.patta {
+        "patta".to_string()
+    } else {
+        format!("+{a} · +{b}")
+    };
+    let patta_note = summary.patta.then(|| view! {
+        p(class="text-warning small mb-0") {
+            "60–60: patta — the deal is replayed and its points do not count."
+        }
+    });
+    let points_row = summary_row(
+        card_img("01D".to_string(), "score-mini"),
+        "Deal points",
+        format!("Team A {a} · Team B {b}"),
+        cls,
+        chip,
+    );
+    let cards = summary.cards.map(|c| {
+        summary_row(
+            card_back("score-mini"),
+            "Cards captured",
+            format!("Team A {} · Team B {}", c.a, c.b),
+            "score-row",
+            format!("{} · {}", c.a, c.b),
+        )
+    });
+    view! {
+        div(class="score-rows") {
+            (points_row)
+            (patta_note)
+            (cards)
+        }
+    }
+}
+
+/// Running totals with progress toward the target, including the points
+/// gained in the deal just played (zero for a patta).
+fn totals(game: &GameView, summary: &DealSummary) -> View {
+    let target = game.target_score.max(1);
+    let pct_a = (100 * summary.totals.a / target).min(100);
+    let pct_b = (100 * summary.totals.b / target).min(100);
+    let (gained_a, gained_b) = if summary.patta {
+        (0, 0)
+    } else {
+        (summary.points.a, summary.points.b)
+    };
+    view! {
+        div(class="totals") {
+            div(class="total-row team-a") {
+                span(class="total-label") { "Team A" }
+                div(class="progress") {
+                    div(class="progress-fill", style=format!("width: {pct_a}%")) {}
+                }
+                span(class="total-value") {
+                    (summary.totals.a) " / " (target)
+                    span(class="gained") { "+" (gained_a) }
+                }
+            }
+            div(class="total-row team-b") {
+                span(class="total-label") { "Team B" }
+                div(class="progress") {
+                    div(class="progress-fill", style=format!("width: {pct_b}%")) {}
+                }
+                span(class="total-value") {
+                    (summary.totals.b) " / " (target)
+                    span(class="gained") { "+" (gained_b) }
+                }
+            }
+        }
+    }
+}
+
+/// The full deal-end modal: points + totals + acknowledgement button.
+pub fn deal_summary_modal(
+    game: GameView,
+    socket: Signal<Option<GameSocket>>,
+    now: Signal<f64>,
+) -> View {
+    let Some(summary) = game.last_deal.clone() else {
+        return view! {};
+    };
+    let viewer_seat = game
+        .players
+        .iter()
+        .find(|p| p.hand.is_some())
+        .map(|p| p.seat);
+    let acked = game.acknowledged.clone();
+    let already_acked = viewer_seat.is_some_and(|s| acked.contains(&s));
+    let waiting: Vec<String> = game
+        .players
+        .iter()
+        .filter(|p| !acked.contains(&p.seat))
+        .map(|p| p.name.clone())
+        .collect();
+    let countdown = game.hand_end_deadline.as_ref().map(|deadline| {
+        // A dynamic closure so only the ticking number re-renders, not the
+        // whole modal (which would swap DOM nodes under the user's cursor).
+        let deadline_ms = js_sys::Date::parse(deadline);
+        view! {
+            p(class="text-secondary small") {
+                "Auto-continuing in "
+                (move || {
+                    ((deadline_ms - now.get_clone()) / 1000.0).ceil().max(0.0) as i32
+                })
+                "s"
+            }
+        }
+    });
+
+    let title = format!("Deal {} — results", summary.deal);
+    let rows = deal_rows(&summary);
+    let totals_view = totals(&game, &summary);
+
+    let action = if game.spectator {
+        // Spectators cannot acknowledge; they just watch the summary.
+        view! {
+            p(class="text-secondary small mb-0") {
+                "Spectating — the next deal is dealt when every player is ready."
+            }
+        }
+    } else if already_acked {
+        let waiting_text = format!("Waiting for {}…", waiting.join(", "));
+        view! {
+            button(class="btn btn-warning", disabled=true) { (waiting_text) }
+        }
+    } else {
+        view! {
+            button(class="btn btn-warning", on:click=move |_| {
+                if let Some(s) = socket.get_clone() {
+                    s.ack();
+                }
+            }) { "Understood, next deal" }
+        }
+    };
+
+    view! {
+        div(class="overlay") {
+            div(class="picker summary-panel") {
+                h2 { (title) }
+                (rows)
+                (totals_view)
+                div(class="summary-actions") { (action) }
+                (countdown)
+            }
+        }
+    }
+}

web/src/components/copy.rs

@@ -0,0 +1,45 @@
+//! Clipboard copy button, shared by the join-code and watch-link actions.
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use sycamore::prelude::*;
+
+/// A button that copies `text` to the clipboard and shows "Copied!" for a
+/// moment. `label` is the idle caption.
+#[component(inline_props)]
+pub fn CopyButton(text: String, label: String) -> View {
+    let copied = create_signal(false);
+    // Held so the reset timer is cancelled if the button is rebuilt (e.g.
+    // another player joins) while the "Copied!" feedback is showing:
+    // firing it afterwards would set a disposed signal and panic.
+    let reset_timer: Rc<RefCell<Option<gloo_timers::callback::Timeout>>> =
+        Rc::new(RefCell::new(None));
+    on_cleanup({
+        let reset_timer = reset_timer.clone();
+        move || {
+            reset_timer.borrow_mut().take();
+        }
+    });
+
+    let on_click = {
+        let text = text.clone();
+        move |_| {
+            if let Some(win) = web_sys::window() {
+                let _ = win.navigator().clipboard().write_text(&text);
+            }
+            copied.set(true);
+            *reset_timer.borrow_mut() = Some(gloo_timers::callback::Timeout::new(
+                1500,
+                move || {
+                    copied.set(false);
+                },
+            ));
+        }
+    };
+
+    view! {
+        button(class="btn btn-outline-light", on:click=on_click) {
+            (move || if copied.get() { "Copied!".to_string() } else { label.clone() })
+        }
+    }
+}

web/src/components/mod.rs

@@ -1,4 +1,6 @@
+pub mod briscola;
 pub mod card;
+pub mod copy;
 pub mod nav;
 pub mod summary;
 pub mod toast;

web/src/components/summary.rs

@@ -260,7 +260,14 @@ pub fn hand_summary_modal(
     let totals_view = totals(&game);
     let title = format!("Hand {} — results", summary.hand);
 
-    let action = if already_acked {
+    let action = if game.spectator {
+        // Spectators cannot acknowledge; they just watch the summary.
+        view! {
+            p(class="text-secondary small mb-0") {
+                "Spectating — the next hand is dealt when every player is ready."
+            }
+        }
+    } else if already_acked {
         let waiting_text = format!("Waiting for {}…", waiting.join(", "));
         view! {
             button(class="btn btn-warning", disabled=true) { (waiting_text) }

web/src/model.rs

@@ -26,12 +26,15 @@ pub struct PlayerView {
     pub captured_count: usize,
     #[serde(default)]
     pub scope: i32,
+    /// Briscola: point value of the player's captured pile.
+    #[serde(default)]
+    pub points: i32,
     /// Own hand only; absent for the other players.
     #[serde(default)]
     pub hand: Option<Vec<String>>,
 }
 
-#[derive(Debug, Clone, Copy, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
 pub struct Scores {
     #[serde(rename = "A")]
     pub a: i32,
@@ -54,6 +57,38 @@ pub struct MoveView {
     pub pigliatutto: bool,
 }
 
+/// One card played in the current briscola trick, in play order.
+#[derive(Debug, Clone, Deserialize)]
+#[allow(dead_code)]
+pub struct TrickCard {
+    pub seat: usize,
+    pub card: String,
+}
+
+/// The most recently completed briscola trick.
+#[derive(Debug, Clone, Deserialize)]
+#[allow(dead_code)]
+pub struct LastTrick {
+    pub winner: usize,
+    #[serde(default)]
+    pub cards: Vec<TrickCard>,
+}
+
+/// The scoring breakdown of one completed briscola deal.
+#[derive(Debug, Clone, Deserialize)]
+#[allow(dead_code)]
+pub struct DealSummary {
+    #[serde(default)]
+    pub deal: i32,
+    /// A 60-60 deal: its points are discarded and the deal is replayed.
+    #[serde(default)]
+    pub patta: bool,
+    pub points: Scores,
+    pub totals: Scores,
+    #[serde(default)]
+    pub cards: Option<TeamCounts>,
+}
+
 #[derive(Debug, Clone, Copy, Deserialize)]
 pub struct TeamCounts {
     #[serde(rename = "A")]
@@ -112,11 +147,16 @@ pub struct HandSummary {
 #[allow(dead_code)]
 pub struct GameView {
     pub id: String,
+    /// The lobby join code; withheld by the server from spectators.
     #[serde(default)]
     pub join_code: String,
     /// Which card game this match is (id from /api/game-types).
     #[serde(default)]
     pub game_type: String,
+    /// Whether the viewer is watching without a seat: no hand, no join
+    /// code, and actions are rejected by the server.
+    #[serde(default)]
+    pub spectator: bool,
     /// Whether the napola rule is scored in this match.
     #[serde(default = "default_true")]
     pub napola: bool,
@@ -163,6 +203,30 @@ pub struct GameView {
     /// Legal captures per hand card; present only for the player on turn.
     #[serde(default)]
     pub legal_moves: Option<HashMap<String, Vec<Vec<String>>>>,
+    /// Briscola: number of seats at the table (2 or 4).
+    #[serde(default)]
+    pub player_count: usize,
+    /// Briscola: trump suit of the current deal (empty for other games).
+    #[serde(default)]
+    pub briscola_suit: String,
+    /// Briscola: the face-up trump card, until it is drawn.
+    #[serde(default)]
+    pub briscola_card: Option<String>,
+    /// Briscola: face-down cards left in the stock.
+    #[serde(default)]
+    pub stock_count: usize,
+    /// Briscola: cards of the trick in progress, in play order.
+    #[serde(default)]
+    pub trick: Vec<TrickCard>,
+    /// Briscola: seat that led the current trick.
+    #[serde(default)]
+    pub trick_leader: Option<usize>,
+    /// Briscola: the most recently completed trick.
+    #[serde(default)]
+    pub last_trick: Option<LastTrick>,
+    /// Briscola: scoring breakdown of the most recent deal.
+    #[serde(default)]
+    pub last_deal: Option<DealSummary>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -291,6 +355,13 @@ pub fn fmt_points(points: f64) -> String {
     }
 }
 
+/// Render a calendar instant as `YYYY-MM-DD HH:MM`. `month` is 0-based
+/// (the JavaScript `Date` convention); the other components are as
+/// returned by `Date`'s local-time getters.
+pub fn fmt_datetime_parts(year: u32, month: u32, day: u32, hour: u32, minute: u32) -> String {
+    format!("{year:04}-{:02}-{day:02} {hour:02}:{minute:02}", month + 1)
+}
+
 /// The caller's Elo rating for one game type (GET /api/me/ratings).
 #[derive(Debug, Clone, Deserialize)]
 #[allow(dead_code)]
@@ -337,6 +408,19 @@ pub struct GameTypesPage {
     pub results: Vec<GameTypeInfo>,
 }
 
+/// One configured OIDC login provider (GET /api/auth/providers).
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct AuthProvider {
+    pub name: String,
+    pub login_url: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct AuthProvidersPage {
+    #[serde(default)]
+    pub providers: Vec<AuthProvider>,
+}
+
 /// A join-code lookup result (GET /api/games/preview): the game's lobby
 /// payload plus its display name, for the pre-join summary. The options
 /// echoed by the engine land in `details` under their `options_schema`
@@ -542,8 +626,39 @@ pub fn card_asset(code: &str) -> String {
     format!("/assets/cards/{code}.svg")
 }
 
+/// Whether a game type is one of the briscola variants.
+pub fn is_briscola(game_type: &str) -> bool {
+    game_type == "briscola" || game_type == "briscola_a_quattro"
+}
+
+/// Human-readable suit name for a one-letter code (`D` -> "denari").
+pub fn suit_name(suit: &str) -> String {
+    match suit {
+        "D" => "denari".to_string(),
+        "C" => "coppe".to_string(),
+        "S" => "spade".to_string(),
+        "B" => "bastoni".to_string(),
+        _ => suit.to_string(),
+    }
+}
+
 pub const CARD_BACK: &str = "/assets/cards/back.svg";
 
+/// Display order key for a hand: rank ascending (01..10, i.e. 1..7 then
+/// Fante, Cavallo, Re), then suit (denari, coppe, spade, bastoni).
+/// Malformed codes sort last.
+pub fn hand_sort_key(code: &str) -> (u8, u8) {
+    let rank = code.get(..2).and_then(|r| r.parse().ok()).unwrap_or(u8::MAX);
+    let suit = match code.get(2..3) {
+        Some("D") => 0,
+        Some("C") => 1,
+        Some("S") => 2,
+        Some("B") => 3,
+        _ => u8::MAX,
+    };
+    (rank, suit)
+}
+
 /// Human-friendly rank+suit label, e.g. `07D` -> "7 of denari".
 pub fn card_label(code: &str) -> String {
     if code.len() != 3 {
@@ -593,6 +708,38 @@ mod tests {
         assert_eq!("7 di denari", card_label("07D"));
     }
 
+    #[test]
+    fn hand_sort_orders_ranks_ascending() {
+        let mut hand = vec![
+            "10B".to_string(),
+            "01S".to_string(),
+            "07D".to_string(),
+            "08C".to_string(),
+        ];
+        hand.sort_by_key(|c| hand_sort_key(c));
+        assert_eq!(vec!["01S", "07D", "08C", "10B"], hand);
+    }
+
+    #[test]
+    fn hand_sort_breaks_ties_by_suit() {
+        let mut hand = vec![
+            "02B".to_string(),
+            "02S".to_string(),
+            "02C".to_string(),
+            "02D".to_string(),
+            "01S".to_string(),
+        ];
+        hand.sort_by_key(|c| hand_sort_key(c));
+        assert_eq!(vec!["01S", "02D", "02C", "02S", "02B"], hand);
+    }
+
+    #[test]
+    fn hand_sort_puts_malformed_codes_last() {
+        let mut hand = vec!["07D".to_string(), "xx".to_string(), "AB1".to_string()];
+        hand.sort_by_key(|c| hand_sort_key(c));
+        assert_eq!(vec!["07D", "xx", "AB1"], hand);
+    }
+
     fn scopone_match() -> MatchSummary {
         serde_json::from_value(json!({
             "id": "m1",
@@ -658,6 +805,12 @@ mod tests {
         assert_eq!("2.5", fmt_points(2.5));
     }
 
+    #[test]
+    fn fmt_datetime_parts_pads_and_offsets_month() {
+        assert_eq!("2026-09-19 05:02", fmt_datetime_parts(2026, 8, 19, 5, 2));
+        assert_eq!("2026-01-01 00:00", fmt_datetime_parts(2026, 0, 1, 0, 0));
+    }
+
     #[test]
     fn leaderboard_points_accept_floats() {
         let e: LeaderboardEntry = serde_json::from_value(json!({
@@ -807,11 +960,39 @@ mod tests {
         .unwrap();
         assert_eq!("playing", g.phase);
         assert!(g.asso_pigliatutto);
+        assert!(!g.spectator);
         assert_eq!(None, g.players[0].hand);
         assert_eq!(Some(vec!["01D".to_string()]), g.players[1].hand);
         assert_eq!(Some(true), g.your_turn);
     }
 
+    #[test]
+    fn game_view_parses_spectator_snapshot() {
+        // A spectator payload: no hand anywhere, no join code, but the
+        // public table state is present.
+        let g: GameView = serde_json::from_value(json!({
+            "id": "11111111-2222-3333-4444-555555555555",
+            "game_type": "scopone_scientifico",
+            "spectator": true,
+            "phase": "playing",
+            "target_score": 11,
+            "scores": {"A": 2, "B": 1},
+            "table": ["07C"],
+            "players": [
+                {"sub": "alice", "name": "Alice", "seat": 0, "team": "A",
+                 "cards_left": 5, "captured_count": 12, "scope": 1},
+            ],
+        }))
+        .unwrap();
+        assert!(g.spectator);
+        assert_eq!("", g.join_code);
+        assert_eq!(Some(Scores { a: 2, b: 1 }), g.scores);
+        assert_eq!(vec!["07C".to_string()], g.table);
+        assert_eq!(None, g.players[0].hand);
+        assert_eq!(12, g.players[0].captured_count);
+        assert_eq!(1, g.players[0].scope);
+    }
+
     #[test]
     fn move_view_parses_pigliatutto() {
         let mv: MoveView = serde_json::from_value(json!({
@@ -948,4 +1129,112 @@ mod tests {
         assert!(g.default_options().is_empty());
         assert_eq!(0, g.min_players);
     }
+
+    #[test]
+    fn is_briscola_matches_both_variants() {
+        assert!(is_briscola("briscola"));
+        assert!(is_briscola("briscola_a_quattro"));
+        assert!(!is_briscola("scopone_scientifico"));
+        assert_eq!("denari", suit_name("D"));
+        assert_eq!("coppe", suit_name("C"));
+        assert_eq!("spade", suit_name("S"));
+        assert_eq!("bastoni", suit_name("B"));
+        assert_eq!("?", suit_name("?"));
+    }
+
+    #[test]
+    fn game_view_parses_briscola_payload() {
+        let g: GameView = serde_json::from_value(json!({
+            "id": "b1",
+            "join_code": "ABC123",
+            "game_type": "briscola",
+            "phase": "playing",
+            "target_score": 61,
+            "player_count": 2,
+            "hand_number": 1,
+            "dealer": 0,
+            "turn": 1,
+            "scores": {"A": 0, "B": 0},
+            "briscola_suit": "D",
+            "briscola_card": "07D",
+            "stock_count": 33,
+            "trick": [{"seat": 1, "card": "04C"}],
+            "trick_leader": 1,
+            "last_trick": null,
+            "players": [
+                {"sub": "alice", "name": "Alice", "seat": 0, "team": "A",
+                 "cards_left": 3, "captured_count": 0, "points": 0,
+                 "hand": ["01D"]},
+                {"sub": "bob", "name": "Bob", "seat": 1, "team": "B",
+                 "cards_left": 3, "captured_count": 0, "points": 0},
+            ],
+            "last_deal": null,
+            "acknowledged": [],
+            "hand_end_deadline": null,
+            "turn_deadline": "2026-01-01T00:00:30+00:00",
+            "your_turn": true,
+        }))
+        .unwrap();
+        assert!(is_briscola(&g.game_type));
+        assert_eq!("D", g.briscola_suit);
+        assert_eq!(Some("07D".to_string()), g.briscola_card);
+        assert_eq!(33, g.stock_count);
+        assert_eq!(1, g.trick.len());
+        assert_eq!(1, g.trick[0].seat);
+        assert_eq!("04C", g.trick[0].card);
+        assert_eq!(Some(1), g.trick_leader);
+        assert_eq!(0, g.players[0].points);
+        assert_eq!(Some(true), g.your_turn);
+    }
+
+    #[test]
+    fn game_view_parses_briscola_deal_summary() {
+        let g: GameView = serde_json::from_value(json!({
+            "id": "b1",
+            "game_type": "briscola_a_quattro",
+            "phase": "hand_end",
+            "player_count": 4,
+            "scores": {"A": 55, "B": 65},
+            "last_deal": {
+                "deal": 1,
+                "patta": false,
+                "points": {"A": 55, "B": 65},
+                "totals": {"A": 55, "B": 65},
+                "cards": {"A": 19, "B": 21},
+            },
+            "last_trick": {
+                "winner": 3,
+                "cards": [
+                    {"seat": 0, "card": "02D"},
+                    {"seat": 1, "card": "05D"},
+                    {"seat": 2, "card": "04D"},
+                    {"seat": 3, "card": "07D"},
+                ],
+            },
+        }))
+        .unwrap();
+        let deal = g.last_deal.unwrap();
+        assert_eq!(1, deal.deal);
+        assert!(!deal.patta);
+        assert_eq!(Scores { a: 55, b: 65 }, deal.points);
+        assert_eq!(Scores { a: 55, b: 65 }, deal.totals);
+        let cards = deal.cards.unwrap();
+        assert_eq!(19, cards.a);
+        assert_eq!(21, cards.b);
+        let trick = g.last_trick.unwrap();
+        assert_eq!(3, trick.winner);
+        assert_eq!(4, trick.cards.len());
+    }
+
+    #[test]
+    fn deal_summary_defaults() {
+        let d: DealSummary = serde_json::from_value(json!({
+            "points": {"A": 60, "B": 60},
+            "totals": {"A": 10, "B": 20},
+        }))
+        .unwrap();
+        assert!(!d.patta);
+        assert_eq!(0, d.deal);
+        assert!(d.cards.is_none());
+    }
 }

web/src/pages/briscola.rs

@@ -0,0 +1,258 @@
+//! Briscola table view: classic two-player and four-player partnership.
+//!
+//! The two variants share this view: four seats render in the usual cross
+//! (partners opposite), two seats stack opponent over player. The center
+//! holds the trick in progress, the stock pile and the face-up briscola.
+use sycamore::prelude::*;
+
+use crate::components::card::{card_back, card_img};
+use crate::components::copy::CopyButton;
+use crate::model::{hand_sort_key, suit_name, GameView, PlayerView, Scores};
+use crate::pages::game::watch_link;
+
+fn player_for_seat(game: &GameView, seat: usize) -> Option<PlayerView> {
+    game.players.iter().find(|p| p.seat == seat).cloned()
+}
+
+/// Panel for one player seat (name, team, hidden card count, points).
+fn seat_panel(game: GameView, seat: usize, position: &'static str) -> View {
+    let Some(player) = player_for_seat(&game, seat) else {
+        return view! {};
+    };
+    let active = game.phase == "playing" && game.turn == seat;
+    let cls = format!(
+        "seat seat-{position}{}",
+        if active { " active" } else { "" }
+    );
+    let name = player.name.clone();
+    let team = player.team.clone();
+    let points = player.points;
+    let captured = player.captured_count;
+    let backs = (0..player.cards_left)
+        .map(|_| card_back("mini"))
+        .collect::<Vec<_>>();
+    view! {
+        div(class=cls) {
+            div(class="seat-name") {
+                (name)
+                span(class="team-badge") { "Team " (team) }
+            }
+            div(class="seat-cards") { (backs) }
+            div(class="seat-stats") {
+                (points) " points · " (captured) " cards"
+            }
+        }
+    }
+}
+
+/// The stock pile with the face-up briscola card beside it.
+fn stock_view(game: &GameView) -> View {
+    let backs = (0..game.stock_count.min(3))
+        .map(|_| card_back("stock-card"))
+        .collect::<Vec<_>>();
+    let trump = game
+        .briscola_card
+        .clone()
+        .map(|code| card_img(code, "briscola-card"));
+    let label = format!("{} in stock", game.stock_count);
+    view! {
+        div(class="stock") {
+            div(class="stock-pile") { (backs) }
+            (trump)
+            span(class="stock-count") { (label) }
+        }
+    }
+}
+
+/// The cards of the trick in progress, in play order, with player names.
+fn trick_view(game: &GameView) -> View {
+    if game.trick.is_empty() {
+        return view! { p(class="table-empty") { "Empty table" } };
+    }
+    let cards = game
+        .trick
+        .iter()
+        .map(|tc| {
+            let name = player_for_seat(game, tc.seat)
+                .map(|p| p.name)
+                .unwrap_or_default();
+            let card = card_img(tc.card.clone(), "table-card");
+            view! {
+                div(class="trick-slot") {
+                    span(class="trick-name") { (name) }
+                    (card)
+                }
+            }
+        })
+        .collect::<Vec<_>>();
+    view! { (cards) }
+}
+
+/// Announcement strip for the most recently completed trick.
+fn last_trick_banner(game: &GameView) -> View {
+    let Some(trick) = game.last_trick.clone() else {
+        return view! {};
+    };
+    let name = player_for_seat(game, trick.winner)
+        .map(|p| p.name)
+        .unwrap_or_default();
+    let cards = trick
+        .cards
+        .iter()
+        .map(|tc| card_img(tc.card.clone(), "move-card"))
+        .collect::<Vec<_>>();
+    view! {
+        div(class="move-banner") {
+            strong { (name) }
+            span { " takes the trick " }
+            (cards)
+        }
+    }
+}
+
+/// The main briscola table.
+pub fn briscola_table(
+    game: GameView,
+    on_hand_card: impl Fn(String) + Copy + 'static,
+    now: Signal<f64>,
+) -> View {
+    // Own seat: the only player entry carrying a hand. Spectators have no
+    // hand, so they watch from seat 0's perspective.
+    let viewer_seat = game
+        .players
+        .iter()
+        .find(|p| p.hand.is_some())
+        .map(|p| p.seat)
+        .unwrap_or(0);
+    let player_count = if game.player_count > 0 {
+        game.player_count
+    } else {
+        game.players.len().max(1)
+    };
+    let my_turn = game.your_turn == Some(true);
+    let turn_note = if game.phase == "finished" {
+        "Match finished".to_string()
+    } else if game.phase == "hand_end" {
+        "Deal finished".to_string()
+    } else if my_turn {
+        "Your turn".to_string()
+    } else {
+        let name = player_for_seat(&game, game.turn)
+            .map(|p| p.name)
+            .unwrap_or_default();
+        format!("{name}'s turn")
+    };
+    let turn_cls = if my_turn { "turn-note you" } else { "turn-note" };
+    let countdown = game.turn_deadline.as_ref().map(|deadline| {
+        // A dynamic closure so only the ticking number re-renders.
+        let deadline_ms = js_sys::Date::parse(deadline);
+        view! {
+            span(class="turn-timer") {
+                "Auto-play in "
+                (move || {
+                    ((deadline_ms - now.get_clone()) / 1000.0).ceil().max(0.0) as i32
+                })
+                "s"
+            }
+        }
+    });
+
+    let scores = game.scores.unwrap_or(Scores { a: 0, b: 0 });
+    let target = game.target_score;
+    let deal = game.hand_number;
+
+    let (grid_cls, top, left, right) = if player_count == 2 {
+        (
+            "table-grid duo",
+            seat_panel(game.clone(), (viewer_seat + 1) % 2, "top"),
+            view! {},
+            view! {},
+        )
+    } else {
+        (
+            "table-grid",
+            seat_panel(game.clone(), (viewer_seat + 2) % 4, "top"),
+            seat_panel(game.clone(), (viewer_seat + 1) % 4, "left"),
+            seat_panel(game.clone(), (viewer_seat + 3) % 4, "right"),
+        )
+    };
+
+    let viewer = player_for_seat(&game, viewer_seat);
+    let my_points = viewer.as_ref().map(|p| p.points).unwrap_or(0);
+    let mut hand = viewer.and_then(|p| p.hand).unwrap_or_default();
+    hand.sort_by_key(|c| hand_sort_key(c));
+    let hand_cards = hand
+        .into_iter()
+        .map(|code| {
+            let card_view = card_img(code.clone(), "hand-card");
+            view! {
+                button(class="hand-slot", on:click=move |_| {
+                    if my_turn {
+                        on_hand_card(code.clone());
+                    }
+                }) { (card_view) }
+            }
+        })
+        .collect::<Vec<_>>();
+    let hint = my_turn.then(|| view! {
+        p(class="text-secondary small text-center") {
+            "Click a card to play it."
+        }
+    });
+
+    // Spectators have no hand: render the pivot seat as a regular panel so
+    // its points stay visible where the hand would be.
+    let bottom = if game.spectator {
+        seat_panel(game.clone(), viewer_seat, "bottom")
+    } else {
+        view! {
+            div(class="seat-bottom") {
+                div(class="seat-stats own-stats") { (my_points) " points" }
+                div(class="hand") { (hand_cards) }
+                (hint)
+            }
+        }
+    };
+
+    let spectator_badge = game.spectator.then(|| view! {
+        span(class="spectator-badge") { "Spectating" }
+    });
+    let watch_link = watch_link(&game.id);
+    let trump_badge = (!game.briscola_suit.is_empty()).then(|| {
+        let suit = suit_name(&game.briscola_suit);
+        view! { span(class="briscola-badge") { "Briscola: " (suit) } }
+    });
+    // Precomputed so the final view's closures only capture owned views.
+    let banner = last_trick_banner(&game);
+    let trick = trick_view(&game);
+    let stock = stock_view(&game);
+
+    view! {
+        div(class="table-wrap") {
+            div(class="hud") {
+                a(href="/") { "← Lobby" }
+                span { "Deal " (deal) }
+                (trump_badge)
+                (spectator_badge)
+                span(class="hud-scores") {
+                    "Team A " (scores.a) " — " (scores.b) " Team B (target "
+                    (target) ")"
+                }
+                span(class=turn_cls) { (turn_note) }
+                (countdown)
+                CopyButton(text=watch_link, label="Copy watch link".to_string())
+            }
+            div(class=grid_cls) {
+                (top)
+                (left)
+                div(class="center") {
+                    (banner)
+                    div(class="table-cards") { (trick) }
+                    (stock)
+                }
+                (right)
+                (bottom)
+            }
+        }
+    }
+}

web/src/pages/game.rs

@@ -1,14 +1,21 @@
 //! Live game page: table view over the websocket.
 use std::cell::Cell;
-use std::cell::RefCell;
 use std::rc::Rc;
 
 use sycamore::prelude::*;
+use wasm_bindgen_futures::spawn_local;
 
+use crate::api;
+use crate::components::briscola::{deal_rows, deal_summary_modal};
 use crate::components::card::{card_back, card_img};
+use crate::components::copy::CopyButton;
 use crate::components::summary::{hand_summary_modal, summary_rows};
 use crate::components::toast::toast;
-use crate::model::{card_label, GameView, MoveView, PlayerView, Scores, ServerMessage};
+use crate::model::{
+    card_label, hand_sort_key, is_briscola, GameView, MoveView, PlayerView, Scores,
+    ServerMessage,
+};
+use crate::pages::briscola::briscola_table;
 use crate::ws::{self, GameSocket};
 
 fn send_play(socket: Signal<Option<GameSocket>>, card: String, capture: Option<Vec<String>>) {
@@ -17,6 +24,14 @@ fn send_play(socket: Signal<Option<GameSocket>>, card: String, capture: Option<V
     }
 }
 
+/// The absolute, shareable URL of this game's page, for the clipboard.
+pub(crate) fn watch_link(id: &str) -> String {
+    let origin = web_sys::window()
+        .and_then(|w| w.location().origin().ok())
+        .unwrap_or_default();
+    format!("{origin}/game/{id}")
+}
+
 /// Panel for one player seat (name, team, hidden card count, stats).
 fn seat_panel(game: GameView, seat: usize, position: &'static str) -> View {
     let Some(player) = game.players.iter().find(|p| p.seat == seat).cloned() else {
@@ -135,23 +150,33 @@ fn start_connect(id: Rc<String>, ctx: ConnCtx, alive: Rc<Cell<bool>>) {
     let on_close = {
         let id = id.clone();
         let alive = alive.clone();
-        move |code: Option<u16>| {
+        move |_code: Option<u16>| {
             if !alive.get() {
                 return;
             }
             ctx.closed.set(true);
-            match code {
+            if ctx.game.get_clone().is_none() && ctx.attempts.get() == 0 {
-                Some(4401) => {
+                // The connection ended before any snapshot arrived. A
-                    ctx.fatal.set(true);
+                // refused handshake looks exactly like a network drop to
-                    ctx.error
+                // the browser (close code 1006, no HTTP status), so ask
-                        .set(Some("Session expired — please log in again.".to_string()));
+                // the API whether the server deliberately rejected us —
-                }
+                // in which case retrying is pointless — or the loss was
-                Some(4403) | Some(4404) => {
+                // transient. Only on the first failure: later attempts
+                // are governed by the retry backoff.
+                let id = id.clone();
+                let alive = alive.clone();
+                spawn_local(async move {
+                    match api::probe_game(&id).await {
+                        api::GameEntry::Unavailable => {
                             ctx.fatal.set(true);
                             ctx.error
                                 .set(Some("This game is no longer available.".to_string()));
                         }
-                _ => schedule_retry(id.clone(), ctx, alive.clone()),
+                        api::GameEntry::Transient => schedule_retry(id, ctx, alive),
+                    }
+                });
+            } else {
+                schedule_retry(id.clone(), ctx, alive.clone());
             }
         }
     };
@@ -367,6 +392,10 @@ pub fn GamePage(id: String) -> View {
                     }
                 }
                 Some(g) if g.phase == "lobby" => view! { LobbyView(game=g) },
+                // Briscola has its own table view for both variants.
+                Some(g) if is_briscola(&g.game_type) => {
+                    briscola_table(g, on_hand_card, now)
+                }
                 // The live table is scopone-specific; other games get a
                 // fallback until they ship their own play view.
                 Some(g) if g.game_type == "scopone_scientifico" => {
@@ -381,6 +410,9 @@ pub fn GamePage(id: String) -> View {
                 Some(g) if g.phase == "hand_end" && g.game_type == "scopone_scientifico" => {
                     hand_summary_modal(g, socket, now)
                 }
+                Some(g) if g.phase == "hand_end" && is_briscola(&g.game_type) => {
+                    deal_summary_modal(g, socket, now)
+                }
                 _ => view! {},
             })
             (move || game_over_view(over.get_clone(), game.get_clone()))
@@ -390,38 +422,16 @@ pub fn GamePage(id: String) -> View {
 
 /// Lobby view while waiting for the remaining players. The seat count
 /// comes from the payload (`seats_open`), so games with other player
-/// counts render correctly.
+/// counts render correctly. Spectators (no seat, no join code) get a
+/// "not started yet" note and the watch link instead.
 #[component(inline_props)]
 fn LobbyView(game: GameView) -> View {
     let seats_open = game
         .seats_open
         .unwrap_or_else(|| 4usize.saturating_sub(game.players.len()));
+    let spectator = game.spectator;
     let join_code = game.join_code.clone();
-    let copied = create_signal(false);
+    let watch_link = watch_link(&game.id);
-    // Held so the reset timer is cancelled if the waiting room is rebuilt
-    // (e.g. another player joins) while the "Copied!" feedback is showing:
-    // firing it afterwards would set a disposed signal and panic.
-    let reset_timer: Rc<RefCell<Option<gloo_timers::callback::Timeout>>> =
-        Rc::new(RefCell::new(None));
-    on_cleanup({
-        let reset_timer = reset_timer.clone();
-        move || {
-            reset_timer.borrow_mut().take();
-        }
-    });
-
-    let copy = {
-        let join_code = join_code.clone();
-        move |_| {
-            if let Some(win) = web_sys::window() {
-                let _ = win.navigator().clipboard().write_text(&join_code);
-            }
-            copied.set(true);
-            *reset_timer.borrow_mut() = Some(gloo_timers::callback::Timeout::new(1500, move || {
-                copied.set(false);
-            }));
-        }
-    };
 
     let players = game
         .players
@@ -455,18 +465,39 @@ fn LobbyView(game: GameView) -> View {
     };
     let percent_style = format!("width: {percent}%");
 
+    // The server withholds the join code from spectators; they get a
+    // "not started yet" note and can share the watch link instead.
+    let share = if spectator {
+        view! {
+            p(class="text-secondary") {
+                "This game hasn't started yet — waiting for the players to take their seats."
+            }
+            div(class="d-grid mb-4") {
+                CopyButton(text=watch_link, label="Copy watch link".to_string())
+            }
+        }
+    } else {
+        // Separate clones: each interpolation/prop captures its own copy.
+        let display_code = join_code.clone();
+        let copy_code = join_code.clone();
+        view! {
+            p(class="text-secondary") { "Share this join code with your friends:" }
+            p(class="code-display") { (display_code) }
+            div(class="d-grid gap-2 mb-4") {
+                CopyButton(text=copy_code, label="Copy code".to_string())
+                CopyButton(text=watch_link, label="Copy watch link".to_string())
+            }
+        }
+    };
+
     view! {
         div(class="container page-shell py-4") {
             div(class="card status-card") {
                 div(class="card-body p-4") {
-                    h1(class="h4 mb-3") { "Waiting for players" }
+                    h1(class="h4 mb-3") {
-                    p(class="text-secondary") { "Share this join code with your friends:" }
+                        (if spectator { "Game not started yet" } else { "Waiting for players" })
-                    p(class="code-display") { (join_code) }
-                    div(class="d-grid mb-4") {
-                        button(class="btn btn-outline-light", on:click=copy) {
-                            (move || if copied.get() { "Copied!" } else { "Copy code" })
-                        }
                     }
+                    (share)
                     ul(class="list-group list-group-flush text-start mb-3") {
                         (players)
                         (open_seats)
@@ -519,7 +550,8 @@ fn table_view(
     selected: Signal<Option<String>>,
     now: Signal<f64>,
 ) -> View {
-    // Own seat: the only player entry carrying a hand.
+    // Own seat: the only player entry carrying a hand. Spectators have no
+    // hand, so they watch from seat 0's perspective.
     let viewer_seat = game
         .players
         .iter()
@@ -576,7 +608,8 @@ fn table_view(
     let viewer = player_for_seat(&game, viewer_seat);
     let my_captured = viewer.as_ref().map(|p| p.captured_count).unwrap_or(0);
     let my_scope = viewer.as_ref().map(|p| p.scope).unwrap_or(0);
-    let hand = viewer.and_then(|p| p.hand).unwrap_or_default();
+    let mut hand = viewer.and_then(|p| p.hand).unwrap_or_default();
+    hand.sort_by_key(|c| hand_sort_key(c));
     let current_selection = selected.get_clone();
     let hand_cards = hand
         .into_iter()
@@ -604,18 +637,41 @@ fn table_view(
         }
     });
 
+    // Spectators have no hand: render the pivot seat as a regular panel
+    // so its captured count and scope stay visible where the hand would be.
+    let bottom = if game.spectator {
+        seat_panel(game.clone(), viewer_seat, "bottom")
+    } else {
+        view! {
+            div(class="seat-bottom") {
+                div(class="seat-stats own-stats") {
+                    (my_captured) " captured · " (my_scope) " scope"
+                }
+                div(class="hand") { (hand_cards) }
+                (hint)
+            }
+        }
+    };
+
+    let spectator_badge = game.spectator.then(|| view! {
+        span(class="spectator-badge") { "Spectating" }
+    });
+    let watch_link = watch_link(&game.id);
+
     view! {
         div(class="table-wrap") {
             div(class="hud") {
                 a(href="/") { "← Lobby" }
                 span { "Hand " (hand_number) }
                 (rule_badge)
+                (spectator_badge)
                 span(class="hud-scores") {
                     "Team A " (scores.a) " — " (scores.b) " Team B (target "
                     (target_score) ")"
                 }
                 span(class=turn_cls) { (turn_note) }
                 (countdown)
+                CopyButton(text=watch_link, label="Copy watch link".to_string())
             }
             div(class="table-grid") {
                 (top)
@@ -628,13 +684,7 @@ fn table_view(
                     }
                 }
                 (right)
-                div(class="seat-bottom") {
+                (bottom)
-                    div(class="seat-stats own-stats") {
-                        (my_captured) " captured · " (my_scope) " scope"
-                    }
-                    div(class="hand") { (hand_cards) }
-                    (hint)
-                }
             }
         }
     }
@@ -677,11 +727,11 @@ fn capture_picker(
     }
 }
 
-/// End-of-match overlay (scopone's team score; other games render
+/// End-of-match overlay: the final hand/deal breakdown and the winner.
-/// nothing until they ship their own play view).
 fn game_over_view(over: Option<(Scores, Option<String>)>, game: Option<GameView>) -> View {
+    let briscola = game.as_ref().is_some_and(|g| is_briscola(&g.game_type));
     if let Some(g) = &game {
-        if g.game_type != "scopone_scientifico" {
+        if g.game_type != "scopone_scientifico" && !briscola {
             return view! {};
         }
     }
@@ -695,12 +745,23 @@ fn game_over_view(over: Option<(Scores, Option<String>)>, game: Option<GameView>
         Some((scores, winner)) => {
             let winner = winner.unwrap_or_else(|| "?".to_string());
             let line = format!("Team {winner} wins {} – {}", scores.a, scores.b);
-            // Explain the final hand's scoring before the result.
+            // Spectators have no match history to look at.
-            let final_summary = game
+            let spectator = game.as_ref().is_some_and(|g| g.spectator);
-                .and_then(|g| g.last_hand)
+            // Explain the final hand's (scopone) or deal's (briscola)
-                .map(|s| {
+            // scoring before the result.
-                    let rows = summary_rows(s);
+            let final_summary: View = if briscola {
-                    view! { (rows) }
+                match game.as_ref().and_then(|g| g.last_deal.clone()) {
+                    Some(deal) => deal_rows(&deal),
+                    None => view! {},
+                }
+            } else {
+                match game.as_ref().and_then(|g| g.last_hand.clone()) {
+                    Some(hand) => summary_rows(hand),
+                    None => view! {},
+                }
+            };
+            let my_matches = (!spectator).then(|| view! {
+                a(class="btn btn-outline-light", href="/history") { "My matches" }
             });
             view! {
                 div(class="overlay") {
@@ -710,7 +771,7 @@ fn game_over_view(over: Option<(Scores, Option<String>)>, game: Option<GameView>
                         p(class="final-score") { (line) }
                         div(class="gameover-actions") {
                             a(class="btn btn-warning", href="/") { "Back to lobby" }
-                            a(class="btn btn-outline-light", href="/history") { "My matches" }
+                            (my_matches)
                         }
                     }
                 }

web/src/pages/history.rs

@@ -68,6 +68,23 @@ fn game_name(game_types: &[GameTypeInfo], game_type: &str) -> String {
         .unwrap_or_else(|| game_type.to_string())
 }
 
+/// The match's finish instant in the browser's local timezone, as
+/// `YYYY-MM-DD HH:MM`. Falls back to the raw UTC prefix when the browser
+/// cannot parse the timestamp.
+fn local_finished(iso: &str) -> String {
+    let date = js_sys::Date::new(&wasm_bindgen::JsValue::from_str(iso));
+    if date.get_time().is_nan() {
+        return iso.replace('T', " ").chars().take(16).collect();
+    }
+    crate::model::fmt_datetime_parts(
+        date.get_full_year(),
+        date.get_month(),
+        date.get_date(),
+        date.get_hours(),
+        date.get_minutes(),
+    )
+}
+
 #[component]
 pub fn HistoryPage() -> View {
     let page = create_signal(Option::<MatchesPage>::None);
@@ -131,12 +148,7 @@ pub fn HistoryPage() -> View {
                             .get_clone()
                             .into_iter()
                             .map(|m| {
-                                let finished = m
+                                let finished = local_finished(&m.finished_at);
-                                    .finished_at
-                                    .replace('T', " ")
-                                    .chars()
-                                    .take(16)
-                                    .collect::<String>();
                                 let game = game_name(&names, &m.game_type);
                                 let mut cells: Vec<View> = team_columns(&m)
                                     .iter()

web/src/pages/lobby.rs

@@ -14,18 +14,47 @@ use sycamore_router::navigate;
 use crate::api;
 use crate::components::card::card_back;
 use crate::components::toast::toast;
-use crate::model::{GameTypeInfo, JoinPreview, OptionField, OptionKind, PlayerRating, User};
+use crate::model::{
+    AuthProvider, GameTypeInfo, JoinPreview, OptionField, OptionKind, PlayerRating, User,
+};
 
 /// Used when the game-types fetch fails: match creation must still work.
 fn fallback_game_types() -> Vec<GameTypeInfo> {
-    vec![GameTypeInfo {
+    vec![
+        GameTypeInfo {
             id: "scopone_scientifico".to_string(),
             name: "Scopone scientifico".to_string(),
             description: String::new(),
             min_players: 4,
             max_players: 4,
             options_schema: serde_json::Value::Null,
-    }]
+        },
+        GameTypeInfo {
+            id: "briscola".to_string(),
+            name: "Briscola".to_string(),
+            description: String::new(),
+            min_players: 2,
+            max_players: 2,
+            options_schema: serde_json::Value::Null,
+        },
+        GameTypeInfo {
+            id: "briscola_a_quattro".to_string(),
+            name: "Briscola a quattro".to_string(),
+            description: String::new(),
+            min_players: 4,
+            max_players: 4,
+            options_schema: serde_json::Value::Null,
+        },
+    ]
+}
+
+/// Human-readable label for a provider name ("google" -> "Google").
+fn provider_label(name: &str) -> String {
+    let mut chars = name.chars();
+    match chars.next() {
+        Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
+        None => String::new(),
+    }
 }
 
 fn json_to_string(value: &serde_json::Value) -> String {
@@ -283,6 +312,8 @@ fn join_preview_panel(
 pub fn LobbyPage() -> View {
     // Outer None = still loading; Some(None) = logged out.
     let user = create_signal(Option::<Option<User>>::None);
+    // Configured login providers, for the logged-out card's buttons.
+    let auth_providers = create_signal(Vec::<AuthProvider>::new());
     // The player's Elo ratings, one row per game type played.
     let ratings = create_signal(Vec::<PlayerRating>::new());
     let error = create_signal(Option::<String>::None);
@@ -400,6 +431,12 @@ pub fn LobbyPage() -> View {
         }
     });
 
+    spawn_local(async move {
+        if let Ok(list) = api::auth_providers().await {
+            auth_providers.set(list);
+        }
+    });
+
     let on_create = move |_| {
         let game_type = selected_game.get_clone();
         let opts: serde_json::Map<String, serde_json::Value> =
@@ -462,8 +499,15 @@ pub fn LobbyPage() -> View {
                                 }
                                 p(class="text-secondary") { "Log in with your account to play." }
                                 // rel="external" opts out of the SPA router's click
-                                // interception: this must be a full page navigation
+                                // interception: these must be full page navigations
-                                // to the backend's OIDC login endpoint.
+                                // to the backend's OIDC login endpoints.
+                                (move || {
+                                    let providers = auth_providers.get_clone();
+                                    if providers.is_empty() {
+                                        // Providers could not be fetched: the
+                                        // generic route redirects to the first
+                                        // configured provider.
+                                        view! {
                                             a(
                                                 class="btn btn-warning btn-lg w-100",
                                                 href="/auth/login",
@@ -472,6 +516,23 @@ pub fn LobbyPage() -> View {
                                                 "Log in"
                                             }
                                         }
+                                    } else {
+                                        view! {
+                                            div(class="d-grid gap-2") {
+                                                (providers.iter().cloned().map(|p| view! {
+                                                    a(
+                                                        class="btn btn-warning btn-lg w-100",
+                                                        href=p.login_url,
+                                                        rel="external",
+                                                    ) {
+                                                        "Log in with " (provider_label(&p.name))
+                                                    }
+                                                }).collect::<Vec<_>>())
+                                            }
+                                        }
+                                    }
+                                })
+                            }
                         }
                     }
                 },
@@ -509,7 +570,7 @@ pub fn LobbyPage() -> View {
                             div(class="lobby-hero text-center") {
                                 h1(class="display-5 fw-bold") { "tavolo" }
                                 p(class="lead text-secondary mb-0") {
-                                    "Play scopone scientifico with friends."
+                                    "Play scopone scientifico and briscola with friends."
                                 }
                             }
                             div(class="row g-4") {

web/src/pages/mod.rs

@@ -1,3 +1,4 @@
+pub mod briscola;
 pub mod game;
 pub mod history;
 pub mod leaderboard;

web/src/ws.rs

@@ -55,8 +55,11 @@ impl GameSocket {
 /// could not be created.
 ///
 /// `on_close` fires exactly once when the connection ends; it receives the
-/// server close code when one was sent (e.g. 4401 unauthenticated, 4403 not
+/// server close code when one was sent (e.g. 1000 for a normal closure) or
-/// seated, 4404 unknown game) or `None` for an abnormal network loss.
+/// `None` for an abnormal loss. A *refused* handshake is not distinguishable
+/// here: browsers report it as an abnormal closure (1006) and never expose
+/// the HTTP status the server answered with, so callers must classify the
+/// failure out of band.
 pub fn connect(
     game_id: &str,
     on_message: impl Fn(ServerMessage) + 'static,
@@ -80,8 +83,14 @@ pub fn connect(
         while let Some(msg) = read.next().await {
             match msg {
                 Ok(Message::Text(text)) => {
-                    if let Ok(parsed) = serde_json::from_str::<ServerMessage>(&text) {
+                    match serde_json::from_str::<ServerMessage>(&text) {
-                        on_message(parsed);
+                        Ok(parsed) => on_message(parsed),
+                        // A silently dropped message would leave the page
+                        // waiting forever; surface the parse error so it is
+                        // visible in the browser console.
+                        Err(err) => web_sys::console::error_1(
+                            &format!("unparseable server message: {err}").into(),
+                        ),
                     }
                 }
                 Ok(Message::Bytes(_)) => {}

web/style.css

@@ -1,4 +1,4 @@
-/* Scopone scientifico frontend — game table, cards and scoring summary.
+/* tavolo frontend — game tables, cards and scoring summaries.
  *
  * The felt palette and the Bootstrap theme overrides live in theme.css,
  * which is loaded before this file. */
@@ -266,6 +266,15 @@ body {
     margin-left: 0.25rem;
 }
 
+.spectator-badge {
+    background: var(--panel-light);
+    color: var(--muted);
+    font-weight: 700;
+    border-radius: 999px;
+    padding: 0.15rem 0.6rem;
+    border: 1px solid var(--muted);
+}
+
 /* ---------- overlays ---------- */
 
 .overlay {
@@ -465,3 +474,69 @@ body {
     font-size: 1.25rem;
     font-weight: 700;
 }
+
+/* ---------- briscola ---------- */
+
+.briscola-badge {
+    background: var(--panel-light);
+    color: var(--accent);
+    font-weight: 700;
+    border-radius: 999px;
+    padding: 0.15rem 0.6rem;
+    border: 1px solid var(--accent);
+}
+
+/* The face-down stock with the face-up trump card beside it. */
+.stock {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+}
+
+.stock-pile {
+    display: flex;
+}
+
+.playing-card.stock-card {
+    height: 48px;
+    margin-left: -34px;
+}
+
+.playing-card.stock-card:first-child {
+    margin-left: 0;
+}
+
+.playing-card.briscola-card {
+    height: 64px;
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+}
+
+.stock-count {
+    color: var(--muted);
+    font-size: 0.8rem;
+    font-variant-numeric: tabular-nums;
+}
+
+/* Current-trick cards with the player's name above each. */
+.trick-slot {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.15rem;
+}
+
+.trick-name {
+    font-size: 0.7rem;
+    color: var(--muted);
+}
+
+/* Two-player table: opponent on top, player at the bottom. */
+.table-grid.duo {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto 1fr auto;
+    grid-template-areas:
+        "top"
+        "center"
+        "bottom";
+}