Move tavolo-app under packages/ for a uniform monorepo layout

Relocate the composition root (app, config, static, logging_config,
aerich_config) from server/src/tavolo/ to
packages/tavolo-app/src/tavolo/, with its own pyproject.toml and README
like the sibling distributions. Module paths and the granian entrypoint
are unchanged.

server/pyproject.toml remains as a tooling shim ([tool.aerich] next to
./migrations, [tool.mypy] for runs from server/); the Dockerfile installs
all three distributions from ./packages. Verified: all suites green,
mypy clean per package, aerich resolves the moved config identically,
wheel builds.

server/packages/tavolo-app/README.md

@@ -0,0 +1,31 @@
+# tavolo-app
+
+The deployable tavolo application: the composition root wiring
+[`tavolo-platform`](../tavolo-platform/README.md) to the
+[`tavolo-scopone`](../tavolo-scopone/README.md) game.
+
+## 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
+  `tavolo.app:app` for granian.
+- `config.py` — environment-driven frozen `Settings`.
+- `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`).
+- `logging_config.py` — logging setup.
+- `static.py` — SPA shell hosting for the compiled frontend.
+
+## Development (from `packages/tavolo-app/`)
+
+```sh
+.venv/bin/python -m mypy --namespace-packages --explicit-package-bases \
+  src/tavolo/app.py \
+  src/tavolo/config.py \
+  src/tavolo/static.py \
+  src/tavolo/aerich_config.py \
+  src/tavolo/logging_config.py
+```
+
+End-to-end coverage of the wired stack lives in `server/tests/`.

