From e5e18dae62d2eee37ce8c10542db9b2558b822fc Mon Sep 17 00:00:00 2001
From: Harry Cordewener <admin@twilightdays.org>
Date: Sat, 15 Aug 2026 01:21:19 -0500
Subject: [PATCH 1/2] A badge that would rather say nothing than say nought
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

§8.5's owner-published outputs: /g/{slug}/badge.svg and /g/{slug}/badge.json,
public and CORS-open because the whole point is a page we do not control.

This is the surface with the least room and the most exposure, and none of the
rules bend for it.

The count carries its own age. "15" on somebody's front page is the incumbents'
badge; "15 now · 4m ago" is ours, in nine more characters. That needed
GameSummary to know WHEN the count was measured, which it did not — §10.1 names
that gap as the one place this project contradicts itself, and PlayersNowAt
closes it for the field a third party is most likely to republish. A count with
no age reads as unknown rather than as a bare figure.

An unknown count is never a zero. A game whose WHO we cannot parse renders
"players unknown" in grey; a measured zero renders "0 now" in the accent,
because we got in and nobody was there and that is a real fact. The first would
be our parser's limit printed as a fact about their game, on their own website,
where we could not correct it — rule 4 where it does the most damage.

An archived game says archived rather than showing the last number it had. The
state is decided before the count, so a game that stopped answering in 2023
cannot wear a live-sounding figure.

The accent means measured everywhere on this site and is spent nowhere else, so
an unknown badge is grey.

A game's name is MSSP text and therefore attacker-controlled. It reaches the
accessible title and nowhere else, escaped: an SVG is a document, and a game
named </text><script> would otherwise be a stored injection with a distribution
mechanism. No external font, no remote reference, nothing fetched.

Caching: strong ETag over the exact bytes and If-None-Match through the same
ApiResponse the rest of §10 uses, with max-age=300 — long enough that a popular
front page does not turn its readers into our traffic, and well inside the two
hours after which a count is stale, so a cache entry cannot outlive the
freshness of what it holds. A former slug redirects permanently, which matters
more here than anywhere: a badge is pasted into a template once and left for
years.

Found while testing: the resolver returned a bare null for both "no such game"
and "redirected", so the caller wrote a 404 over the 301 and the forever-redirect
worked on neither route. Two outcomes, two values.

842 tests over five suites, Postgres exercised. 12 new, all of them about what
the badge declines to claim.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../Persistence/NpgsqlGameQueries.cs          |  25 +-
 src/MUI.Catalog/Views.cs                      |  14 +-
 src/MUI.Web/Api/BadgeEndpoints.cs             | 175 ++++++++++++
 src/MUI.Web/Api/MuiApi.cs                     |   5 +
 src/MUI.Web/Api/PlayerBadge.cs                | 238 ++++++++++++++++
 src/MUI.Web/Components/Pages/Account.razor    |  18 ++
 src/MUI.Web/Fixtures/FixtureGameQueries.cs    |  10 +-
 src/MUI.Web/wwwroot/app.css                   |  17 ++
 tests/MUI.Web.Tests/Api/BadgeApiTests.cs      | 260 ++++++++++++++++++
 9 files changed, 748 insertions(+), 14 deletions(-)
 create mode 100644 src/MUI.Web/Api/BadgeEndpoints.cs
 create mode 100644 src/MUI.Web/Api/PlayerBadge.cs
 create mode 100644 tests/MUI.Web.Tests/Api/BadgeApiTests.cs

diff --git a/src/MUI.Catalog/Persistence/NpgsqlGameQueries.cs b/src/MUI.Catalog/Persistence/NpgsqlGameQueries.cs
index 59a1ab93..2445ec1d 100644
--- a/src/MUI.Catalog/Persistence/NpgsqlGameQueries.cs
+++ b/src/MUI.Catalog/Persistence/NpgsqlGameQueries.cs
@@ -157,7 +157,8 @@ ORDER BY g.name
                 digest.CountNow,
                 Winner(forGame, "CODEBASE")?.Value,
                 MeasuredProtocolsOf(forGame),
-                row.LastReachableAt);
+                row.LastReachableAt,
+                digest.CountAt);
 
             facetRows.Add(new GameFacetRow(
                 summary,
@@ -258,7 +259,9 @@ FROM game
             row.IsClaimed,
             digest.CountNow,
             Winner(fields, "CODEBASE")?.Value,
-            MeasuredProtocolsOf(fields));
+            MeasuredProtocolsOf(fields),
+            row.LastReachableAt,
+            digest.CountAt);
     }
 
     public async Task<GamePage?> FindAsync(string slug, CancellationToken cancellationToken = default)
@@ -303,7 +306,8 @@ FROM game
             digest.CountNow,
             Winner(fields, "CODEBASE")?.Value,
             MeasuredProtocolsOf(fields),
