feat(banner): per-campaign colour overrides and urgent alerts

Non-default campaigns gain an optional colour override (background / text /
link) in two sets — one for every theme, one for the dark theme only — and an
"urgent" flag.

- Colours ride profile.get as six trailing FlatBuffers strings on
  BannerCampaign (backward-compatible). The client resolves the cascade
  (dark <- dark ?? all, light <- all) per rendered theme and derives the strip
  border from the background in JS (no CSS color-mix, for the old Android
  WebView floor); AdBanner applies them as inline vars scoped to the strip.
- Urgent is resolved entirely server-side: while any enabled, in-window urgent
  campaign exists, computeActiveSet returns only the urgent campaigns and
  bannerFor skips the eligibility gate — so a system notice reaches every viewer
  (paid / hint-holding / no_banner included) and preempts the ordinary feed. No
  wire field; it appears on each viewer's next profile.get.
- Admin console (/_gm/banners): native colour pickers + a live light/dark
  preview of the strip, and an urgent toggle. The default campaign stays plain,
  enforced by the service and a DB CHECK.

Migration 00009 is additive (nullable colour columns + a bool default +
all-or-nothing / hex / default-plain CHECKs) — expand-contract, rollback-safe.

Docs: ARCHITECTURE §10, UI_DESIGN, FUNCTIONAL (+ru). Tests: ads unit (urgent
preempt + colour validation), codec + resolver unit, gateway transcode, and
integration (colour round-trip + urgent bypass against real Postgres).

backend/internal/ads/ads.go

