From c6d22b40613e7a64f76a45663c47395a2d97e6a3 Mon Sep 17 00:00:00 2001
From: rumblefrog <contact@zhenyangli.me>
Date: Sun, 10 May 2026 13:49:52 -0400
Subject: [PATCH] Fix #1312: restore map thumbnail on expanded server cards
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The v2.0.0 redesign at #1123 D1 rebuilt page_servers.tpl from the
handoff card grid and dropped the legacy `<img id="mapimg_{$server.sid}">`
slot. The API handler still returns the `mapimg` URL
(api_servers_host_players → GetMapImage), so the field had no
consumer — every expanded card showed the map name as text only.

Restore the surface by adding a hidden `<img data-testid="server-map-img">`
inside the players panel and wiring the inline initializer to
patch `src` from `r.data.mapimg`. The slot only paints once
`onload` fires; on `error` it stays hidden so missing files (a
fork without `nomap.jpg`, an unknown map without a screenshot)
degrade to "no thumbnail" instead of a broken-image icon.

Regression guards:
  - web/tests/integration/ServerMapImageRenderTest.php pins the
    static contract: handler still emits `mapimg`, template ships
    the `<img>` slot inside the players panel, inline JS wires
    `d.mapimg` + `onload`/`onerror`, GetMapImage falls back to
    `nomap` and the bundled `nomap.jpg` placeholder ships.
  - web/tests/e2e/specs/flows/server-map-thumbnail.spec.ts pins the
    runtime observable across the three terminal paths: bundled
    image loads + becomes visible, missing image keeps the slot
    hidden, server-offline keeps the slot hidden.

Documents the new render path in AGENTS.md's "Where to find what"
table so the surface stays discoverable.
---
 AGENTS.md                                     |   1 +
 .../specs/flows/server-map-thumbnail.spec.ts  | 289 ++++++++++++++++++
 .../integration/ServerMapImageRenderTest.php  | 216 +++++++++++++
 web/themes/default/page_servers.tpl           |  42 ++-
 4 files changed, 547 insertions(+), 1 deletion(-)
 create mode 100644 web/tests/e2e/specs/flows/server-map-thumbnail.spec.ts
 create mode 100644 web/tests/integration/ServerMapImageRenderTest.php

