feat(result): the DM result is the world animation of the day

A shared DM result showed one pin, the person's own, and the animation
with everybody who played the day was nowhere. The DM result now goes
out as the world animation: every answer scored so far on one globe and
the first three on the podium with their photos. The caption keeps the
person's own day and adds their place in the world so far. Sharing from
the Mini App sends the same animation.

The day is still open in later time zones at a DM's 20:00, so the
result carries a Refresh button and an italic note on when the ranking
is final. Refresh redraws with the answers scored since, at most every
two minutes per language, and the bot reads updates one by one, so the
drawing runs in the background and a toast says what happens. Two
minutes after the last zone's 20:00 a job puts the final picture in
every DM result and takes the button away.

The picture is the same for everyone who reads a language, so it is
drawn once per version of the ranking and then sent by file_id
(migration 011_world_card.sql: the world_card table, the shown version
on chat_round and the job kind "world"). Without ffmpeg DM results go
out as before. The world podium writes distances under a kilometre in
metres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: amtiYo

CHANGELOG.md

@@ -11,6 +11,26 @@ See [`docs/versioning.md`](docs/versioning.md) for what the numbers mean and
 
 ## Unreleased
 
+Operators: migration `011_world_card.sql` runs on start with
+`AUTO_MIGRATE=true`: a `world_card` table, a `world_version` column on
+`chat_round` and the job kind `world`. The world animation is drawn with
+ffmpeg; without it DM results go out as before.
+
+### Changed
+
+- The DM result is the world animation of the day: every answer scored so
+  far on one globe and the first three on the podium, with their photos.
+  The caption keeps the person's own day and adds their place in the world
+  so far. Sharing the result from the Mini App sends the same animation,
+  so the shared post shows everyone, not one pin.
+- Until the day closes in every time zone the result carries a Refresh
+  button and an italic note on when the ranking is final. Refresh redraws
+  the picture with the answers scored since, at most once every two
+  minutes per language, and says when there is nothing new.
+- Two minutes after the last zone's 20:00 the final picture replaces the
+  one in every DM result, with the final place and without the button.
+- The world animation writes distances under a kilometre in metres.
+
 ## v0.0.1-alpha.7 - 2026-10-26
 
 Results show the players' faces, the DM result is about the person's own

cmd/maply/main.go

@@ -27,6 +27,7 @@ import (
 	"github.com/FreshLabDev/maply/internal/round"
 	"github.com/FreshLabDev/maply/internal/schedule"
 	"github.com/FreshLabDev/maply/internal/telegram"
+	"github.com/FreshLabDev/maply/internal/world"
 	"github.com/FreshLabDev/maply/migrations"
 	"github.com/FreshLabDev/maply/web"
 )
@@ -108,7 +109,6 @@ func run(log *slog.Logger) error {
 		opts.Profiles = profiles
 		go profiles.Run(ctx, 10*time.Minute)
 	}
-	b := bot.New(store, tgc, log, opts)
 	// The players' photos for the pins and tables of the results.
 	avatars := &avatar.Service{Store: store, TG: tgc, Log: log}
 
@@ -132,6 +132,33 @@ func run(log *slog.Logger) error {
 		log.Info("result cards on", "renderer", cfg.CardRendererURL, "sharing", cards.CanShare())
 	}
 
+	var sched *schedule.Scheduler
+	if cfg.Schedule {
+		sched = &schedule.Scheduler{
+			Store:     store,
+			TG:        tgc,
+			Weather:   schedule.OpenMeteo{},
+			Payloads:  signer,
+			Zones:     zones,
+			Countries: countries,
+			ImagesDir: cfg.ImagesDir,
+			Username:  me.Username,
+			AppURL:    cfg.AppURL,
+			Avatars:   avatars,
+			Log:       log,
+		}
+		if cards != nil {
+			sched.Cards = cards
+		}
+		if ffmpeg != "" {
+			sched.Anim = &schedule.Animator{FFmpeg: ffmpeg}
+			// A DM's result is the whole world's day on one globe.
+			sched.World = &world.Service{Store: store, Zones: zones, FFmpeg: ffmpeg, Avatars: avatars, Log: log}
+			opts.World = sched
+		}
+	}
+	b := bot.New(store, tgc, log, opts)
+
 	gameAPI := &api.Server{
 		Store:       store,
 		InitData:    auth.NewVerifier(cfg.TelegramBotToken),
@@ -190,26 +217,7 @@ func run(log *slog.Logger) error {
 		}
 	}()
 