server/packages/tavolo-app/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tavolo-app"
+version = "0.1.0"
+description = "Tavolo multiplayer card-game application: platform + scopone game wiring"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "tavolo-platform",
+    "tavolo-scopone",
+    "kaya-core",
+    "kaya-cors",
+    "kaya-session",
+    "kaya-session-redis",
+    "kaya-oidc",
+    "kaya-openapi",
+    "kaya-rsgi",
+    "granian>=2.0",
+    "asyncpg",
+    "aerich",
+    "httpx",
+    "PyJWT[crypto]",
+    "pwo",
+    "PyYAML",
+    "redis",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy",
+    "httpx-ws",
+]
+otel = [
+    "kaya-otel>=0.0.4",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+plugins = []

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

@@ -0,0 +1,23 @@
+"""Tortoise ORM configuration consumed by the aerich CLI.
+
+Kept separate from :mod:`tavolo.app` so ``aerich`` can import it without
+assembling the whole application (mixins, routes). The database URL comes
+from the same :class:`~tavolo.config.Settings` the app uses, so the CLI
+and the app always point at the same database.
+
+``aerich.models`` is required alongside the app models: it provides the
+table aerich uses to track applied migrations.
+"""
+from __future__ import annotations
+
+from .config import settings
+
+TORTOISE_ORM = {
+    "connections": {"default": settings.database_url},
+    "apps": {
+        "models": {
+            "models": ["tavolo.platform.models", "aerich.models"],
+            "default_connection": "default",
+        }
+    },
+}

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

@@ -0,0 +1,206 @@
+"""Application entry point.
+
+Assembles the :class:`~kaya.core.KayaApp` with the kaya mixins plus the
+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:`~tavolo.platform.tortoise_mixin.TortoiseMixin` (Postgres match
+  statistics; skipped for ``/api/health`` and the OpenAPI documentation
+  endpoints)
+- :class:`~kaya.openapi.OpenAPIMixin` (serves the OpenAPI document at
+  ``/api/openapi.json`` and a Swagger UI at ``/api/docs``)
+- :class:`~tavolo.platform.mixin.PlatformMixin` (game lobby, match
+  history, leaderboards and the live-play websocket, served by the
+  registered game engines)
+- :class:`~tavolo.platform.deadlines.DeadlineSchedulerMixin` (fires the
+  engines' timeouts)
+
+A :class:`~kaya.cors.CorsMixin` is prepended when CORS is configured via the
+``CORS_*`` environment variables (see :mod:`tavolo.config`). A
+:class:`~kaya.otel.OTelMixin` (optional ``otel`` extra) is prepended when
+``OTEL_ENABLED`` is set, adding OpenTelemetry traces and metrics.
+
+Live games are kept in :data:`game_store` (Redis when configured,
+in-memory otherwise). The SPA shell routes are registered at the bottom;
+imports must happen after ``app`` is built.
+"""
+from __future__ import annotations
+
+from importlib.metadata import version as _pkg_version
+from logging import getLogger
+from typing import Optional
+
+from kaya.core import KayaApp, KayaMixin
+from kaya.cors import CorsMixin
+from kaya.oidc import OIDCConfig, OIDCMixin
+from kaya.openapi import OpenAPIMixin
+from kaya.session import InMemorySessionStore, SessionMixin, SessionStore
+from kaya.session.redis import RedisSessionStore
+from redis.asyncio import Redis
+from tavolo.platform import GameRegistry, Platform, PlatformMixin
+from tavolo.platform.deadlines import DeadlineScheduler, DeadlineSchedulerMixin
+from tavolo.platform.store import GameStore, InMemoryGameStore, RedisGameStore
+from tavolo.platform.tortoise_mixin import TortoiseMixin
+from tavolo.scopone import ScoponeEngine
+
+from .config import Settings, settings
+from .logging_config import configure_logging
+
+configure_logging(settings.logging_config)
+log = getLogger(__name__)
+
+
+def cors_mixin_from_settings(settings: Settings) -> Optional[CorsMixin]:
+    """Build a :class:`~kaya.cors.CorsMixin` from the CORS settings.
+
+    Returns ``None`` — CORS disabled — unless at least one of
+    ``CORS_ALLOW_ORIGINS`` / ``CORS_ALLOW_ORIGIN_REGEX`` is configured.
+    Settings left unset fall back to the mixin's own defaults.
+    """
+    if settings.cors_allow_origins is None and settings.cors_allow_origin_regex is None:
+        return None
+    return CorsMixin(
+        allow_origins=settings.cors_allow_origins or (),
+        allow_origin_regex=settings.cors_allow_origin_regex,
+        allow_methods=settings.cors_allow_methods or ("GET",),
+        allow_headers=settings.cors_allow_headers or (),
+        allow_credentials=settings.cors_allow_credentials,
+        expose_headers=settings.cors_expose_headers or (),
+        max_age=settings.cors_max_age,
+    )
+
+
+def otel_mixin_from_settings(settings: Settings) -> 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.
+    """
+    if not settings.otel_enabled:
+        return None
+    try:
+        from kaya.otel import OTelMixin
+    except ImportError as exc:
+        raise RuntimeError(
+            "OTEL_ENABLED is set but kaya-otel is not installed; "
+            "install tavolo-app with the 'otel' extra"
+        ) from exc
+    headers = dict(
+        pair.split("=", 1)
+        for pair in (settings.otel_exporter_headers or ())
+        if "=" in pair
+    )
+    return OTelMixin(
+        service_name=settings.otel_service_name,
+        endpoint=settings.otel_exporter_endpoint,
+        headers=headers or None,
+        excluded_paths=settings.otel_excluded_paths,
+    )
+
+
+registry = GameRegistry()
+registry.register(
+    ScoponeEngine(
+        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",
+    settings.hand_ack_timeout_seconds,
+    settings.turn_timeout_seconds,
+)
+
+session_store: SessionStore
+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))
+    game_store = RedisGameStore(
+        Redis.from_url(settings.redis_url, decode_responses=False),
+        registry,
+        ttl_seconds=settings.game_ttl_seconds,
+    )
+    log.info("using Redis stores (sessions + live games, game TTL %ds)", settings.game_ttl_seconds)
+else:
+    session_store = InMemorySessionStore()
+    game_store = InMemoryGameStore(registry)
+    log.info("REDIS_URL unset: using in-memory stores (sessions + live games)")
+
+session_mixin = SessionMixin(session_store)
+oidc_mixin = OIDCMixin(
+    OIDCConfig(
+        issuer=settings.oidc_issuer,
+        client_id=settings.oidc_client_id,
+        client_secret=settings.oidc_client_secret,
+        redirect_uri=settings.oidc_redirect_uri,
+        post_login_redirect=settings.oidc_post_login_redirect,
+        post_logout_redirect=settings.oidc_post_logout_redirect,
+        fetch_userinfo=True,
+    ),
+    session=session_mixin,
+)
+openapi_mixin = OpenAPIMixin(
+    title="tavolo",
+    version=_pkg_version("tavolo-app"),
+    description="Multiplayer card-game platform API",
+    spec_path="/api/openapi.json",
+    docs_path="/api/docs",
+)
+tortoise_mixin = TortoiseMixin(
+    database_url=settings.database_url,
+    models_modules=["tavolo.platform.models"],
+    skip_paths=frozenset({"/api/health", "/api/docs", "/api/openapi.json"}),
+)
+scheduler = DeadlineScheduler(
+    game_store,
+    registry,
+    heartbeat_ms=settings.deadline_heartbeat_ms,
+)
+platform = Platform(
+    registry=registry,
+    game_store=game_store,
+    scheduler=scheduler,
+    oidc=oidc_mixin,
+)
+
+mixins: list[KayaMixin] = [session_mixin, oidc_mixin, tortoise_mixin, openapi_mixin,
+                           PlatformMixin(platform), DeadlineSchedulerMixin(scheduler)]
+otel_mixin = otel_mixin_from_settings(settings)
+if otel_mixin is not None:
+    # First in the list: 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.
+    mixins.insert(0, otel_mixin)
+    log.info(
+        "OpenTelemetry enabled: service=%s endpoint=%s",
+        settings.otel_service_name,
+        settings.otel_exporter_endpoint or "(OTLP default)",
+    )
+
+cors_mixin = cors_mixin_from_settings(settings)
+if cors_mixin is not None:
+    # First in the list: preflight requests are answered before the session
+    # and OIDC hooks run.
+    mixins.insert(0, cors_mixin)
+    log.info(
+        "CORS enabled: origins=%s origin_regex=%s credentials=%s",
+        settings.cors_allow_origins,
+        settings.cors_allow_origin_regex,
+        settings.cors_allow_credentials,
+    )
+
+app = KayaApp(mixins=mixins)
+
+# Register the SPA shell. The catch-all only matches paths no other route
+# claimed (asset files under /static are served by Granian itself and never
+# reach the app).
+from . import static  # noqa: E402,F401

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

@@ -0,0 +1,185 @@
+"""Environment-driven configuration for the tavolo application.
+
+Mirrors kaya's own pattern: read ``os.environ`` directly into a plain
+dataclass. No pydantic-settings, no settings module.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional, Tuple
+from urllib.parse import quote
+
+
+def _env(name: str, default: Optional[str] = None) -> str:
+    value = os.environ.get(name)
+    if value is None or value == "":
+        if default is None:
+            raise RuntimeError(f"Missing required environment variable: {name}")
+        return default
+    return value
+
+
+def _env_list(name: str) -> Optional[Tuple[str, ...]]:
+    """Parse a comma-separated environment variable into a tuple of values.
+
+    Items are stripped and empty items dropped. Unset or empty variables
+    yield ``None``.
+    """
+    value = os.environ.get(name)
+    if value is None or value.strip() == "":
+        return None
+    return tuple(part.strip() for part in value.split(",") if part.strip())
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.environ.get(name)
+    if value is None or value == "":
+        return default
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _database_url_from_parts(engine: str,
+                             user: str,
+                             password: Optional[str],
+                             host: str,
+                             port: str,
+                             name: str,
+                             options: str) -> str:
+    """Assemble a database DSN from individual components.
+
+    ``user`` and ``password`` are percent-encoded so credentials containing
+    URL-reserved characters (``@``, ``:``, ``/``, ...) do not corrupt the
+    DSN. ``port`` and ``options`` are omitted when empty: a missing port
+    lets the driver pick its default (5432 for asyncpg). ``options`` is a
+    raw query string (e.g. ``ssl=require``) appended after a ``?``.
+    """
+    netloc = quote(user, safe="")
+    if password:
+        netloc += ":" + quote(password, safe="")
+    netloc += "@" + host
+    if port:
+        netloc += ":" + port
+    url = f"{engine}://{netloc}/{name}"
+    options = options.lstrip("?")
+    if options:
+        url += "?" + options
+    return url
+
+
+@dataclass(frozen=True)
+class Settings:
+    database_url: str
+    oidc_issuer: str
+    oidc_client_id: str
+    oidc_client_secret: Optional[str]
+    oidc_redirect_uri: str
+    # 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]
+    # How long a live game (and its join-code index) survives in Redis
+    # without activity, in seconds. Defaults to 24h.
+    game_ttl_seconds: int
+    # Directory holding the compiled frontend (trunk's dist output). Only
+    # used to locate index.html for the SPA shell; the assets themselves
+    # 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;
+    # 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).
+    turn_timeout_seconds: int
+    # Upper bound on how long the deadline consumer sleeps between polls.
+    # Locally enqueued deadlines wake the consumer immediately; the
+    # heartbeat only bounds the discovery delay for deadlines enqueued by
+    # other workers.
+    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.
+    logging_config: Optional[str]
+    # CORS (kaya-cors' CorsMixin). Disabled unless CORS_ALLOW_ORIGINS or
+    # CORS_ALLOW_ORIGIN_REGEX is set; the app serves the SPA and the API
+    # from the same origin, so no CORS headers are needed by default.
+    cors_allow_origins: Optional[Tuple[str, ...]]
+    cors_allow_origin_regex: Optional[str]
+    cors_allow_methods: Optional[Tuple[str, ...]]
+    cors_allow_headers: Optional[Tuple[str, ...]]
+    cors_allow_credentials: bool
+    cors_expose_headers: Optional[Tuple[str, ...]]
+    cors_max_age: int
+    # OpenTelemetry (kaya-otel's OTelMixin). Disabled unless OTEL_ENABLED is
+    # truthy; the exporter endpoint falls back to the OTLP/HTTP default
+    # (localhost:4318) when OTEL_EXPORTER_OTLP_ENDPOINT is unset.
+    otel_enabled: bool
+    otel_service_name: str
+    otel_exporter_endpoint: Optional[str]
+    otel_exporter_headers: Optional[Tuple[str, ...]]
+    # Paths excluded from tracing and metrics (exact matches). Defaults to
+    # the health endpoint, which k8s probes would otherwise spam.
+    otel_excluded_paths: Tuple[str, ...]
+
+    @staticmethod
+    def from_env() -> "Settings":
+        return Settings(
+            # DATABASE_URL, when set, is used verbatim and the DATABASE_*
+            # parts below are ignored (sqlite in tests, managed-DB DSNs).
+            database_url=os.environ.get("DATABASE_URL") or _database_url_from_parts(
+                engine=_env("DATABASE_ENGINE", "postgres"),
+                user=_env("DATABASE_USER", "tavolo"),
+                password=_env("DATABASE_PASSWORD", "password"),
+                host=_env("DATABASE_HOST", "localhost"),
+                # Unset: the port segment is omitted and the driver default
+                # (5432 for asyncpg) applies.
+                port=os.environ.get("DATABASE_PORT", ""),
+                name=_env("DATABASE_NAME", "tavolo"),
+                # 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_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
+            # stores (tests, ephemeral dev). Set to e.g.
+            # redis://localhost:6379/0 to persist both in Redis.
+            redis_url=os.environ.get("REDIS_URL"),
+            game_ttl_seconds=int(_env("GAME_TTL_SECONDS", "86400")),
+            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")),
+            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
+            # is set.
+            cors_allow_origins=_env_list("CORS_ALLOW_ORIGINS"),
+            cors_allow_origin_regex=os.environ.get("CORS_ALLOW_ORIGIN_REGEX") or None,
+            cors_allow_methods=_env_list("CORS_ALLOW_METHODS"),
+            cors_allow_headers=_env_list("CORS_ALLOW_HEADERS"),
+            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
+            # and metrics 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",),
+        )
+
+
+settings: Settings = Settings.from_env()

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

@@ -0,0 +1,74 @@
+"""Logging setup for the tavolo application.
+
+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}``.
+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.::
+
+    version: 1
+    disable_existing_loggers: false
+    formatters:
+      default:
+        format: "{asctime} [{levelname}] ({processName:s}/{threadName:s}) - {name} - {message}"
+        style: "{"
+    handlers:
+      console:
+        class: logging.StreamHandler
+        formatter: default
+    root:
+      level: WARNING
+      handlers: [console]
+    loggers:
+      tavolo:
+        level: INFO
+
+``disable_existing_loggers`` should stay ``false``: Granian configures its
+own loggers before importing the application, and disabling them would
+silence the server and Tortoise.
+"""
+from __future__ import annotations
+
+from logging.config import dictConfig
+from typing import Optional
+
+import yaml
+
+DEFAULT_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {
+            "format": "{asctime} [{levelname}] ({processName:s}/{threadName:s}) - {name} - {message}",
+            "style": "{",
+        },
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "default",
+            "level": "DEBUG",
+        },
+    },
+    "root": {
+        "level": "DEBUG",
+        "handlers": ["console"],
+    },
+}
+
+
+def configure_logging(config_path: Optional[str]) -> None:
+    """Apply the YAML logging configuration at ``config_path``, or the
+    built-in default when unset."""
+    if config_path is None:
+        dictConfig(DEFAULT_CONFIG)
+        return
+    try:
+        with open(config_path, "rb") as handle:
+            config = yaml.safe_load(handle)
+    except OSError as exc:
+        raise RuntimeError(f"Cannot read LOGGING_CONFIG file: {config_path}") from exc
+    if not isinstance(config, dict):
+        raise RuntimeError(f"LOGGING_CONFIG file is not a YAML mapping: {config_path}")
+    dictConfig(config)

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