diff --git a/AGENTS.md b/AGENTS.md
index 07ac8f017..fdf3666d3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1259,6 +1259,7 @@ audit (#1207) locked in. New CTAs:
 | Reuse the moderation-queue card layout (admin submissions / protests, mobile-stacked summary rows) | `web/themes/default/css/theme.css` (`.queue-row`, `.queue-row__body`, `.queue-row__date` — #1207 PUB-2). Apply by adding `class="queue-row …"` to the outer `<details>` and dropping the inline `flex` / `flex-shrink:0` styles from the summary children. |
 | Add visible row actions to a table-rendered admin list (Edit / Unmute / Remove buttons + responsive mobile-card mirror) | `web/themes/default/page_comms.tpl` (#1207 ADM-5) is the canonical reference: `<button class="btn btn--secondary btn--sm">` / `<a class="btn btn--ghost btn--sm">` inside a `.row-actions` cell, plus `.ban-card__actions` row of identical-data-action buttons in the mobile card. Wire destructive / state-changing buttons via `data-action="…"` + `data-bid` + `data-fallback-href`; the inline page-tail JS calls `sb.api.call(Actions.PascalName)` and falls back to the GET URL if the JSON dispatcher is absent. |
 | Edit the player-detail drawer (open trigger, tabs, panes, lazy loaders) | `web/themes/default/js/theme.js` (`renderDrawerBody` / `loadPaneIfNeeded`) |
+| Render the per-server map thumbnail in the expanded public server card | `web/themes/default/page_servers.tpl` (`<img data-testid="server-map-img" hidden>` slot inside `[data-testid="server-players-panel"]` + the `applyData` patch that wires `r.data.mapimg` into `src` and toggles `hidden` on `load` / `error`). The URL itself comes from `Sbpp\…` global helper `\GetMapImage()` in `web/includes/system-functions.php` (falls back to `images/maps/nomap.jpg` when the file is missing); the bundled `nomap.jpg` placeholder ships under `web/images/maps/`. The slot must default to `hidden` and stay hidden on the `error` branch — fork installs without `nomap.jpg` would otherwise paint a broken-image icon. Regression guards: `web/tests/integration/ServerMapImageRenderTest.php` (template / handler contract) + `web/tests/e2e/specs/flows/server-map-thumbnail.spec.ts` (runtime visibility under success / 404 / connect-error). #1312 restored this surface after the #1123 D1 redesign dropped the legacy `<img id="mapimg_{$server.sid}">`. |
 | Edit the command palette (icon-only trigger, ⌘K binding, result rows, kbd hints, Ctrl+Enter copy) | `web/themes/default/js/theme.js` (`openPalette` / `closePalette` / `renderPaletteResults` / `applyPlatformHints` / `handlePaletteCopyShortcut`) + `core/title.tpl` (the `.topbar__search` icon button) + the `.palette__row*` rules in `web/themes/default/css/theme.css`. Player rows carry `data-drawer-bid="<bid>"` (bare Enter / click → `loadDrawer`, palette closes itself) + `data-steamid="<steam>"` (`Ctrl/Cmd+Enter` → `navigator.clipboard.writeText` + `showToast`). The kbd glyphs are server-rendered in non-Mac form (`Enter`, `Ctrl`); `applyPlatformHints` swaps `[data-enterkey]` → ⏎ and `[data-modkey]` → ⌘ on Mac/iOS at boot and after every render (#1184, #1207 DET-2). |
 | Add admin-only per-player notes | `web/api/handlers/notes.php` (CRUD) — Notes tab is gated by `bans.detail`'s `notes_visible` flag |
 | Render admin-authored Markdown to safe HTML | `web/includes/Markup/IntroRenderer.php` (`Sbpp\Markup`) |
diff --git a/web/tests/e2e/specs/flows/server-map-thumbnail.spec.ts b/web/tests/e2e/specs/flows/server-map-thumbnail.spec.ts
new file mode 100644
index 000000000..d8e9ac989
--- /dev/null
+++ b/web/tests/e2e/specs/flows/server-map-thumbnail.spec.ts
@@ -0,0 +1,289 @@
+/**
+ * Flow: the expanded public server card paints the map thumbnail
+ * once the SourceQuery response lands (#1312).
+ *
+ * Background: v1.x SourceBans++ rendered an inline
+ * `<img id="mapimg_{$server.sid}">` that JS patched once the per-card
+ * UDP probe responded. The #1123 D1 redesign rebuilt
+ * `page_servers.tpl` from the handoff card grid and dropped the
+ * `<img>` slot — the `mapimg` URL still flowed through the JSON
+ * envelope but had no DOM target. The fix restores the slot
+ * (`<img data-testid="server-map-img" hidden>`) inside the players
+ * panel and wires the inline initializer to:
+ *
+ *   - Patch `src` from `r.data.mapimg`.
+ *   - Unhide the slot on `load` (so the empty `src=""` placeholder
+ *     never paints a broken-image icon during the loading window).
+ *   - KEEP the slot hidden on `error` (so a missing file — e.g. a
+ *     fork that ships without `nomap.jpg` — degrades to "no
+ *     thumbnail" instead of a broken-image icon).
+ *
+ * This spec drives the runtime observable: seed a server row,
+ * intercept the per-card `Actions.ServersHostPlayers` call so the
+ * harness doesn't depend on a live UDP probe, and assert each path
+ * (load → visible, error → still hidden, connect-error → never
+ * rendered) against the `data-testid="server-map-img"` hook.
+ *
+ * The PHPUnit guard at `web/tests/integration/ServerMapImageRenderTest.php`
+ * pins the static contract (the slot ships in the template, the JS
+ * still wires `d.mapimg`); this spec pins the runtime contract.
+ *
+ * No `setTimeout` waits — every assertion anchors on a terminal
+ * attribute or visibility change Playwright auto-waits on, per the
+ * AGENTS.md "Anti-patterns" rule.
+ */
+
+import { expect, test } from '../../fixtures/auth.ts';
+import { truncateE2eDb } from '../../fixtures/db.ts';
+
+interface SeededServer {
+    sid: number;
+    ip: string;
+    port: number;
+}
+
+interface ServerHostPlayersStub {
+    /** Map name surfaced in the data row + alt-text-eligible payload. */
+    map: string;
+    /** Relative URL the inline initializer patches into the slot's `src`. */
+    mapimg: string;
+    /** Force `error: 'connect'` if true (mirrors the offline UDP path). */
+    connectError?: boolean;
+}
+
+/**
+ * Seed one enabled server via `Actions.ServersAdd`. Mirrors
+ * `seedBanViaApi` in `fixtures/seeds.ts`: drives the same PHP
+ * dispatcher (CSRF + permissions + handler) that production traffic
+ * uses, so a future contract drift on `servers.add` is caught here
+ * along with the actual surface under test.
+ *
+ * The seeded IP is in the documentation-only `192.0.2.0/24` block
+ * (RFC 5737) — guarantees the live UDP probe — if anything ever
+ * managed to escape the route mock — would route to nowhere.
+ */
+async function seedServerViaApi(page: import('@playwright/test').Page): Promise<SeededServer> {
+    const ip   = '192.0.2.13';
+    const port = 27015;
+
+    await page.goto('/');
+    const envelope = await page.evaluate(
+        async (args) => {
+            const w = window as unknown as {
+                sb: {
+                    api: {
+                        call: (
+                            action: string,
+                            params: Record<string, unknown>,
+                        ) => Promise<{
+                            ok: boolean;
+                            data?: { sid?: number };
+                            error?: { code: string; message: string };
+                        }>;
+                    };
+                };
+                Actions: Record<string, string>;
+            };
+            return await w.sb.api.call(w.Actions.ServersAdd, {
+                ip:      args.ip,
+                port:    String(args.port),
+                rcon:    '',
+                rcon2:   '',
+                // mid=1 (Half-Life 2 DM) is the first row data.sql seeds
+                // into `:prefix_mods`, so it's always available without
+                // a paired mod insert.
+                mod:     1,
+                enabled: true,
+                group:   '0',
+            });
+        },
+        { ip, port },
+    );
+
+    const env = envelope as { ok: boolean; data?: { sid?: number }; error?: { code: string; message: string } };
+    if (!env.ok || env.data?.sid === undefined) {
+        throw new Error(`seedServerViaApi: servers.add failed (ok=${env.ok}) — ${JSON.stringify(env)}`);
+    }
+    return { sid: env.data.sid, ip, port };
+}
+
+/**
+ * Install a `page.route()` stub that intercepts the per-card
+ * `Actions.ServersHostPlayers` JSON dispatcher call and answers
+ * with a deterministic envelope.
+ *
+ * The dispatcher endpoint is `./api.php` (per `web/scripts/api.js`),
+ * resolved against the page's base URL. Other actions on the page
+ * are not intercepted — the public servers page only fires
+ * `servers.host_players` from its inline initializer, so the body
+ * inspection below safely passes through anything else (the chrome's
+ * version check etc.) untouched.
+ */
+async function stubHostPlayers(
+    page: import('@playwright/test').Page,
+    seeded: SeededServer,
+    stub: ServerHostPlayersStub,
+): Promise<void> {
+    // Match the dispatcher endpoint by the URL's pathname so the
+    // matcher honours absolute, relative, host-included, and host-less
+    // URLs uniformly. The string-glob form (`**\/api.php`) misses some
+    // cross-origin shapes Playwright normalises differently — the
+    // function form is the safe primitive.
+    await page.route((url) => url.pathname.endsWith('/api.php'), async (route) => {
+        const req = route.request();
+        if (req.method() !== 'POST') {
+            await route.continue();
+            return;
+        }
+        let payload: { action?: string; params?: { sid?: number } } = {};
+        try {
+            payload = JSON.parse(req.postData() ?? '{}');
+        } catch {
+            await route.continue();
+            return;
+        }
+        if (payload.action !== 'servers.host_players') {
+            await route.continue();
+            return;
+        }
+
+        // The dispatcher (web/api.php) wraps every successful handler
+        // return in `{ ok: true, data: <handler-return> }` and the page
+        // initializer above guards on `r.ok && r.data`. Match the
+        // envelope shape exactly so the mock looks identical to a
+        // real API response on the wire — the inline script doesn't
+        // know it's talking to a stub.
+        if (stub.connectError) {
+            await route.fulfill({
+                status: 200,
+                contentType: 'application/json',
+                body: JSON.stringify({
+                    ok: true,
+                    data: {
+                        sid:      seeded.sid,
+                        ip:       seeded.ip,
+                        port:     seeded.port,
+                        error:    'connect',
+                        is_owner: false,
+                    },
+                }),
+            });
+            return;
+        }
+
+        await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify({
+                ok: true,
+                data: {
+                    sid:        seeded.sid,
+                    ip:         seeded.ip,
+                    port:       seeded.port,
+                    hostname:   'e2e map-img test server',
+                    players:    1,
+                    maxplayers: 24,
+                    map:        stub.map,
+                    mapfull:    stub.map,
+                    mapimg:     stub.mapimg,
+                    os_class:   'fab fa-linux',
+                    secure:     true,
+                    player_list: [
+                        { id: 0, name: 'tester', frags: 0, time: 0, time_f: '00:00' },
+                    ],
+                    can_ban: false,
+                },
+            }),
+        });
+    });
+}
+
+test.describe('flow: expanded server card map thumbnail (#1312)', () => {
+    test.beforeEach(async () => {
+        await truncateE2eDb();
+    });
+
+    test('paints the thumbnail when the bundled map image exists', async ({ page }) => {
+        const seeded = await seedServerViaApi(page);
+
+        // de_dust2.jpg ships in web/images/maps/ out of the box, so
+        // the browser will resolve the URL to a real 200 + image
+        // payload and the inline initializer's `onload` branch
+        // unhides the slot.
+        await stubHostPlayers(page, seeded, {
+            map:    'de_dust2',
+            mapimg: 'images/maps/de_dust2.jpg',
+        });
+
+        await page.goto(`/index.php?p=servers&s=0`);
+
+        const tile = page.locator('[data-testid="server-tile"]').first();
+        // Anchor on the terminal attribute the inline initializer
+        // sets — Playwright auto-waits, no setTimeout needed.
+        await expect(tile).toHaveAttribute('data-status', 'online');
+        // `?p=servers&s=0` requests auto-expansion of index 0; the
+        // initializer flips `data-expanded` once the response lands.
+        await expect(tile).toHaveAttribute('data-expanded', 'true');
+
+        const mapImg = tile.locator('[data-testid="server-map-img"]');
+        await expect(mapImg).toBeVisible();
+        await expect(mapImg).toHaveAttribute('src', /images\/maps\/de_dust2\.jpg$/);
+    });
+
+    test('keeps the slot hidden when the image fails to load', async ({ page }) => {
+        const seeded = await seedServerViaApi(page);
+
+        // Point at a path that will return 404 (no such file ships).
+        // The inline `onerror` handler must `setAttribute('hidden', '')`
+        // so the slot stays invisible — pre-fix the broken-image
+        // glyph would paint instead.
+        await stubHostPlayers(page, seeded, {
+            map:    'definitely_not_a_real_map',
+            mapimg: 'images/maps/__sbpp_e2e_does_not_exist__.jpg',
+        });
+
+        await page.goto(`/index.php?p=servers&s=0`);
+
+        const tile = page.locator('[data-testid="server-tile"]').first();
+        await expect(tile).toHaveAttribute('data-status', 'online');
+
+        // Slot must be in the DOM (so the `src` patch had a target),
+        // but stay `hidden`. We assert the `hidden` attribute rather
+        // than `not.toBeVisible()` so a future style refactor that
+        // swaps `hidden` for `display: none` would have to update
+        // this assertion deliberately rather than coast through.
+        const mapImg = tile.locator('[data-testid="server-map-img"]');
+        await expect(mapImg).toHaveCount(1);
+        // `hidden` is reflected as a boolean attribute → the value
+        // is the empty string when set. Polling here covers the
+        // window between `onerror` firing and the DOM mutation
+        // landing without a setTimeout.
+        await expect(async () => {
+            const isHidden = await mapImg.evaluate((el) => el.hasAttribute('hidden'));
+            expect(isHidden, 'map-img must stay hidden when the image 404s').toBe(true);
+        }).toPass();
+    });
+
+    test('does not surface the slot when the server is offline', async ({ page }) => {
+        const seeded = await seedServerViaApi(page);
+
+        // Force the connect-error branch in `applyData()`. The whole
+        // map-img wiring sits below the early-return, so the slot
+        // stays in its initial `hidden` state.
+        await stubHostPlayers(page, seeded, {
+            map:          '',
+            mapimg:       '',
+            connectError: true,
+        });
+
+        await page.goto(`/index.php?p=servers&s=0`);
+
+        const tile = page.locator('[data-testid="server-tile"]').first();
+        await expect(tile).toHaveAttribute('data-status', 'offline');
+
+        const mapImg = tile.locator('[data-testid="server-map-img"]');
+        await expect(mapImg).toHaveCount(1);
+        const isHidden = await mapImg.evaluate((el) => el.hasAttribute('hidden'));
+        expect(isHidden, 'offline tiles must keep the map-img slot hidden').toBe(true);
+    });
+});
diff --git a/web/tests/integration/ServerMapImageRenderTest.php b/web/tests/integration/ServerMapImageRenderTest.php
new file mode 100644
index 000000000..6e1c23f2b
--- /dev/null
+++ b/web/tests/integration/ServerMapImageRenderTest.php
@@ -0,0 +1,216 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sbpp\Tests\Integration;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Issue #1312: the public servers list (`?p=servers`) lost the map
+ * thumbnail surface when #1123 D1 rebuilt `page_servers.tpl` from the
+ * handoff card grid. The legacy v1.x card carried an inline
+ * `<img id="mapimg_{$server.sid}">` whose `src` was patched in by JS
+ * once the SourceQuery response landed; the v2.0 redesign kept the
+ * `mapimg` field in the API envelope but dropped the rendering site.
+ *
+ * The fix restores the thumbnail in the EXPANDED panel (so it rides
+ * the same `data-expanded="true"` toggle that surfaces the player
+ * list) with a `hidden`-by-default `<img>` slot the inline initializer
+ * patches from `r.data.mapimg`. `onload` unhides the element; `onerror`
+ * keeps it hidden so missing files never paint a broken-image icon.
+ *
+ * This suite is the hermetic regression guard for that contract:
+ *
+ *   1. The API handler still returns `mapimg` (the contract is
+ *      load-bearing for any future consumer — the legacy admin
+ *      surfaces, the v1.x reference render, plus this template).
+ *   2. The template ships the `<img data-testid="server-map-img">`
+ *      slot inside the players panel.
+ *   3. The inline initializer wires `r.data.mapimg` into the slot's
+ *      `src` and toggles `hidden` on `load` / `error`.
+ *   4. `GetMapImage()` still falls back to `nomap` when the file
+ *      can't be found, and the bundled `nomap.jpg` placeholder still
+ *      ships (so the fallback path renders something instead of a
+ *      404 / broken-image icon).
+ *
+ * The assertions are deliberately string-shape against the template
+ * source rather than a full Smarty render: the regression we're
+ * guarding against is "the slot got removed from the template" /
+ * "the JS got rewired to ignore the field", and a sub-millisecond
+ * `file_get_contents` + `assertStringContainsString` catches both
+ * without booting a stub Smarty or seeding a server row. The E2E
+ * suite covers the runtime observable (the `<img>` actually paints
+ * after the API call lands) — this PHPUnit guard is the contract
+ * gate.
+ */
+final class ServerMapImageRenderTest extends TestCase
+{
+    private string $template;
+    private string $handler;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $tplPath = ROOT . 'themes/default/page_servers.tpl';
+        $hdlPath = ROOT . 'api/handlers/servers.php';
+
+        $tpl = file_get_contents($tplPath);
+        $hdl = file_get_contents($hdlPath);
+        if ($tpl === false || $hdl === false) {
+            self::fail("setUp could not read template or handler ({$tplPath} / {$hdlPath})");
+        }
+        $this->template = $tpl;
+        $this->handler  = $hdl;
+    }
+
+    /**
+     * `api_servers_host_players` must keep returning the `mapimg`
+     * field; the template's `<img>` slot has no value if the handler
+     * stops emitting the URL. Pre-#1312 the field was effectively
+     * dead weight in the response — this test pins that the contract
+     * is now load-bearing on both ends.
+     */
+    public function testHandlerStillEmitsMapimgField(): void
+    {
+        $this->assertStringContainsString(
+            "'mapimg'   => GetMapImage(",
+            $this->handler,
+            "api_servers_host_players must keep emitting `mapimg` so page_servers.tpl's "
+            . "`<img data-testid=\"server-map-img\">` slot can render — see #1312 for the "
+            . "v1.x → v2.0 regression that motivated the surface restore.",
+        );
+    }
+
+    /**
+     * The thumbnail slot itself. Asserts both the testid hook (E2E
+     * specs anchor on this) AND the `hidden` default — the slot
+     * stays invisible until `onload` fires so the empty `<img>`
+     * never paints a broken-image icon between page load and the
+     * SourceQuery round-trip landing.
+     */
+    public function testTemplateShipsMapImgSlot(): void
+    {
+        $this->assertStringContainsString(
+            'data-testid="server-map-img"',
+            $this->template,
+            "page_servers.tpl must ship the `<img data-testid=\"server-map-img\">` slot "
+            . "inside the players panel so the inline initializer has a target to patch "
+            . "from r.data.mapimg (#1312).",
+        );
+
+        // The slot must be `hidden` by default so the empty src=""
+        // doesn't paint a broken-image icon during the loading window.
+        // Match against the literal markup we emit so a future style
+        // refactor doesn't accidentally drop the attribute.
+        $this->assertMatchesRegularExpression(
+            '/<img[^>]*\bdata-testid="server-map-img"[^>]*\bhidden\b/s',
+            $this->template,
+            "The `<img data-testid=\"server-map-img\">` slot must default to `hidden` so "
+            . "the empty `src=\"\"` placeholder never paints a broken-image icon between "
+            . "page load and the SourceQuery response landing (#1312).",
+        );
+    }
+
+    /**
+     * Slot must live inside the `server-players-panel` div so it
+     * rides the same `[hidden]` toggle that surfaces the player list
+     * — the issue's "expanded server card" framing pins this. A
+     * future refactor that pulls the `<img>` outside the panel
+     * (always-visible, even on collapsed cards) would silently
+     * regress the contract.
+     *
+     * Cheap sanity: search for the panel's opening div, then assert
+     * the `<img>` slot appears between that opening tag and the
+     * panel's closing `</div>`. Smarty parses the file linearly so
+     * substring ordering is a faithful proxy for DOM ancestry.
+     */
+    public function testMapImgSlotLivesInsidePlayersPanel(): void
+    {
+        $panelStart = strpos($this->template, 'data-testid="server-players-panel"');
+        $imgStart   = strpos($this->template, 'data-testid="server-map-img"');
+
+        $this->assertNotFalse($panelStart, 'players panel container must exist in the template');
+        $this->assertNotFalse($imgStart,   'map-img slot must exist in the template');
+        $this->assertGreaterThan(
+            $panelStart,
+            $imgStart,
+            "The `<img data-testid=\"server-map-img\">` slot must appear AFTER the "
+            . "`server-players-panel` opening tag so it renders inside the panel that "
+            . "the toggle expands — pulling it outside the panel makes the thumbnail "
+            . "always-visible and changes the affordance the issue restored (#1312).",
+        );
+    }
+
+    /**
+     * The inline initializer must wire `d.mapimg` into the slot's
+     * `src` and the `onload` / `onerror` pair into the `hidden`
+     * toggle — without this wiring the slot stays empty + hidden
+     * forever and the thumbnail never paints.
+     */
+    public function testInlineInitializerWiresMapImg(): void
+    {
+        $this->assertStringContainsString(
+            "tile.querySelector('[data-testid=\"server-map-img\"]')",
+            $this->template,
+            "The inline initializer must locate the `<img>` slot via its testid hook "
+            . "so it can patch the `src` from r.data.mapimg (#1312).",
+        );
+
+        $this->assertStringContainsString(
+            'mapImg.src = String(d.mapimg)',
+            $this->template,
+            "The inline initializer must assign d.mapimg to the slot's `src` — "
+            . "without this assignment the empty `src=\"\"` placeholder never gets "
+            . "the live value the API returns (#1312).",
+        );
+
+        $this->assertMatchesRegularExpression(
+            '/mapImg\.onload\s*=\s*function\s*\([^)]*\)\s*\{[^}]*removeAttribute\([\'\"]hidden[\'\"]\)/s',
+            $this->template,
+            "The inline initializer must unhide the slot on `load` so the thumbnail "
+            . "becomes visible only after the file actually downloads — pre-load the "
+            . "slot stays `hidden` (#1312).",
+        );
+
+        $this->assertMatchesRegularExpression(
+            '/mapImg\.onerror\s*=\s*function\s*\([^)]*\)\s*\{[^}]*setAttribute\([\'\"]hidden[\'\"],\s*[\'\"][\'\"]\)/s',
+            $this->template,
+            "The inline initializer must KEEP the slot hidden on `error` so a missing "
+            . "file (or a missing `nomap.jpg`) never paints a broken-image icon (#1312).",
+        );
+    }
+
+    /**
+     * `GetMapImage()` is the helper the API handler calls to derive
+     * the URL the template will eventually patch in. Its fallback to
+     * `nomap.jpg` is what keeps unknown maps from producing a 404 —
+     * this test pins both halves of the contract: the helper's
+     * behaviour AND the bundled `nomap.jpg` placeholder.
+     */
+    public function testGetMapImageFallsBackToNomap(): void
+    {
+        $url = \GetMapImage('definitely-not-a-real-map-' . uniqid());
+        $this->assertSame(
+            SB_MAP_LOCATION . '/nomap.jpg',
+            $url,
+            "GetMapImage() must return the `nomap.jpg` URL when the requested map's "
+            . "file is missing — without this fallback every server running an "
+            . "unrecognised map would emit a 404 / broken-image icon (#1312).",
+        );
+
+        // Belt-and-suspenders: the bundled `nomap.jpg` placeholder
+        // still needs to exist on disk, otherwise the fallback URL
+        // points at a 404 and the `onerror` branch is the only thing
+        // standing between a missing file and a visible broken-image
+        // icon. Assert the asset ships.
+        $this->assertFileExists(
+            ROOT . SB_MAP_LOCATION . '/nomap.jpg',
+            "web/images/maps/nomap.jpg must ship as the fallback placeholder for "
+            . "`GetMapImage()` — without it the helper returns a URL that 404s and "
+            . "every server running an unrecognised map relies on the JS `onerror` "
+            . "handler as the last line of defense against a broken-image icon (#1312).",
+        );
+    }
+}
diff --git a/web/themes/default/page_servers.tpl b/web/themes/default/page_servers.tpl
index 10423f6a9..ca263c8aa 100644
--- a/web/themes/default/page_servers.tpl
+++ b/web/themes/default/page_servers.tpl
@@ -220,6 +220,27 @@
                  data-testid="server-players-panel"
                  hidden
                  style="border-top:1px solid var(--border);padding:0.75rem 1.25rem">
+                {*
+                    Map preview thumbnail. The legacy v1.x server card carried
+                    an inline `<img id="mapimg_{$server.sid}">` here; the
+                    #1123 D1 redesign dropped it but the API handler still
+                    returns `mapimg` (web/api/handlers/servers.php →
+                    api_servers_host_players → GetMapImage). The inline
+                    initializer below patches `src` from the live response
+                    and unhides the element on `load`; on `error` (file
+                    missing or 404 / nomap.jpg also missing) the element
+                    stays `hidden` so we never paint a broken-image icon.
+                    `alt=""` is intentional: the map name is already
+                    rendered as text in the `[data-testid="server-map"]`
+                    row above, so the image is decorative confirmation
+                    rather than independent content (#1312).
+                *}
+                <img src=""
+                     alt=""
+                     data-testid="server-map-img"
+                     class="server-tile__mapimg"
+                     hidden
+                     style="display:block;width:100%;max-height:140px;object-fit:cover;border-radius:var(--radius-sm);margin-bottom:0.5rem;background:var(--bg-muted)">
                 <p class="text-xs text-muted m-0" data-empty-message>No players currently connected.</p>
                 <ul class="m-0" data-player-list style="list-style:none;padding:0;display:none"></ul>
             </div>
@@ -295,7 +316,7 @@
 
     /**
      * @param {HTMLElement} tile
-     * @param {{hostname?: string, players?: number, maxplayers?: number, map?: string, player_list?: Array<{name: string, frags: number, time_f: string}>, error?: string}} d
+     * @param {{hostname?: string, players?: number, maxplayers?: number, map?: string, mapimg?: string, player_list?: Array<{name: string, frags: number, time_f: string}>, error?: string}} d
      */
     function applyData(tile, d) {
         if (d.error === 'connect') {
@@ -320,6 +341,25 @@
         var mapEl = tile.querySelector('[data-testid="server-map"]');
         if (mapEl) mapEl.textContent = d.map || '';
 
+        // Map preview thumbnail (#1312). The handler returns
+        // `images/maps/<map>.jpg` (or `images/maps/nomap.jpg` if the
+        // file is missing). Show the <img> only after the network
+        // round-trip succeeds — `nomap.jpg` itself can be missing on
+        // forks / bare deployments, so we treat any load error as a
+        // signal to keep the slot hidden rather than painting a
+        // broken-image icon.
+        var mapImg = tile.querySelector('[data-testid="server-map-img"]');
+        if (mapImg instanceof HTMLImageElement) {
+            if (d.mapimg) {
+                mapImg.onload = function () { mapImg.removeAttribute('hidden'); };
+                mapImg.onerror = function () { mapImg.setAttribute('hidden', ''); };
+                mapImg.src = String(d.mapimg);
+            } else {
+                mapImg.setAttribute('hidden', '');
+                mapImg.removeAttribute('src');
+            }
+        }
+
         var players = Number(d.players || 0);
         var maxp = Number(d.maxplayers || 0);
         var pl = tile.querySelector('[data-testid="server-players"]');