-	if cfg.Schedule {
-		sched := &schedule.Scheduler{
-			Store:     store,
-			TG:        tgc,
-			Weather:   schedule.OpenMeteo{},
-			Payloads:  signer,
-			Zones:     zones,
-			Countries: countries,
-			ImagesDir: cfg.ImagesDir,
-			Username:  me.Username,
-			AppURL:    cfg.AppURL,
-			Avatars:   avatars,
-			Log:       log,
-		}
-		if cards != nil {
-			sched.Cards = cards
-		}
-		if ffmpeg != "" {
-			sched.Anim = &schedule.Animator{FFmpeg: ffmpeg}
-		}
+	if sched != nil {
 		go func() {
 			log.Info("scheduler starting")
 			if err := sched.Run(ctx); err != nil {

internal/anim/world.go

@@ -27,7 +27,10 @@ type World struct {
 	Guesses []Guess
 	Top     [3]*Winner // the first three; nil where there are fewer
 	Unit    string
-	Lang    language.Language
+	// UnitM writes a distance under a kilometre in metres; empty keeps it
+	// in kilometres.
+	UnitM string
+	Lang  language.Language
 }
 
 const worldDur = 12
@@ -100,5 +103,5 @@ func (w *World) Draw(c *Canvas, t float64) {
 		c.Pin(78, 172, 30, PinStyle{Fill: white, Hole: deep, NoEdge: true, EdgeWidth: 1}, 1, clip)
 		c.Text(Display, 40, s, 98, 173, Left, white, 1, clip)
 	}
-	c.podium(worldPodium, w.Top, w.Unit, "", t)
+	c.podium(worldPodium, w.Top, w.Unit, w.UnitM, t)
 }

internal/api/api_integration_test.go

@@ -93,7 +93,7 @@ func setup(t *testing.T) *harness {
 		t.Fatal(err)
 	}
 	for _, stmt := range []string{
-		`TRUNCATE maply.job, maply.chat_round, maply.guess, maply.site_guess, maply.site_player, maply.chat_settings, maply.round, maply.place, maply.avatar`,
+		`TRUNCATE maply.job, maply.chat_round, maply.guess, maply.site_guess, maply.site_player, maply.chat_settings, maply.round, maply.place, maply.avatar, maply.world_card`,
 		`TRUNCATE core.person, core.chat CASCADE`,
 		`TRUNCATE core.language_observation`,
 	} {

internal/bot/bot.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/FreshLabDev/maply/internal/db"
 	"github.com/FreshLabDev/maply/internal/round"
+	"github.com/FreshLabDev/maply/internal/schedule"
 	"github.com/FreshLabDev/maply/internal/telegram"
 )
 
@@ -69,6 +70,15 @@ type Options struct {
 	// Profiles draws the statistics picture; nil shows the statistics as
 	// text only.
 	Profiles Profiles
+	// World refreshes the world picture of a DM's result; nil leaves its
+	// Refresh button doing nothing.
+	World WorldRefresher
+}
+
+// WorldRefresher brings the world picture under a DM's result up to date;
+// see schedule.Scheduler.RefreshWorld.
+type WorldRefresher interface {
+	RefreshWorld(ctx context.Context, chatID, msgID int64, d round.Date) (schedule.Refresh, error)
 }
 
 type Bot struct {

internal/bot/bot_test.go

@@ -161,6 +161,7 @@ type fakeTelegram struct {
 	deleted      []int64
 	alerts       []string
 	answers      int
+	toasts       []string
 	members      map[int64]string
 	anims        []sent
 	animated     chan struct{} // told after each animation, when set
@@ -214,8 +215,9 @@ func (f *fakeTelegram) DeleteMessage(_ context.Context, _, messageID int64) erro
 	return nil
 }
 
-func (f *fakeTelegram) AnswerCallbackQuery(context.Context, string, string) error {
+func (f *fakeTelegram) AnswerCallbackQuery(_ context.Context, _, text string) error {
 	f.answers++
+	f.toasts = append(f.toasts, text)
 	return nil
 }
 

internal/bot/panels.go

@@ -12,6 +12,7 @@ import (
 	"github.com/FreshLabDev/maply/internal/db"
 	"github.com/FreshLabDev/maply/internal/i18n"
 	"github.com/FreshLabDev/maply/internal/round"
+	"github.com/FreshLabDev/maply/internal/schedule"
 	"github.com/FreshLabDev/maply/internal/telegram"
 )
 
@@ -139,6 +140,9 @@ func isPanel(m tg.Message) bool {
 }
 
 func (b *Bot) onCallback(ctx context.Context, cq *tg.CallbackQuery) error {
+	if d, ok := schedule.WorldCallback(cq.Data); ok {
+		return b.onRefreshWorld(ctx, cq, d)
+	}
 	owner, action, ok := parseMenuCB(cq.Data)
 	if !ok {
 		return b.tg.AnswerCallbackQuery(ctx, cq.ID, "")

internal/bot/world.go

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+package bot
+
+import (
+	"context"
+
+	"github.com/FreshLabDev/tg"
+
+	"github.com/FreshLabDev/maply/internal/i18n"
+	"github.com/FreshLabDev/maply/internal/round"
+	"github.com/FreshLabDev/maply/internal/schedule"
+)
+
+// onRefreshWorld is a press of Refresh under a DM's result: the world
+// picture is redrawn with the answers scored since, and a toast says what
+// happens. Only the person whose DM it is can press it.
+func (b *Bot) onRefreshWorld(ctx context.Context, cq *tg.CallbackQuery, d round.Date) error {
+	m := cq.Message
+	if b.opts.World == nil || m.Chat.Type != "private" || m.Chat.ID != cq.From.ID || m.MessageID == 0 {
+		return b.tg.AnswerCallbackQuery(ctx, cq.ID, "")
+	}
+	raw, err := b.personLang(ctx, cq.From)
+	if err != nil {
+		_ = b.tg.AnswerCallbackQuery(ctx, cq.ID, "")
+		return err
+	}
+	lang := i18n.Resolve(raw)
+	r, err := b.opts.World.RefreshWorld(ctx, m.Chat.ID, m.MessageID, d)
+	text := ""
+	switch r {
+	case schedule.RefreshSame:
+		text = i18n.T(lang, "world.refresh_same")
+	case schedule.RefreshFinal:
+		text = i18n.T(lang, "world.refresh_final")
+	case schedule.RefreshDrawing:
+		text = i18n.T(lang, "world.refresh_drawing")
+	}
+	if answerErr := b.tg.AnswerCallbackQuery(ctx, cq.ID, text); err == nil {
+		err = answerErr
+	}
+	return err
+}

internal/bot/world_test.go

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+package bot
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"testing"
+
+	"github.com/FreshLabDev/tg"
+
+	"github.com/FreshLabDev/maply/internal/round"
+	"github.com/FreshLabDev/maply/internal/schedule"
+)
+
+type fakeRefresher struct {
+	r     schedule.Refresh
+	calls []round.Date
+}
+
+func (f *fakeRefresher) RefreshWorld(_ context.Context, _, _ int64, d round.Date) (schedule.Refresh, error) {
+	f.calls = append(f.calls, d)
+	return f.r, nil
+}
+
+// Refresh works in the person's own DM only and says what it does.
+func TestRefreshWorld(t *testing.T) {
+	ctx := context.Background()
+	d := round.NewDate(2026, 11, 2)
+	press := func(chat tg.Chat, from int64) *tg.CallbackQuery {
+		return &tg.CallbackQuery{ID: "q", From: tg.User{ID: from, LanguageCode: "en"}, Data: "wr:" + d.String(),
+			Message: tg.Message{MessageID: 5, Chat: chat}}
+	}
+	for _, c := range []struct {
+		name  string
+		r     schedule.Refresh
+		cq    *tg.CallbackQuery
+		calls int
+		toast string
+	}{
+		{"drawing", schedule.RefreshDrawing, press(tg.Chat{ID: 9, Type: "private"}, 9), 1, "Drawing the map with the new answers, this takes up to a minute."},
+		{"nothing new", schedule.RefreshSame, press(tg.Chat{ID: 9, Type: "private"}, 9), 1, "No new answers yet."},
+		{"final", schedule.RefreshFinal, press(tg.Chat{ID: 9, Type: "private"}, 9), 1, "The day's ranking is final."},
+		{"gone", schedule.RefreshGone, press(tg.Chat{ID: 9, Type: "private"}, 9), 1, ""},
+		{"in a group", schedule.RefreshDrawing, press(tg.Chat{ID: -100, Type: "supergroup"}, 9), 0, ""},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			client := &fakeTelegram{}
+			world := &fakeRefresher{r: c.r}
+			b := New(newStore(), client, slog.New(slog.NewTextHandler(io.Discard, nil)), Options{World: world})
+			if err := b.onCallback(ctx, c.cq); err != nil {
+				t.Fatal(err)
+			}
+			if len(world.calls) != c.calls || (c.calls > 0 && world.calls[0] != d) {
+				t.Errorf("refreshes = %v", world.calls)
+			}
+			if len(client.toasts) != 1 || client.toasts[0] != c.toast {
+				t.Errorf("toasts = %q, want %q", client.toasts, c.toast)
+			}
+		})
+	}
+}

internal/db/db_integration_test.go

@@ -51,7 +51,7 @@ func testStore(t *testing.T) *Store {
 	reset := func() {
 		for _, stmt := range []string{
 			`UPDATE maply.runtime_state SET telegram_offset=0`,
-			`TRUNCATE maply.job, maply.chat_round, maply.guess, maply.site_guess, maply.site_player, maply.chat_settings, maply.round, maply.place, maply.avatar`,
+			`TRUNCATE maply.job, maply.chat_round, maply.guess, maply.site_guess, maply.site_player, maply.chat_settings, maply.round, maply.place, maply.avatar, maply.world_card`,
 			`TRUNCATE core.person, core.chat CASCADE`,
 			`TRUNCATE core.language_observation`,
 		} {