-            row.LastReachableAt);
+            row.LastReachableAt,
+            digest.CountAt);
 
         return new GamePage(
             summary,
@@ -778,10 +782,11 @@ private async Task<Dictionary<Guid, PresenceDigest>> PresenceDigestAsync(
 
         var rows = await connection.QueryAsync<DigestRow>(new CommandDefinition(
             """
-            SELECT g.id AS GameId, recent.count AS CountNow, coalesce(week.n, 0) AS NonZeroThisWeek
+            SELECT g.id AS GameId, recent.count AS CountNow, recent.at AS CountAt,
+                   coalesce(week.n, 0) AS NonZeroThisWeek
               FROM unnest(@ids::uuid[]) AS g(id)
               LEFT JOIN LATERAL (
-                   SELECT p.count
+                   SELECT p.count, p.at
                      FROM presence_sample p
                     WHERE p.game_id = g.id AND p.at >= @nowFrom AND p.count IS NOT NULL
                     ORDER BY p.at DESC
@@ -799,7 +804,9 @@ FROM presence_sample p
             },
             cancellationToken: cancellationToken));
 
-        return rows.ToDictionary(r => r.GameId, r => new PresenceDigest(r.CountNow, r.NonZeroThisWeek > 0));
+        return rows.ToDictionary(
+            r => r.GameId,
+            r => new PresenceDigest(r.CountNow, r.CountAt, r.NonZeroThisWeek > 0));
     }
 
     /// <summary>
@@ -879,9 +886,9 @@ private static ActivityBand BandOf(
             : ActivityBand.Dark;
     }
 
-    private sealed record PresenceDigest(int? CountNow, bool NonZeroThisWeek)
+    private sealed record PresenceDigest(int? CountNow, DateTimeOffset? CountAt, bool NonZeroThisWeek)
     {
-        public static readonly PresenceDigest None = new(null, false);
+        public static readonly PresenceDigest None = new(null, null, false);
     }
 
     private sealed class GameRow
@@ -922,6 +929,8 @@ private sealed class DigestRow
 
         public int? CountNow { get; init; }
 
+        public DateTimeOffset? CountAt { get; init; }
+
         public long NonZeroThisWeek { get; init; }
     }
 
diff --git a/src/MUI.Catalog/Views.cs b/src/MUI.Catalog/Views.cs
index a1c26218..663f09e6 100644
--- a/src/MUI.Catalog/Views.cs
+++ b/src/MUI.Catalog/Views.cs
@@ -79,10 +79,21 @@ public sealed record ActivityCell(int DayOfWeek, int Hour, int? Count, bool Prob
 
 /// <summary>A game as the listing shows it.</summary>
 /// <remarks>
+/// <para>
 /// <see cref="LastReachableAt"/> is carried because the last-seen facet (spec §9) filters on it, and
 /// a facet whose value cannot be read off the rows it returned is one a reader has to take on trust.
 /// Null means we have never once reached the game, which is a different fact from "reachable a long
 /// time ago" and is never rendered as the older of the two.
+/// </para>
+/// <para>
+/// <see cref="PlayersNowAt"/> is when the count in <see cref="PlayersNow"/> was measured, and it is
+/// here because §10.1 names its absence as the one place this project contradicts itself: a summary
+/// that carries a number and no age publishes a measurement as a bare value, which is the confusion
+/// the incumbents' directories run on. It is not the whole of §10.1's fix — the codebase still has
+/// no chip — but the count is the field a surface is most likely to republish on its own, and the
+/// owner badge (§8.5) is exactly that surface. Null whenever <see cref="PlayersNow"/> is null, and
+/// the two are never read apart.
+/// </para>
 /// </remarks>
 public sealed record GameSummary(
     Guid Id,
@@ -94,7 +105,8 @@ public sealed record GameSummary(
     int? PlayersNow,
     string? Codebase,
     IReadOnlyList<string> MeasuredProtocols,
-    DateTimeOffset? LastReachableAt = null);
+    DateTimeOffset? LastReachableAt = null,
+    DateTimeOffset? PlayersNowAt = null);
 
 /// <summary>A game as its own page shows it.</summary>
 /// <remarks>
diff --git a/src/MUI.Web/Api/BadgeEndpoints.cs b/src/MUI.Web/Api/BadgeEndpoints.cs
new file mode 100644
index 00000000..9ecd8677
--- /dev/null
+++ b/src/MUI.Web/Api/BadgeEndpoints.cs
@@ -0,0 +1,175 @@
+using MUI.Catalog;
+
+using Microsoft.Net.Http.Headers;
+
+namespace MUI.Web.Api;
+
+/// <summary>
+/// Spec §8.5's owner-published outputs: a live player-count badge, and JSON for the game's own site.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Public, not owner-gated.</b> These are meant to be embedded on a page we do not control, by an
+/// operator who does not want to proxy them, so they answer anybody — and they publish nothing the
+/// game's own page does not already show. What a claim grants is the <em>reason</em> to want them,
+/// not permission to fetch them.
+/// </para>
+/// <para>
+/// Both go through <see cref="ApiResponse"/>, so both get a strong ETag over the exact bytes,
+/// <c>If-None-Match</c> handling, <c>nosniff</c> and the open CORS header the rest of §10 has. The
+/// one thing they override is the cache window: a badge is refetched by every reader of somebody's
+/// front page, and a minute is too little.
+/// </para>
+/// </remarks>
+public static class BadgeEndpoints
+{
+    public static void Map(IEndpointRouteBuilder app)
+    {
+        ArgumentNullException.ThrowIfNull(app);
+
+        app.MapGet("/g/{slug}/badge.svg", SvgAsync);
+        app.MapGet("/g/{slug}/badge.json", JsonAsync);
+    }
+
+    /// <summary>The badge, as an image.</summary>
+    public static async Task SvgAsync(
+        HttpContext http,
+        string slug,
+        IGameQueries queries,
+        ISlugHistory slugs,
+        TimeProvider clock)
+    {
+        var (game, redirected) = await ResolveAsync(http, slug, queries, slugs, ".svg");
+
+        if (redirected)
+        {
+            return;
+        }
+
+        if (game is null)
+        {
+            // A badge rather than an empty 404, because whoever sees this is the operator who just
+            // pasted the wrong URL onto their own site, and a broken-image icon says nothing.
+            http.Response.StatusCode = StatusCodes.Status404NotFound;
+            http.Response.ContentType = "image/svg+xml; charset=utf-8";
+            http.Response.Headers[HeaderNames.CacheControl] = "no-store";
+            await http.Response.WriteAsync(PlayerBadge.UnknownSvg(), http.RequestAborted);
+            return;
+        }
+
+        var reading = PlayerBadge.Read(game, clock.GetUtcNow());
+        var body = System.Text.Encoding.UTF8.GetBytes(PlayerBadge.Svg(reading, game.Name));
+
+        ApiResponse.Prepare(http, "image/svg+xml; charset=utf-8", ETag.Of(body));
+        http.Response.Headers[HeaderNames.CacheControl] = PlayerBadge.CacheControl;
+
+        if (ApiResponse.NotModified(http, ETag.Of(body)))
+        {
+            return;
+        }
+
+        http.Response.ContentLength = body.Length;
+        await http.Response.Body.WriteAsync(body, http.RequestAborted);
+    }
+
+    /// <summary>The same reading, for a page that would rather draw its own.</summary>
+    public static async Task JsonAsync(
+        HttpContext http,
+        string slug,
+        IGameQueries queries,
+        ISlugHistory slugs,
+        TimeProvider clock)
+    {
+        var (game, redirected) = await ResolveAsync(http, slug, queries, slugs, ".json");
+
+        if (redirected)
+        {
+            return;
+        }
+
+        if (game is null)
+        {
+            await ApiResponse.ProblemAsync(
+                http,
+                StatusCodes.Status404NotFound,
+                "No such game",
+                $"Nothing in the catalogue answers to '{slug}'.");
+            return;
+        }
+
+        var reading = PlayerBadge.Read(game, clock.GetUtcNow());
+
+        await ApiResponse.WriteJsonAsync(http, new BadgeView(
+            game.Slug,
+            game.Name,
+            game.State,
+            reading.Count,
+            reading.Word,
+            reading.Description,
+            reading.Age?.TotalSeconds,
+            game.PlayersNowAt,
+            game.LastReachableAt,
+            ApiRoutes.Page(game.Slug),
+            $"{ApiRoutes.Page(game.Slug)}/badge.svg"));
+
+        http.Response.Headers[HeaderNames.CacheControl] = PlayerBadge.CacheControl;
+    }
+
+    /// <summary>
+    /// The game a slug names, redirecting from one it used to have (spec §5.7).
+    /// </summary>
+    /// <remarks>
+    /// A badge is the single most likely thing on this site to outlive the URL it was copied from:
+    /// it is pasted into somebody's template once and left for years, and §5.7's forever-redirect is
+    /// the promise that makes that safe.
+    ///
+    /// The second half of the answer is not a nicety: this returned a bare null for both "no such
+    /// game" and "redirected", so the caller wrote a 404 over the 301 it had just set and the
+    /// forever-redirect worked for no route on this pair. Two outcomes, two values.
+    /// </remarks>
+    private static async Task<(GameSummary? Game, bool Redirected)> ResolveAsync(
+        HttpContext http,
+        string slug,
+        IGameQueries queries,
+        ISlugHistory slugs,
+        string suffix)
+    {
+        if (await queries.FindAsync(slug, http.RequestAborted) is { } page)
+        {
+            return (page.Summary, false);
+        }
+
+        if (await slugs.CurrentSlugAsync(slug, http.RequestAborted) is { } current
+            && await queries.FindAsync(current, http.RequestAborted) is not null)
+        {
+            http.Response.StatusCode = StatusCodes.Status301MovedPermanently;
+            http.Response.Headers[HeaderNames.Location] = $"{ApiRoutes.Page(current)}/badge{suffix}";
+            http.Response.Headers[HeaderNames.CacheControl] = PlayerBadge.CacheControl;
+            return (null, true);
+        }
+
+        return (null, false);
+    }
+}
+
+/// <summary>
+/// The badge as data (spec §8.5), for a site that would rather render its own.
+/// </summary>
+/// <remarks>
+/// <see cref="Count"/> is null whenever nothing was measured, and <see cref="State"/> says which of
+/// the three cases that is — so a consumer coercing null to zero has to do it on purpose, and one
+/// reading the state cannot do it at all. Both are published because §5.4's middle case is the one
+/// every reimplementation loses.
+/// </remarks>
+public sealed record BadgeView(
+    string Slug,
+    string Name,
+    LifecycleState Lifecycle,
+    int? Count,
+    string State,
+    string Description,
+    double? AgeSeconds,
+    DateTimeOffset? MeasuredAt,
+    DateTimeOffset? LastReachableAt,
+    string PageUrl,
+    string BadgeUrl);
diff --git a/src/MUI.Web/Api/MuiApi.cs b/src/MUI.Web/Api/MuiApi.cs
index 1dbba1af..bb504cb8 100644
--- a/src/MUI.Web/Api/MuiApi.cs
+++ b/src/MUI.Web/Api/MuiApi.cs
@@ -45,6 +45,11 @@ public static IEndpointRouteBuilder MapMuiApi(this IEndpointRouteBuilder endpoin
         FeedEndpoints.Map(endpoints);
         DumpEndpoints.Map(endpoints);
 
+        // §8.5's owner-published outputs. Off /g/ rather than /api/, because these are pasted into
+        // somebody else's template by hand and the shortest honest URL is the one that survives
+        // being retyped.
+        BadgeEndpoints.Map(endpoints);
+
         return endpoints;
     }
 
diff --git a/src/MUI.Web/Api/PlayerBadge.cs b/src/MUI.Web/Api/PlayerBadge.cs
new file mode 100644
index 00000000..c953ecff
--- /dev/null
+++ b/src/MUI.Web/Api/PlayerBadge.cs
@@ -0,0 +1,238 @@
+using System.Globalization;
+using System.Net;
+using System.Text;
+
+using MUI.Catalog;
+
+namespace MUI.Web.Api;
+
+/// <summary>What a badge can be showing. Three states, and never two.</summary>
+/// <remarks>
+/// The same three-state discipline §5.4 applies to an hour of the heatmap, applied to a number on
+/// somebody else's front page. <see cref="Counted"/> covers a measured zero — we got in and nobody
+/// was there, which is a real fact about a game and a filled cell — and <see cref="Unknown"/> covers
+/// both "we could not count" and "we have not counted recently". Collapsing the second into a zero
+/// is rule 4, broken on a page we do not control and cannot correct.
+/// </remarks>
+public enum BadgeState
+{
+    Counted,
+
+    Unknown,
+
+    /// <summary>The game has gone dark (§7.5). A live-count badge has no live count to give.</summary>
+    Archived,
+}
+
+/// <summary>
+/// The live player-count badge of spec §8.5 — an owner-published output, on somebody else's page.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>This is the surface with the least room and the most exposure, and the rules do not bend for
+/// it.</b> A badge is embedded where we have no other sentence, no footnote and no chance to
+/// explain, so the number it shows has to carry its own age and its own state or it is exactly the
+/// unlabelled figure the incumbents publish. There is space: "14 now · 4m ago" is nine characters
+/// more than "14".
+/// </para>
+/// <para>
+/// <b>An unknown count is never a zero.</b> A game whose <c>WHO</c> we cannot parse renders
+/// "players unknown" in grey, not "0 players" in green — the second would be our parser's limit
+/// published as a fact about their game, on their own front page, which is rule 5 at its most
+/// damaging.
+/// </para>
+/// <para>
+/// No external font, no remote reference, no script. The SVG is self-contained because a badge that
+/// fetched anything would put a third-party request on every page that embeds it, and because an
+/// <c>&lt;img&gt;</c> does not execute one anyway.
+/// </para>
+/// </remarks>
+public static class PlayerBadge
+{
+    /// <summary>
+    /// How long a badge may be cached by a browser or a CDN.
+    /// </summary>
+    /// <remarks>
+    /// Five minutes: short enough that "live" is not a lie on a page somebody refreshes, long enough
+    /// that a game on a popular front page does not turn its readers into our traffic. Deliberately
+    /// well inside <c>FieldRegistry.Volatile</c>, the two hours after which a count is stale — a
+    /// cache entry that outlived the freshness of what it holds would be publishing a stale number
+    /// with a live label.
+    /// </remarks>
+    public const string CacheControl = "public, max-age=300";
+
+    /// <summary>The site's own accent, which means <em>measured</em> everywhere it appears.</summary>
+    private const string Measured = "#35d29a";
+
+    /// <summary>Grey. Never the accent, because there is nothing measured to point at.</summary>
+    private const string Absent = "#6b747c";
+
+    private const string Label = "mu*index";
+
+    private const int Height = 20;
+
+    /// <summary>
+    /// Reads a summary into the one of three things a badge can say.
+    /// </summary>
+    /// <remarks>
+    /// Archived is decided before the count, and not after. An archived game may still carry a count
+    /// from the last time it answered, and rendering it would put a live-sounding number on a page
+    /// for a game that stopped answering in 2023.
+    /// </remarks>
+    public static BadgeReading Read(GameSummary game, DateTimeOffset now)
+    {
+        ArgumentNullException.ThrowIfNull(game);
+
+        if (game.State is LifecycleState.Archived)
+        {
+            return new BadgeReading(BadgeState.Archived, null, null, game.LastReachableAt);
+        }
+
+        // The two halves of a measurement travel together or not at all: a count with no age is a
+        // number we cannot label, and an age with no count labels nothing.
+        return game is { PlayersNow: { } count, PlayersNowAt: { } at }
+            ? new BadgeReading(BadgeState.Counted, count, now - at, game.LastReachableAt)
+            : new BadgeReading(BadgeState.Unknown, null, null, game.LastReachableAt);
+    }
+
+    /// <summary>The badge as an SVG document.</summary>
+    public static string Svg(BadgeReading reading, string gameName)
+    {
+        ArgumentNullException.ThrowIfNull(reading);
+
+        var value = reading.Text;
+        var colour = reading.State is BadgeState.Counted ? Measured : Absent;
+
+        var labelWidth = Width(Label) + 12;
+        var valueWidth = Width(value) + 12;
+        var total = labelWidth + valueWidth;
+
+        // Everything interpolated below is either ours or escaped. A game's name is MSSP text and
+        // therefore attacker-controlled — it reaches the accessible title and nowhere else, and it
+        // goes through WebUtility.HtmlEncode on the way, because an SVG is a document and a name
+        // containing "</text>" would otherwise be markup.
+        var title = WebUtility.HtmlEncode($"{gameName} — {reading.Description}");
+
+        return $"""
+            <svg xmlns="http://www.w3.org/2000/svg" width="{total}" height="{Height}"
+                 role="img" aria-label="{title}">
+              <title>{title}</title>
+              <linearGradient id="s" x2="0" y2="100%">
+                <stop offset="0" stop-color="#fff" stop-opacity=".08"/>
+                <stop offset="1" stop-opacity=".08"/>
+              </linearGradient>
+              <rect width="{total}" height="{Height}" rx="3" fill="#1d2125"/>
+              <rect x="{labelWidth}" width="{valueWidth}" height="{Height}" rx="3" fill="{colour}"/>
+              <rect x="{labelWidth}" width="4" height="{Height}" fill="{colour}"/>
+              <rect width="{total}" height="{Height}" rx="3" fill="url(#s)"/>
+              <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">
+                <text x="{labelWidth / 2}" y="14" fill="#e8eaec" text-anchor="middle">{Label}</text>
+                <text x="{labelWidth + (valueWidth / 2)}" y="14" fill="#0f1113"
+                      text-anchor="middle">{WebUtility.HtmlEncode(value)}</text>
+              </g>
+            </svg>
+            """;
+    }
+
+    /// <summary>
+    /// A badge for a slug we do not have, as a badge.
+    /// </summary>
+    /// <remarks>
+    /// A 404 with a body, rather than an empty one. The reader of this is an operator who has just
+    /// pasted the wrong URL into their own site, and a broken-image icon tells them nothing while
+    /// this tells them the thing they need to know. The status is still 404 and it is never cached.
+    /// </remarks>
+    public static string UnknownSvg() =>
+        Svg(new BadgeReading(BadgeState.Unknown, null, null, null) { Override = "unknown game" }, "mu*index");
+
+    /// <summary>
+    /// How wide a string renders at 11px, near enough to lay a box out around it.
+    /// </summary>
+    /// <remarks>
+    /// An estimate, and it only has to be good enough that the text does not touch the edges: SVG
+    /// has no text metrics without a layout engine, and shipping a font to get them would put a
+    /// remote asset on every page that embeds this. Digits and lower-case are the common case and
+    /// are measured closest; anything wider simply gets a roomier box.
+    /// </remarks>
+    private static int Width(string text)
+    {
+        var width = 0d;
+
+        foreach (var c in text)
+        {
+            width += c switch
+            {
+                >= 'A' and <= 'Z' => 7.5,
+                'i' or 'j' or 'l' or 't' or 'f' or 'r' or '.' or ' ' or '·' => 3.6,
+                'm' or 'w' => 9.5,
+                _ => 6.3,
+            };
+        }
+
+        return (int)Math.Ceiling(width);
+    }
+}
+
+/// <summary>
+/// What the badge says, and why. The same reading serves the SVG and the JSON.
+/// </summary>
+/// <remarks>
+/// One reading behind both outputs, so an owner embedding the image and an owner reading the JSON
+/// cannot be told two different things about the same moment — which is the same reason the plain
+/// surface renders from the page's own view models.
+/// </remarks>
+public sealed record BadgeReading(
+    BadgeState State,
+    int? Count,
+    TimeSpan? Age,
+    DateTimeOffset? LastReachableAt)
+{
+    /// <summary>Set only by <see cref="PlayerBadge.UnknownSvg"/>, for a slug that names no game.</summary>
+    internal string? Override { get; init; }
+
+    /// <summary>
+    /// The words on the badge.
+    /// </summary>
+    /// <remarks>
+    /// A measured zero says "0 now", which is a fact we measured and are entitled to publish. An
+    /// unmeasured count says "players unknown" and never borrows the shape of a number.
+    /// </remarks>
+    public string Text => Override ?? State switch
+    {
+        BadgeState.Counted => $"{Count!.Value.ToString(CultureInfo.InvariantCulture)} now · {Relative()}",
+        BadgeState.Archived => "archived",
+        _ => "players unknown",
+    };
+
+    /// <summary>The same, as a sentence, for the accessible title and the JSON.</summary>
+    public string Description => State switch
+    {
+        BadgeState.Counted => $"{Count} players measured {Relative()} ago",
+        BadgeState.Archived => "archived — this game has stopped answering",
+        _ => "player count not measured",
+    };
+
+    /// <summary>How the API names this state, matching <see cref="PlayerCountState"/> where it can.</summary>
+    public string Word => State switch
+    {
+        BadgeState.Counted => "measured",
+        BadgeState.Archived => "archived",
+        _ => "unknown",
+    };
+
+    /// <summary>
+    /// A coarse age, because a badge has room for two characters and not for "4 minutes ago".
+    /// </summary>
+    /// <remarks>
+    /// Rounded down, never up. "1h" for something measured fifty-nine minutes ago overstates its
+    /// age, which is the safe direction; rounding the other way would call an hour-old number fresh.
+    /// </remarks>
+    private string Relative() => Age switch
+    {
+        null => "?",
+        { TotalMinutes: < 1 } => "just now",
+        { TotalHours: < 1 } age => $"{(int)age.TotalMinutes}m",
+        { TotalDays: < 1 } age => $"{(int)age.TotalHours}h",
+        var age => $"{(int)age!.Value.TotalDays}d",
+    };
+}
diff --git a/src/MUI.Web/Components/Pages/Account.razor b/src/MUI.Web/Components/Pages/Account.razor
index 7bca8a08..328c6681 100644
--- a/src/MUI.Web/Components/Pages/Account.razor
+++ b/src/MUI.Web/Components/Pages/Account.razor
@@ -56,6 +56,24 @@ else
                         <span class="faint">
                             verified @claim.ClaimedAt!.Value.ToString("d MMM yyyy")@(BeaconNote(claim))
                         </span>
+
+                        @*
+                            §8.5's owner-published outputs. Shown here because this is where the
+                            person who would paste it is, and shown as the exact line to copy —
+                            the same reason the claim page prints the MSSP variable in full.
+                        *@
+                        <details class="publish">
+                            <summary class="faint">put your player count on your own site</summary>
+                            <pre class="mono">&lt;a href="/g/@game.Slug"&gt;&lt;img src="/g/@game.Slug/badge.svg" alt="@game.Name on mu*index"&gt;&lt;/a&gt;</pre>
+                            <p class="faint">
+                                The badge carries the count <em>and</em> when we measured it, because
+                                a number with no age is the thing this site exists to replace. It
+                                says <em>players unknown</em> rather than nought when we could not
+                                count, and <em>archived</em> if the game stops answering. There is
+                                <a href="/g/@game.Slug/badge.json">JSON</a> too, if you would rather
+                                draw your own.
+                            </p>
+                        </details>
                     </li>
                 }
             </ul>
diff --git a/src/MUI.Web/Fixtures/FixtureGameQueries.cs b/src/MUI.Web/Fixtures/FixtureGameQueries.cs
index ca7b0c83..4a6046cc 100644
--- a/src/MUI.Web/Fixtures/FixtureGameQueries.cs
+++ b/src/MUI.Web/Fixtures/FixtureGameQueries.cs
@@ -41,13 +41,13 @@ public sealed class FixtureGameQueries : IGameQueries, IAvailabilityHistory
         Guid.Parse("aaaaaaaa-0000-0000-0000-000000000001"), "m-u-s-h", "M*U*S*H",
         "The PennMUSH development server.", LifecycleState.Active, IsClaimed: false,
         PlayersNow: 15, Codebase: "PennMUSH 1.8.8p0", MeasuredProtocols: ["MSSP", "CHARSET"],
-        LastReachableAt: Now.AddMinutes(-4));
+        LastReachableAt: Now.AddMinutes(-4), PlayersNowAt: Now.AddMinutes(-4));
 
     private static readonly GameSummary Eldertale = new(
         Guid.Parse("aaaaaaaa-0000-0000-0000-000000000002"), "eldertale", "Eldertale Online",
         null, LifecycleState.Active, IsClaimed: false,
         PlayersNow: 0, Codebase: "PennMUSH 1.8.8p0", MeasuredProtocols: ["MSSP", "CHARSET"],
-        LastReachableAt: Now.AddHours(-3));
+        LastReachableAt: Now.AddHours(-3), PlayersNowAt: Now.AddHours(-3));
 
     // No MSSP PLAYERS, no pre-login WHO. Its count exists only because the connect screen states it.
     private static readonly GameSummary Aardwolf = new(
@@ -55,7 +55,7 @@ public sealed class FixtureGameQueries : IGameQueries, IAvailabilityHistory
         "Counted from the connect screen, which is the only place this game publishes a number.",
         LifecycleState.Active, IsClaimed: false,
         PlayersNow: 219, Codebase: null, MeasuredProtocols: ["MSSP", "GMCP", "MCCP2", "MSDP"],
-        LastReachableAt: Now.AddMinutes(-40));
+        LastReachableAt: Now.AddMinutes(-40), PlayersNowAt: Now.AddMinutes(-40));
 
     // Answers, but nothing we can count. Renders "count unknown" — never a zero.
     private static readonly GameSummary MidnightSun = new(
@@ -69,14 +69,14 @@ public sealed class FixtureGameQueries : IGameQueries, IAvailabilityHistory
         "An intro screen long enough that the frame has to explain why it stopped.",
         LifecycleState.Active, IsClaimed: false,
         PlayersNow: 71, Codebase: null, MeasuredProtocols: ["MSSP", "MCCP2"],
-        LastReachableAt: Now.AddDays(-2));
+        LastReachableAt: Now.AddDays(-2), PlayersNowAt: Now.AddDays(-2));
 
     // Claimed, and the owner turned republication off. Stated without editorial (spec §8).
     private static readonly GameSummary Ashen = new(
         Guid.Parse("aaaaaaaa-0000-0000-0000-000000000007"), "ashen-court", "Ashen Court",
         "Courtly intrigue, low fantasy. Application required.", LifecycleState.Active,
         IsClaimed: true, PlayersNow: 9, Codebase: "Evennia", MeasuredProtocols: ["MSSP", "GMCP", "TLS"],
-        LastReachableAt: Now.AddMinutes(-9));
+        LastReachableAt: Now.AddMinutes(-9), PlayersNowAt: Now.AddMinutes(-9));
 
     private static readonly GameSummary Gaslight = new(
         Guid.Parse("aaaaaaaa-0000-0000-0000-000000000005"), "gaslight-row", "Gaslight Row",
diff --git a/src/MUI.Web/wwwroot/app.css b/src/MUI.Web/wwwroot/app.css
index bd5aa550..72617a13 100644
--- a/src/MUI.Web/wwwroot/app.css
+++ b/src/MUI.Web/wwwroot/app.css
@@ -1025,3 +1025,20 @@ table.client-matrix td a { color: var(--faint); }
 .prose pre code { font-size: 13px; }
 .prose ul, .prose ol { padding-left: 1.4em; }
 .prose li { margin-bottom: 4px; }
+
+/* ── owner-published outputs ───────────────────────────────────────────────
+   §8.5's badge snippet, shown where the person who pastes it already is. The
+   pre wraps rather than scrolls: a line somebody has to copy should be visible
+   in one piece. */
+
+details.publish { margin-top: 6px; }
+details.publish > summary { cursor: pointer; font-size: 12px; }
+details.publish pre {
+    background: var(--recessed);
+    border: 1px solid var(--line);
+    border-radius: 3px;
+    padding: 8px 10px;
+    font-size: 12px;
+    white-space: pre-wrap;
+    word-break: break-all;
+}
diff --git a/tests/MUI.Web.Tests/Api/BadgeApiTests.cs b/tests/MUI.Web.Tests/Api/BadgeApiTests.cs
new file mode 100644
index 00000000..8daa9020
--- /dev/null
+++ b/tests/MUI.Web.Tests/Api/BadgeApiTests.cs
@@ -0,0 +1,260 @@
+using System.Net;
+using System.Text.Json;
+
+using MUI.Web.Api;
+
+namespace MUI.Web.Tests.Api;
+
+/// <summary>
+/// The owner-published badge (spec §8.5), on a page we do not control.
+/// </summary>
+/// <remarks>
+/// Every rule this site has, asserted at its hardest point. A badge is embedded where there is no
+/// footnote, no provenance chip and no second sentence — so if a number can be published unlabelled
+/// or a silence can be published as a zero, it happens here first and we never see it.
+/// </remarks>
+public class BadgeApiTests
+{
+    /// <summary>
+    /// The count carries its own age, because there is nowhere else to put one.
+    /// </summary>
+    /// <remarks>
+    /// "15" on somebody's front page is the incumbents' badge. "15 now · 4m ago" is this site's
+    /// claim, in nine more characters.
+    /// </remarks>
+    [Test]
+    public async Task AMeasuredCountIsPublishedWithItsAge()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var svg = await host.Client.GetStringAsync("/g/m-u-s-h/badge.svg");
+
+        await Assert.That(svg).Contains("15 now");
+        await Assert.That(svg).Contains("4m");
+        await Assert.That(svg).Contains("mu*index");
+    }
+
+    /// <summary>
+    /// A measured zero is a measurement and says so; an unmeasured count never borrows its shape.
+    /// </summary>
+    /// <remarks>
+    /// This is rule 4 at the point it would do the most damage. Eldertale was probed and nobody was
+    /// there — a real fact, published. Midnight Sun answered and could not be counted, and renders
+    /// as unknown; a "0" there would be our parser's limit printed as a fact about their game, on
+    /// their own website, where we could not correct it.
+    /// </remarks>
+    [Test]
+    public async Task AMeasuredZeroIsAZeroAndAnUnknownCountIsNever()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var zero = await host.Client.GetStringAsync("/g/eldertale/badge.svg");
+        var unknown = await host.Client.GetStringAsync("/g/midnight-sun/badge.svg");
+
+        await Assert.That(zero).Contains("0 now");
+
+        await Assert.That(unknown).Contains("players unknown");
+        await Assert.That(unknown).DoesNotContain("0 now");
+        await Assert.That(unknown).DoesNotContain(">0<");
+    }
+
+    /// <summary>
+    /// Unknown is grey. The accent means measured everywhere on this site, and a badge is no place
+    /// to start spending it on something we did not measure.
+    /// </summary>
+    [Test]
+    public async Task OnlyAMeasuredBadgeWearsTheMeasuredColour()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var measured = await host.Client.GetStringAsync("/g/m-u-s-h/badge.svg");
+        var unknown = await host.Client.GetStringAsync("/g/midnight-sun/badge.svg");
+
+        await Assert.That(measured).Contains("#35d29a");
+        await Assert.That(unknown).DoesNotContain("#35d29a");
+    }
+
+    /// <summary>
+    /// An archived game's badge says archived rather than showing the last number it had.
+    /// </summary>
+    /// <remarks>
+    /// §7.5: archiving takes a game out of the listing and out of nothing else, so the badge still
+    /// answers — but a live-count badge for a game that stopped answering in 2023 has no live count,
+    /// and a stale one under a live label is the one thing it must not print.
+    /// </remarks>
+    [Test]
+    public async Task AnArchivedGameGetsABadgeThatSaysSo()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var svg = await host.Client.GetStringAsync("/g/gaslight-row/badge.svg");
+
+        await Assert.That(svg).Contains("archived");
+        await Assert.That(svg).DoesNotContain("now ·");
+    }
+
+    /// <summary>
+    /// A game's name is MSSP text, and MSSP text is attacker-controlled.
+    /// </summary>
+    /// <remarks>
+    /// The name reaches the accessible title and nowhere else, escaped. An SVG is a document, so a
+    /// game named <c>&lt;/text&gt;&lt;script&gt;</c> would otherwise be markup on every page that
+    /// embeds the badge — a stored injection with a distribution mechanism.
+    /// </remarks>
+    [Test]
+    public async Task AGamesOwnNameCannotBecomeMarkup()
+    {
+        var reading = new BadgeReading(BadgeState.Unknown, null, null, null);
+
+        var svg = PlayerBadge.Svg(reading, "</text><script>alert(1)</script>");
+
+        await Assert.That(svg).DoesNotContain("<script>");
+        await Assert.That(svg).Contains("&lt;script&gt;");
+    }
+
+    /// <summary>A badge is cached longer than the API, and still well inside a count's own life.</summary>
+    /// <remarks>
+    /// Every reader of somebody's front page fetches this, so a minute is too little; a count is
+    /// stale at two hours, so anything approaching that would serve a stale number under a live
+    /// label.
+    /// </remarks>
+    [Test]
+    public async Task ABadgeIsCacheableAndRevalidates()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var first = await host.Client.GetAsync("/g/m-u-s-h/badge.svg");
+
+        await Assert.That(first.Headers.CacheControl!.ToString()).IsEqualTo("public, max-age=300");
+        await Assert.That(first.Headers.ETag).IsNotNull();
+
+        var request = new HttpRequestMessage(HttpMethod.Get, "/g/m-u-s-h/badge.svg");
+        request.Headers.Add("If-None-Match", first.Headers.ETag!.ToString());
+
+        var second = await host.Client.SendAsync(request);
+
+        await Assert.That(second.StatusCode).IsEqualTo(HttpStatusCode.NotModified);
+        await Assert.That((await second.Content.ReadAsByteArrayAsync()).Length).IsEqualTo(0);
+    }
+
+    /// <summary>It is embedded cross-origin by definition, and served as an image.</summary>
+    [Test]
+    public async Task ABadgeIsServedAsAnImageAnybodyMayEmbed()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var response = await host.Client.GetAsync("/g/m-u-s-h/badge.svg");
+
+        await Assert.That(response.Content.Headers.ContentType!.MediaType).IsEqualTo("image/svg+xml");
+        await Assert.That(response.Headers.GetValues("Access-Control-Allow-Origin").Single())
+            .IsEqualTo("*");
+        await Assert.That(response.Headers.GetValues("X-Content-Type-Options").Single())
+            .IsEqualTo("nosniff");
+    }
+
+    /// <summary>
+    /// A slug the game used to wear still serves its badge, permanently.
+    /// </summary>
+    /// <remarks>
+    /// A badge is the likeliest thing here to outlive the URL it was copied from — pasted into a
+    /// template once and left for years — so §5.7's forever-redirect matters more for this route
+    /// than for any other.
+    /// </remarks>
+    [Test]
+    public async Task ABadgeUrlSurvivesARename()
+    {
+        await using var host = await ApiHost.StartAsync(new Dictionary<string, string?>
+        {
+            ["SlugAliases:tidewater-nights"] = "m-u-s-h",
+        });
+
+        var response = await host.Client.GetAsync("/g/tidewater-nights/badge.svg");
+
+        await Assert.That(response.StatusCode).IsEqualTo(HttpStatusCode.MovedPermanently);
+        await Assert.That(response.Headers.Location!.ToString()).IsEqualTo("/g/m-u-s-h/badge.svg");
+    }
+
+    /// <summary>A slug naming nothing gets a badge that says so, and is never cached.</summary>
+    [Test]
+    public async Task AnUnknownSlugSaysSoOnTheBadgeItself()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var response = await host.Client.GetAsync("/g/no-such-game/badge.svg");
+
+        await Assert.That(response.StatusCode).IsEqualTo(HttpStatusCode.NotFound);
+        await Assert.That(await response.Content.ReadAsStringAsync()).Contains("unknown game");
+        await Assert.That(response.Headers.CacheControl!.NoStore).IsTrue();
+    }
+
+    /// <summary>
+    /// The JSON publishes null and a named state, so a consumer cannot coerce silence to zero.
+    /// </summary>
+    /// <remarks>
+    /// Both, because §5.4's middle case is the one every reimplementation loses. A consumer reading
+    /// only <c>count</c> gets a null it has to handle; one reading <c>state</c> cannot mistake it.
+    /// </remarks>
+    [Test]
+    public async Task TheJsonNamesTheStateAsWellAsCarryingTheNumber()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var counted = await Json.ElementAsync(await host.Client.GetAsync("/g/m-u-s-h/badge.json"));
+        var unknown = await Json.ElementAsync(
+            await host.Client.GetAsync("/g/midnight-sun/badge.json"));
+
+        await Assert.That(counted.GetProperty("count").GetInt32()).IsEqualTo(15);
+        await Assert.That(counted.GetProperty("state").GetString()).IsEqualTo("measured");
+        await Assert.That(counted.GetProperty("measuredAt").ValueKind).IsNotEqualTo(JsonValueKind.Null);
+        await Assert.That(counted.GetProperty("ageSeconds").GetDouble()).IsGreaterThanOrEqualTo(0);
+
+        await Assert.That(unknown.GetProperty("count").ValueKind).IsEqualTo(JsonValueKind.Null);
+        await Assert.That(unknown.GetProperty("state").GetString()).IsEqualTo("unknown");
+        await Assert.That(unknown.GetProperty("measuredAt").ValueKind).IsEqualTo(JsonValueKind.Null);
+    }
+
+    /// <summary>The JSON points back at the page and at the image, so one fetch finds the rest.</summary>
+    [Test]
+    public async Task TheJsonLinksToThePageAndTheBadge()
+    {
+        await using var host = await ApiHost.StartAsync();
+
+        var badge = await Json.ElementAsync(await host.Client.GetAsync("/g/ashen-court/badge.json"));
+
+        await Assert.That(badge.GetProperty("pageUrl").GetString()).IsEqualTo("/g/ashen-court");
+        await Assert.That(badge.GetProperty("badgeUrl").GetString())
+            .IsEqualTo("/g/ashen-court/badge.svg");
+    }
+
+    /// <summary>
+    /// A count and its age travel together or not at all.
+    /// </summary>
+    /// <remarks>
+    /// A number we cannot label is a number this site may not publish, so a summary carrying a count
+    /// with no measurement time reads as unknown rather than as a bare figure. That combination
+    /// should not occur — the query fills both from one row — and the badge does not rely on it not
+    /// occurring.
+    /// </remarks>
+    [Test]
+    public async Task ACountWithNoAgeIsNotPublishedAsACount()
+    {
+        var unlabelled = new MUI.Catalog.GameSummary(
+            Guid.CreateVersion7(),
+            "orphan",
+            "Orphan",
+            null,
+            MUI.Catalog.LifecycleState.Active,
+            IsClaimed: false,
+            PlayersNow: 12,
+            Codebase: null,
+            MeasuredProtocols: [],
+            LastReachableAt: DateTimeOffset.UtcNow,
+            PlayersNowAt: null);
+
+        var reading = PlayerBadge.Read(unlabelled, DateTimeOffset.UtcNow);
+
+        await Assert.That(reading.State).IsEqualTo(BadgeState.Unknown);
+        await Assert.That(reading.Count).IsNull();
+        await Assert.That(reading.Text).IsEqualTo("players unknown");
+    }
+}

From e8d4788cb8544d0cb3f83215b8f2ae98177c2dc2 Mon Sep 17 00:00:00 2001
From: Harry Cordewener <nekomercutio@gmail.com>
Date: Sat, 15 Aug 2026 14:33:21 -0500
Subject: [PATCH 2/2] Let the badge show a count we read off a connect screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#27's FieldSources.IsMeasured now includes banner, and the badge picked
that up without a line changing: PlayerBadge.Read and BadgeEndpoints both
guard on ProvenanceChip.IsMeasured, which delegates to it. There was no
third spelling to fold in — checked, and the only other IsMeasured in the
tree are CapabilityFields' (measured-vs-declared FIELD NAMES) and
CatalogueSource's (fixture-vs-database), neither of which is this line.

But nothing asserted the case the decision turned on. This test had two
rows, one on each side of the old line, and Aardwolf — whose count exists
only because its connect screen states it — was in neither. Added as the
second control: dropping banner from the shared predicate fails this test
along with three of #27's own, and passing it back leaves all four green.

The MSSP row is untouched and still refuses: a game filling in a structured
self-description is reporting rather than being read, and its PLAYERS may
be whatever the codebase last cached.
---
 tests/MUI.Web.Tests/Api/BadgeApiTests.cs | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/tests/MUI.Web.Tests/Api/BadgeApiTests.cs b/tests/MUI.Web.Tests/Api/BadgeApiTests.cs
index 823a7c92..7d6eae17 100644
--- a/tests/MUI.Web.Tests/Api/BadgeApiTests.cs
+++ b/tests/MUI.Web.Tests/Api/BadgeApiTests.cs
@@ -48,8 +48,13 @@ public async Task AMeasuredCountIsPublishedWithItsAge()
     /// <para>
     /// The badge and <c>/api/games/{slug}</c> are held to the same predicate rather than to two
     /// judgements that agree today: the JSON below says <c>unknown</c> where the API says
-    /// <c>declared</c>, and both come from <c>ProvenanceChip.IsMeasured</c>. M*U*S*H is the control
-    /// — a <c>WHO</c> count, and it still goes out as a number.
+    /// <c>declared</c>, and both reach <c>FieldSources.IsMeasured</c> through
+    /// <c>ProvenanceChip</c>. Two controls, one on each side of that line — M*U*S*H's <c>WHO</c>
+    /// count, and Aardwolf's, which exists only because we read it off the connect screen. The
+    /// second is the whole point of the line being drawn on the <em>source</em> and not on who
+    /// authored the number: we open the socket and parse that text ourselves on every probe, so
+    /// its freshness is ours, and a badge that refused to show it would be withholding a
+    /// measurement we took.
     /// </para>
     /// </remarks>
     [Test]
@@ -60,6 +65,7 @@ public async Task ADeclaredCountIsNotPublishedAsAMeasuredOne()
         var declared = await host.Client.GetStringAsync("/g/ashen-court/badge.svg");
         var json = await Json.ElementAsync(await host.Client.GetAsync("/g/ashen-court/badge.json"));
         var measured = await host.Client.GetStringAsync("/g/m-u-s-h/badge.svg");
+        var banner = await host.Client.GetStringAsync("/g/aardwolf/badge.svg");
 
         await Assert.That(declared).Contains("players unknown");
         await Assert.That(declared).DoesNotContain("9 now")
@@ -71,6 +77,9 @@ await Assert.That(json.GetProperty("measuredAt").ValueKind).IsEqualTo(JsonValueK
             .Because("an instant beside no count of ours would name a measurement nobody took");
 
         await Assert.That(measured).Contains("15 now");
+
+        await Assert.That(banner).Contains("219 now")
+            .Because("we read that number off the connect screen ourselves, which is a measurement");
     }
 
     /// <summary>