@@ -0,0 +1,46 @@
+"""SPA shell hosting for the compiled single-page application.
+
+Static assets (wasm, js, css, card images) are served by Granian itself
+under the ``/static`` prefix (``GRANIAN_STATIC_PATH_*`` env vars; see the
+Dockerfile) and never reach Python. This module only serves ``index.html``
+from ``STATIC_DIR``: at the site root and — via the glob catch-all — for
+every path no API or auth route claimed, so client-side routes
+(``/game/<id>`` etc.) work on direct loads and refreshes.
+
+kaya-openapi deliberately skips glob routes, so this handler never appears
+in the API specification.
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from kaya.core import HttpContext
+
+from .app import app
+from .config import settings
+
+
+async def _send_shell(ctx: HttpContext) -> None:
+    """Serve the SPA shell, or 404 when the frontend build is missing."""
+    index = Path(settings.static_dir) / "index.html"
+    if not index.is_file():
+        await ctx.send_empty(404)
+        return
+    body = await asyncio.to_thread(index.read_bytes)
+    await ctx.send_bytes(200, body, {"content-type": ("text/html; charset=utf-8",)})
+
+
+@app.GET("/")
+async def index(ctx: HttpContext) -> None:
+    """Serve the SPA shell at the site root (the glob below cannot match
+    an empty path)."""
+    await _send_shell(ctx)
+
+
+@app.GET("/*", recursive=True)
+async def spa(ctx: HttpContext, _matched: object = None) -> None:
+    """SPA fallback: any path that matched no other route renders the app
+    shell. Requests under ``/static`` are answered by Granian before the
+    app is ever called, so they never arrive here."""
+    await _send_shell(ctx)