@@ -30,6 +30,15 @@ var ErrDefaultImmutable = errors.New("ads: the default campaign cannot be modifi
 // window or message body).
 var ErrValidation = errors.New("ads: validation")
 
+// ColorSet is an optional per-campaign colour override for the banner strip:
+// background, foreground (text) and link, each a "#rrggbb" hex string. The three
+// are set together or the whole set is absent (a nil *ColorSet).
+type ColorSet struct {
+	Bg   string
+	Fg   string
+	Link string
+}
+
 // Campaign is one advertising placement order with its messages.
 type Campaign struct {
 	ID        uuid.UUID // uuid.Nil on create
@@ -40,6 +49,16 @@ type Campaign struct {
 	StartsAt  *time.Time // nil = open-ended start; always nil for the default
 	EndsAt    *time.Time // nil = open-ended end; always nil for the default
 	Messages  []Message
+	// OverrideAll paints the strip on every theme; OverrideDark, when set, further
+	// overrides the dark theme (the client resolves dark ← dark ?? all ?? token,
+	// light ← all ?? token). Both are nil for the default campaign and for a
+	// campaign that keeps the neutral theme tokens. Non-default only.
+	OverrideAll  *ColorSet
+	OverrideDark *ColorSet
+	// Urgent forces the banner on every viewer (bypassing eligibility) and, while
+	// any urgent campaign is active, suppresses every non-urgent campaign and the
+	// default remainder. Non-default only; always false for the default campaign.
+	Urgent    bool
 	CreatedAt time.Time
 	UpdatedAt time.Time
 }
@@ -70,10 +89,15 @@ type Timings struct {
 
 // ActiveCampaign is one campaign in the resolved rotation feed sent to a client:
 // its GCD-reduced show weight and its messages, already resolved to the viewer's
-// language and in display (round-robin) order.
+// language and in display (round-robin) order, plus the optional colour overrides
+// the client applies to the strip (nil = the neutral theme tokens). Urgency is not
+// carried here: it is resolved server-side into the set's membership and the
+// eligibility bypass, so the client only ever renders what it is sent.
 type ActiveCampaign struct {
-	Weight   int
-	Messages []string
+	Weight       int
+	Messages     []string
+	OverrideAll  *ColorSet
+	OverrideDark *ColorSet
 }
 
 // Eligible reports whether an account should be shown the advertising banner: a
@@ -85,14 +109,20 @@ func Eligible(paidAccount bool, hintBalance int, hasNoBanner bool) bool {
 }
 
 // computeActiveSet builds the resolved rotation feed from the enabled campaigns
-// at time now, in language lang. Campaigns outside their validity window, and
-// campaigns with no messages, are dropped. The default campaign's effective
-// weight is the remainder up to 100% — max(0, 100 - sum of active timed
-// weights) — so it fills unsold inventory and is dropped entirely when timed
-// campaigns already reach 100%. Weights are then reduced by their GCD so the
-// fair rotation cycle stays short. The input is expected to be the enabled
-// campaigns (ActiveCampaigns); disabled ones must already be excluded.
-func computeActiveSet(campaigns []Campaign, now time.Time, lang string) []ActiveCampaign {
+// at time now, in language lang, and reports whether the feed is an urgent one.
+// Campaigns outside their validity window, and campaigns with no messages, are
+// dropped.
+//
+// While any active campaign is urgent, the feed is the urgent campaigns alone —
+// every non-urgent timed campaign and the default remainder are suppressed for
+// the duration (and the caller shows the feed to every viewer, bypassing
+// eligibility). Otherwise the default campaign's effective weight is the
+// remainder up to 100% — max(0, 100 - sum of active timed weights) — so it fills
+// unsold inventory and is dropped entirely when timed campaigns already reach
+// 100%. Weights are then reduced by their GCD so the fair rotation cycle stays
+// short. The input is expected to be the enabled campaigns (ActiveCampaigns);
+// disabled ones must already be excluded.
+func computeActiveSet(campaigns []Campaign, now time.Time, lang string) ([]ActiveCampaign, bool) {
 	var timed []Campaign
 	var def *Campaign
 	for i := range campaigns {
@@ -108,20 +138,54 @@ func computeActiveSet(campaigns []Campaign, now time.Time, lang string) []Active
 			timed = append(timed, c)
 		}
 	}
+	if urgent := filterUrgent(timed); len(urgent) > 0 {
+		out := make([]ActiveCampaign, 0, len(urgent))
+		for _, c := range urgent {
+			out = append(out, activeFrom(c, lang))
+		}
+		reduceByGCD(out)
+		return out, true
+	}
 	sumTimed := 0
 	for _, c := range timed {
 		sumTimed += c.Weight
 	}
 	out := make([]ActiveCampaign, 0, len(timed)+1)
 	for _, c := range timed {
-		out = append(out, ActiveCampaign{Weight: c.Weight, Messages: resolveBodies(c.Messages, lang)})
+		out = append(out, activeFrom(c, lang))
 	}
 	if def != nil {
 		if dw := 100 - sumTimed; dw > 0 {
-			out = append(out, ActiveCampaign{Weight: dw, Messages: resolveBodies(def.Messages, lang)})
+			a := activeFrom(*def, lang)
+			a.Weight = dw // the default's stored weight is nominal; it fills the remainder
+			out = append(out, a)
 		}
 	}
 	reduceByGCD(out)
+	return out, false
+}
+
+// activeFrom projects a campaign to its rotation-feed entry: its show weight, its
+// language-resolved messages and its colour overrides (carried through by
+// reference, they are read-only).
+func activeFrom(c Campaign, lang string) ActiveCampaign {
+	return ActiveCampaign{
+		Weight:       c.Weight,
+		Messages:     resolveBodies(c.Messages, lang),
+		OverrideAll:  c.OverrideAll,
+		OverrideDark: c.OverrideDark,
+	}
+}
+
+// filterUrgent returns the urgent campaigns among cs, preserving order. It is the
+// preempt selector: a non-empty result makes the whole feed urgent.
+func filterUrgent(cs []Campaign) []Campaign {
+	var out []Campaign
+	for _, c := range cs {
+		if c.Urgent {
+			out = append(out, c)
+		}
+	}
 	return out
 }
 

backend/internal/ads/ads_test.go

@@ -46,12 +46,19 @@ func TestComputeActiveSet(t *testing.T) {
 	timed := func(name string, weight int, starts, ends *time.Time, msgs []Message) Campaign {
 		return Campaign{Name: name, Weight: weight, Enabled: true, StartsAt: starts, EndsAt: ends, Messages: msgs}
 	}
+	urgent := func(name string, weight int, msgs []Message) Campaign {
+		c := timed(name, weight, nil, nil, msgs)
+		c.Urgent = true
+		return c
+	}
+	red := &ColorSet{Bg: "#aa0000", Fg: "#ffffff", Link: "#ffdd00"}
 
 	tests := []struct {
-		name      string
-		campaigns []Campaign
-		lang      string
-		want      []ActiveCampaign
+		name       string
+		campaigns  []Campaign
+		lang       string
+		want       []ActiveCampaign
+		wantUrgent bool
 	}{
 		{
 			name:      "default only reduces to weight 1",
@@ -152,22 +159,71 @@ func TestComputeActiveSet(t *testing.T) {
 			lang: "en",
 			want: []ActiveCampaign{{Weight: 1, Messages: []string{"one-en", "two-en"}}},
 		},
+		{
+			name: "urgent preempts default and normal timed",
+			campaigns: []Campaign{
+				def(msg("house")),
+				timed("promo", 40, nil, nil, msg("promo")),
+				urgent("alert", 50, msg("alert")),
+			},
+			lang: "en",
+			// only the urgent campaign survives; a lone weight reduces to 1.
+			want:       []ActiveCampaign{{Weight: 1, Messages: []string{"alert-en"}}},
+			wantUrgent: true,
+		},
+		{
+			name: "multiple urgent share the feed by gcd",
+			campaigns: []Campaign{
+				def(msg("house")),
+				urgent("a", 60, msg("a")),
+				urgent("b", 40, msg("b")),
+			},
+			lang: "en",
+			// default and any non-urgent dropped; gcd(60,40)=20 -> 3 and 2.
+			want: []ActiveCampaign{
+				{Weight: 3, Messages: []string{"a-en"}},
+				{Weight: 2, Messages: []string{"b-en"}},
+			},
+			wantUrgent: true,
+		},
+		{
+			name: "out-of-window urgent does not preempt",
+			campaigns: []Campaign{
+				def(msg("house")),
+				func() Campaign { c := urgent("future", 50, msg("future")); c.StartsAt = &future; return c }(),
+			},
+			lang: "en",
+			// the urgent campaign is not yet live, so the normal default feed stands.
+			want: []ActiveCampaign{{Weight: 1, Messages: []string{"house-en"}}},
+		},
+		{
+			name: "colour overrides ride the active campaign",
+			campaigns: []Campaign{
+				def(msg("house")),
+				func() Campaign { c := timed("promo", 100, nil, nil, msg("promo")); c.OverrideAll = red; return c }(),
+			},
+			lang: "en",
+			want: []ActiveCampaign{{Weight: 1, Messages: []string{"promo-en"}, OverrideAll: red}},
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := computeActiveSet(tt.campaigns, now, tt.lang)
+			got, gotUrgent := computeActiveSet(tt.campaigns, now, tt.lang)
 			if !reflect.DeepEqual(got, tt.want) {
 				t.Errorf("computeActiveSet() =\n  %#v\nwant\n  %#v", got, tt.want)
 			}
+			if gotUrgent != tt.wantUrgent {
+				t.Errorf("computeActiveSet() urgent = %v, want %v", gotUrgent, tt.wantUrgent)
+			}
 		})
 	}
 }
 
 func TestComputeActiveSetEmpty(t *testing.T) {
 	// No campaigns at all yields an empty (non-nil-or-nil) feed without panicking.
-	if got := computeActiveSet(nil, time.Now(), "en"); len(got) != 0 {
-		t.Errorf("computeActiveSet(nil) = %#v, want empty", got)
+	if got, urgent := computeActiveSet(nil, time.Now(), "en"); len(got) != 0 || urgent {
+		t.Errorf("computeActiveSet(nil) = %#v urgent=%v, want empty non-urgent", got, urgent)
 	}
 }
 

backend/internal/ads/service.go

@@ -3,6 +3,7 @@ package ads
 import (
 	"context"
 	"fmt"
+	"regexp"
 	"strings"
 	"time"
 
@@ -40,17 +41,20 @@ func NewService(store *Store) *Service { return &Service{store: store} }
 // ActiveSet returns the resolved rotation feed for a viewer in language lang
 // (en/ru) together with the global display timings: the currently-active
 // campaigns, each with its GCD-reduced show weight and its messages resolved to
-// lang, ready for the client's weighted round-robin.
-func (s *Service) ActiveSet(ctx context.Context, lang string) ([]ActiveCampaign, Timings, error) {
+// lang, ready for the client's weighted round-robin. The bool result reports
+// whether the feed is urgent — an urgent feed is shown to every viewer
+// regardless of eligibility (the caller skips the eligibility gate for it).
+func (s *Service) ActiveSet(ctx context.Context, lang string) ([]ActiveCampaign, Timings, bool, error) {
 	campaigns, err := s.store.ActiveCampaigns(ctx)
 	if err != nil {
-		return nil, Timings{}, err
+		return nil, Timings{}, false, err
 	}
 	timings, err := s.store.Settings(ctx)
 	if err != nil {
-		return nil, Timings{}, err
+		return nil, Timings{}, false, err
 	}
-	return computeActiveSet(campaigns, time.Now().UTC(), lang), timings, nil
+	set, urgent := computeActiveSet(campaigns, time.Now().UTC(), lang)
+	return set, timings, urgent, nil
 }
 
 // ListCampaigns returns every campaign with its messages, for the admin console.
@@ -76,8 +80,13 @@ func (s *Service) CreateCampaign(ctx context.Context, c Campaign) (uuid.UUID, er
 	if err := validWindow(c.StartsAt, c.EndsAt); err != nil {
 		return uuid.Nil, err
 	}
+	all, dark, err := validOverrides(c.OverrideAll, c.OverrideDark)
+	if err != nil {
+		return uuid.Nil, err
+	}
 	return s.store.CreateCampaign(ctx, Campaign{
 		Name: name, Weight: c.Weight, Enabled: c.Enabled, StartsAt: c.StartsAt, EndsAt: c.EndsAt,
+		OverrideAll: all, OverrideDark: dark, Urgent: c.Urgent,
 	})
 }
 
@@ -99,6 +108,7 @@ func (s *Service) UpdateCampaign(ctx context.Context, c Campaign) error {
 		upd.Enabled = true
 		upd.StartsAt = nil
 		upd.EndsAt = nil
+		// The default (house) campaign stays plain: no colour overrides, never urgent.
 	} else {
 		if err := validWeight(c.Weight); err != nil {
 			return err
@@ -106,10 +116,17 @@ func (s *Service) UpdateCampaign(ctx context.Context, c Campaign) error {
 		if err := validWindow(c.StartsAt, c.EndsAt); err != nil {
 			return err
 		}
+		all, dark, err := validOverrides(c.OverrideAll, c.OverrideDark)
+		if err != nil {
+			return err
+		}
 		upd.Weight = c.Weight
 		upd.Enabled = c.Enabled
 		upd.StartsAt = c.StartsAt
 		upd.EndsAt = c.EndsAt
+		upd.OverrideAll = all
+		upd.OverrideDark = dark
+		upd.Urgent = c.Urgent
 	}
 	return s.store.UpdateCampaign(ctx, upd)
 }
@@ -254,6 +271,46 @@ func validWindow(starts, ends *time.Time) error {
 	return nil
 }
 
+// hexColor matches a "#rrggbb" colour — the format the console's native colour
+// input emits and the wire carries.
+var hexColor = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)
+
+// validOverrides validates the two optional colour sets together and returns
+// their normalised copies (nil when a set is absent), so a caller can store them
+// directly.
+func validOverrides(all, dark *ColorSet) (*ColorSet, *ColorSet, error) {
+	va, err := validColorSet(all)
+	if err != nil {
+		return nil, nil, err
+	}
+	vd, err := validColorSet(dark)
+	if err != nil {
+		return nil, nil, err
+	}
+	return va, vd, nil
+}
+
+// validColorSet validates one optional colour override: a nil set passes (no
+// override); otherwise all three colours must be present and "#rrggbb". It
+// returns a trimmed, lower-cased copy.
+func validColorSet(cs *ColorSet) (*ColorSet, error) {
+	if cs == nil {
+		return nil, nil
+	}
+	bg := strings.TrimSpace(cs.Bg)
+	fg := strings.TrimSpace(cs.Fg)
+	link := strings.TrimSpace(cs.Link)
+	if bg == "" || fg == "" || link == "" {
+		return nil, fmt.Errorf("%w: a colour override needs all of background, text and link", ErrValidation)
+	}
+	for _, h := range []string{bg, fg, link} {
+		if !hexColor.MatchString(h) {
+			return nil, fmt.Errorf("%w: colours must be #rrggbb hex", ErrValidation)
+		}
+	}
+	return &ColorSet{Bg: strings.ToLower(bg), Fg: strings.ToLower(fg), Link: strings.ToLower(link)}, nil
+}
+
 // validBodies trims and bounds both mandatory language bodies of a message.
 func validBodies(bodyEn, bodyRu string) (string, string, error) {
 	en := strings.TrimSpace(bodyEn)

backend/internal/ads/store.go

@@ -90,15 +90,23 @@ func (s *Store) Campaign(ctx context.Context, id uuid.UUID) (Campaign, error) {
 func (s *Store) CreateCampaign(ctx context.Context, c Campaign) (uuid.UUID, error) {
 	id := uuid.New()
 	now := time.Now().UTC()
+	abg, afg, alink := colorCols(c.OverrideAll)
+	dbg, dfg, dlink := colorCols(c.OverrideDark)
 	stmt := table.AdCampaigns.INSERT(
 		table.AdCampaigns.CampaignID, table.AdCampaigns.Name, table.AdCampaigns.Weight,
 		table.AdCampaigns.IsDefault, table.AdCampaigns.Enabled,
 		table.AdCampaigns.StartsAt, table.AdCampaigns.EndsAt,
+		table.AdCampaigns.OverrideBg, table.AdCampaigns.OverrideFg, table.AdCampaigns.OverrideLink,
+		table.AdCampaigns.OverrideBgDark, table.AdCampaigns.OverrideFgDark, table.AdCampaigns.OverrideLinkDark,
+		table.AdCampaigns.Urgent,
 		table.AdCampaigns.CreatedAt, table.AdCampaigns.UpdatedAt,
 	).VALUES(
 		postgres.UUID(id), postgres.String(c.Name), postgres.Int(int64(c.Weight)),
 		postgres.Bool(false), postgres.Bool(c.Enabled),
 		tsOrNull(c.StartsAt), tsOrNull(c.EndsAt),
+		abg, afg, alink,
+		dbg, dfg, dlink,
+		postgres.Bool(c.Urgent),
 		postgres.TimestampzT(now), postgres.TimestampzT(now),
 	)
 	if _, err := stmt.ExecContext(ctx, s.db); err != nil {
@@ -111,12 +119,20 @@ func (s *Store) CreateCampaign(ctx context.Context, c Campaign) (uuid.UUID, erro
 // window. The default flag is never touched here. Returns ErrNotFound when no
 // campaign matches.
 func (s *Store) UpdateCampaign(ctx context.Context, c Campaign) error {
+	abg, afg, alink := colorCols(c.OverrideAll)
+	dbg, dfg, dlink := colorCols(c.OverrideDark)
 	stmt := table.AdCampaigns.UPDATE(
 		table.AdCampaigns.Name, table.AdCampaigns.Weight, table.AdCampaigns.Enabled,
-		table.AdCampaigns.StartsAt, table.AdCampaigns.EndsAt, table.AdCampaigns.UpdatedAt,
+		table.AdCampaigns.StartsAt, table.AdCampaigns.EndsAt,
+		table.AdCampaigns.OverrideBg, table.AdCampaigns.OverrideFg, table.AdCampaigns.OverrideLink,
+		table.AdCampaigns.OverrideBgDark, table.AdCampaigns.OverrideFgDark, table.AdCampaigns.OverrideLinkDark,
+		table.AdCampaigns.Urgent, table.AdCampaigns.UpdatedAt,
 	).SET(
 		postgres.String(c.Name), postgres.Int(int64(c.Weight)), postgres.Bool(c.Enabled),
-		tsOrNull(c.StartsAt), tsOrNull(c.EndsAt), postgres.TimestampzT(time.Now().UTC()),
+		tsOrNull(c.StartsAt), tsOrNull(c.EndsAt),
+		abg, afg, alink,
+		dbg, dfg, dlink,
+		postgres.Bool(c.Urgent), postgres.TimestampzT(time.Now().UTC()),
 	).WHERE(table.AdCampaigns.CampaignID.EQ(postgres.UUID(c.ID)))
 	return execOne(ctx, s.db, stmt, "update campaign")
 }
@@ -257,18 +273,40 @@ func execOne(ctx context.Context, db qrm.Executable, stmt postgres.Statement, wh
 
 func modelToCampaign(r model.AdCampaigns) Campaign {
 	return Campaign{
-		ID:        r.CampaignID,
-		Name:      r.Name,
-		Weight:    int(r.Weight),
-		IsDefault: r.IsDefault,
-		Enabled:   r.Enabled,
-		StartsAt:  r.StartsAt,
-		EndsAt:    r.EndsAt,
-		CreatedAt: r.CreatedAt,
-		UpdatedAt: r.UpdatedAt,
+		ID:           r.CampaignID,
+		Name:         r.Name,
+		Weight:       int(r.Weight),
+		IsDefault:    r.IsDefault,
+		Enabled:      r.Enabled,
+		StartsAt:     r.StartsAt,
+		EndsAt:       r.EndsAt,
+		OverrideAll:  colorSetFrom(r.OverrideBg, r.OverrideFg, r.OverrideLink),
+		OverrideDark: colorSetFrom(r.OverrideBgDark, r.OverrideFgDark, r.OverrideLinkDark),
+		Urgent:       r.Urgent,
+		CreatedAt:    r.CreatedAt,
+		UpdatedAt:    r.UpdatedAt,
 	}
 }
 
+// colorSetFrom rebuilds an optional ColorSet from three nullable colour columns.
+// The all-or-nothing CHECK keeps the trio consistent, so a nil in any one means
+// the set is absent.
+func colorSetFrom(bg, fg, link *string) *ColorSet {
+	if bg == nil || fg == nil || link == nil {
+		return nil
+	}
+	return &ColorSet{Bg: *bg, Fg: *fg, Link: *link}
+}
+
+// colorCols renders a *ColorSet as its three column value-expressions in
+// bg, fg, link order — NULL for each when the set is absent.
+func colorCols(cs *ColorSet) (bg, fg, link postgres.Expression) {
+	if cs == nil {
+		return postgres.NULL, postgres.NULL, postgres.NULL
+	}
+	return postgres.String(cs.Bg), postgres.String(cs.Fg), postgres.String(cs.Link)
+}
+
 func modelToMessage(r model.AdMessages) Message {
 	return Message{
 		ID:         r.MessageID,