From cb4a31a860b4486694f8402065a0a285b921679a Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Mon, 15 Jun 2026 23:25:27 +0200
Subject: [PATCH 1/9] feat(ads): client banner rotation, fade UX & live toggle
 (PR2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Consume the server-driven banner block (PR1) in the UI and retire the gate.

- banner.ts: createScheduler — a smooth weighted round-robin over campaigns (each
  appears its weight share per cycle, evenly interleaved) with round-robin over a
  campaign's messages; the rotator drives fade-in -> hold/scroll -> fade-out -> gap
  -> fade-in, a lone message stays put, reduce-motion swaps instantly without scroll.
- model.ts/codec.ts: Profile.banner (Banner/BannerCampaign/BannerTimings) decoded
  from the fbs block.
- Screen.svelte: drop the compile-time SHOW_AD_BANNER; render AdBanner from
  app.profile.banner (campaigns + timings + reduceMotion).
- AdBanner.svelte: opacity-driven fades + scroll host; the rotator is recreated when
  the campaigns/timings change (a `banner` notify re-fetch swaps them in place).
- app.svelte.ts: on the `notify` `banner` sub-kind, refreshProfile() so the banner
  shows/hides in place.
- tests: scheduler distribution + round-robin, the fade sequence, single-message,
  reduce-motion, stop(); codec banner decode. UI_DESIGN.md + trackers updated.
---
 PLAN.md                           |   6 +-
 PRERELEASE.md                     |   2 +-
 docs/UI_DESIGN.md                 |  20 +++-
 ui/src/components/AdBanner.svelte |  77 +++++++------
 ui/src/components/Screen.svelte   |  15 +--
 ui/src/lib/app.svelte.ts          |  19 ++++
 ui/src/lib/banner.test.ts         | 179 +++++++++++++++++++++---------
 ui/src/lib/banner.ts              | 156 +++++++++++++++-----------
 ui/src/lib/codec.test.ts          |  35 ++++++
 ui/src/lib/codec.ts               |  29 +++++
 ui/src/lib/model.ts               |  26 +++++
 11 files changed, 399 insertions(+), 165 deletions(-)

diff --git a/PLAN.md b/PLAN.md
index c4214b1..fee5f9b 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -1428,9 +1428,9 @@ cannot submit; three-way admin filter.
       docker-network caddy hop `172.18.0.x` for chat moderation, and bucketing the gateway's
       per-IP rate limiter on it). Correct + spoof-safe in **both** contours (prod has no host
       caddy → public clients untrusted → real peer used). `peerIP` unit-tested.
-    - **Ad banner** gated **off** behind a compile-time `SHOW_AD_BANNER=false` in `Screen.svelte`
-      — the `{#if}` branch, the `AdBanner` import and `banner.ts` are tree-shaken out of the prod
-      bundle (code kept for post-release polish).
+    - **Ad banner** was gated off here behind `SHOW_AD_BANNER=false`; the **AD** phase
+      (PRERELEASE.md) later turned it into the real server-driven advertising network and removed
+      the gate (`Screen` renders it from `app.profile.banner`).
     - **Landing** Telegram entry is now just the **64px logo** (clickable, no button/caption).
     - **TG-fullscreen header** reworked again: title + menu are one **centred pair** (hamburger
       right of the title) pinned to the **bottom** of the TG nav band, lining up with Telegram's
diff --git a/PRERELEASE.md b/PRERELEASE.md
index 9bf751a..accdc65 100644
--- a/PRERELEASE.md
+++ b/PRERELEASE.md
@@ -32,7 +32,7 @@ the edge before prod. Each phase maps back to the owner's raw pre-release TODO l
 | DA | Dictionary admin: online release-archive upload → word-diff preview → install/activate; versioned dict volume; active version persisted in DB; resident label = release tag | owner ad-hoc | **done** |
 | AB | Manual account block (admin suspension): permanent/temporary with an editable en+ru reason picklist; a block forfeits the player's active games + cancels their open ones; a backend gate refuses a blocked account with **403 `account_blocked`**; the UI shows a terminal blocked screen and stops all push/poll; manual unblock; temporary blocks self-expire (migration `00003`) | owner ad-hoc | **done** |
 | AI | Honest AI opponent in quick game: an explicit 🤖 AI / 👤 random selector (AI default); the robot is seated and moves at once; 7-day inactivity loss (the per-turn timeout reused); chat/nudge disabled, no statistics; the opponent is shown as 🤖 everywhere | owner ad-hoc | **done** |
-| AD | Advertising banner ("ad network"): server-driven weighted campaigns (percent weight + validity window; the perpetual default fills the remainder up to 100%), bilingual messages shown by bot (`service_language`); eligibility = free account + empty hint wallet + no `no_banner` role (guests included); the resolved feed rides `profile.get` with a `notify` `banner` re-poll on eligibility change; `/_gm/banners` admin + global display timings; client smooth-weighted-round-robin rotation + fade-out/gap/fade-in UX. A single `app.load` bootstrap aggregator was considered and **deferred** (see ARCHITECTURE §10). | owner ad-hoc | PR1 backend+admin **done**; PR2 UI rotation **next** |
+| AD | Advertising banner ("ad network"): server-driven weighted campaigns (percent weight + validity window; the perpetual default fills the remainder up to 100%), bilingual messages shown by bot (`service_language`); eligibility = free account + empty hint wallet + no `no_banner` role (guests included); the resolved feed rides `profile.get` with a `notify` `banner` re-poll on eligibility change; `/_gm/banners` admin + global display timings; client smooth-weighted-round-robin rotation + fade-out/gap/fade-in UX. A single `app.load` bootstrap aggregator was considered and **deferred** (see ARCHITECTURE §10). | owner ad-hoc | **done** (PR1 backend+admin, PR2 UI rotation) |
 | → | Stage 18 — prod contour deploy | — | see [`PLAN.md`](PLAN.md) |
 
 ## Key findings (these reshaped the raw list — read before starting a phase)
diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md
index 83b1a85..28c8151 100644
--- a/docs/UI_DESIGN.md
+++ b/docs/UI_DESIGN.md
@@ -195,16 +195,24 @@ Login uses `Screen`.
   under-board slot shows the **Scores: N** preview. The screen **title** is the variant's
   display name (Scrabble / Скрэббл / Erudite / Эрудит), not a constant "Scrabble".
 
-## Announcement banner (`components/AdBanner.svelte`, `lib/banner.ts`)
+## Advertising banner (`components/AdBanner.svelte`, `lib/banner.ts`)
 
 A one-line inset strip under the nav bar, drawn on a dedicated `--ad-bg` token —
 a subtle accent, a touch darker than the surroundings in the light theme and a touch lighter
 in the dark theme, mapped to Telegram's `secondary_bg_color` inside the Mini App. Content is
-minimal markdown (text + links, escaped + linkified). A parameterised **rotator** drives messages: a fitting message
-holds `holdMs` (default 60 s) then cross-fades to the next; a message wider than the strip
-pauses (`edgePauseMs`), scrolls to its right edge at `scrollPxPerSec`, pauses, and repeats
-until the cycle exceeds `holdMs`. Today a **mock** provider rotates a long and a short
-message; the source becomes a server-driven channel later (see ARCHITECTURE).
+minimal markdown (text + links, escaped + linkified). It is **server-driven**: the campaigns and
+display timings ride the `profile.get` response (`app.profile.banner`, present only for an eligible
+viewer — see ARCHITECTURE §10), so `Screen` renders the strip only when that block is present, and
+a `notify` `banner` event re-fetches the profile to show or hide it in place.
+
+A **smooth weighted round-robin** (`createScheduler`) picks the next message: campaigns compete by
+their weight (each appears its weight share per cycle, evenly interleaved, not at random), and a
+campaign's own messages advance round-robin. The **rotator** then drives one message: it fades in
+(`fadeInMs`), holds `holdMs` (a message wider than the strip pauses `edgePauseMs`, scrolls to its
+right edge at `scrollPxPerSec`, pauses, and repeats while under `holdMs`), then — when more than one
+message exists — fades out (`fadeOutMs`), waits `gapMs`, and fades the next in. A lone message stays
+put (a long one keeps scrolling). All timings are operator-set (`/_gm/banner-settings`). Under
+**reduce-motion** the fades collapse to an instant swap and a long message does not scroll.
 
 ## Result / status iconography (`lib/result.ts`)
 
diff --git a/ui/src/components/AdBanner.svelte b/ui/src/components/AdBanner.svelte
index b9e37fc..a49baa4 100644
--- a/ui/src/components/AdBanner.svelte
+++ b/ui/src/components/AdBanner.svelte
@@ -1,43 +1,57 @@
 <script lang="ts">
-  import { onDestroy, onMount } from 'svelte';
-  import { fade } from 'svelte/transition';
-  import {
-    createBannerRotator,
-    defaultBannerConfig,
-    linkify,
-    mockBanners,
-    type BannerConfig,
-    type BannerItem,
-  } from '../lib/banner';
+  import { createBannerRotator, defaultBannerTimings, linkify } from '../lib/banner';
+  import type { BannerCampaign, BannerTimings } from '../lib/model';
   import { onExternalLinkClick } from '../lib/telegram';
 
-  let { items = mockBanners(), config = defaultBannerConfig }: { items?: BannerItem[]; config?: BannerConfig } =
-    $props();
+  let {
+    campaigns,
+    timings = defaultBannerTimings,
+    reduceMotion = false,
+  }: { campaigns: BannerCampaign[]; timings?: BannerTimings; reduceMotion?: boolean } = $props();
 
-  let current = $state(0);
+  let current = $state('');
+  let opacity = $state(0);
+  let opDur = $state(0); // opacity transition duration, ms (fade-in / fade-out)
   let tx = $state(0);
   let txDur = $state(0);
   let track = $state<HTMLElement>();
   let viewport = $state<HTMLElement>();
 
-  let rotator: ReturnType<typeof createBannerRotator> | null = null;
-
-  onMount(() => {
-    rotator = createBannerRotator(items, {
-      overflowPx: () => Math.max(0, (track?.scrollWidth ?? 0) - (viewport?.clientWidth ?? 0)),
-      show: (i) => {
-        current = i;
+  // Recreate the rotator whenever the campaigns, timings or reduce-motion change (a
+  // `banner` notify re-fetches the profile, swapping the campaigns in place). Under
+  // reduce-motion the fade/gap timings collapse to 0 (instant swap) and overflowPx
+  // reports 0 (no scroll).
+  $effect(() => {
+    const cfg: BannerTimings = reduceMotion ? { ...timings, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 } : timings;
+    const rotator = createBannerRotator(campaigns, {
+      show: (md) => {
+        current = md;
+        tx = 0;
+        txDur = 0;
+        opDur = 0;
+        opacity = 0;
+        requestAnimationFrame(() => {
+          opDur = cfg.fadeInMs;
+          opacity = 1;
+        });
+      },
+      resetScroll: () => {
         tx = 0;
         txDur = 0;
       },
+      hide: (durationMs) => {
+        opDur = durationMs;
+        opacity = 0;
+      },
+      overflowPx: () => (reduceMotion ? 0 : Math.max(0, (track?.scrollWidth ?? 0) - (viewport?.clientWidth ?? 0))),
       scrollTo: (toPx, durationMs) => {
         txDur = durationMs;
         tx = -toPx;
       },
-    }, config);
+    }, cfg);
     rotator.start();
+    return () => rotator.stop();
   });
-  onDestroy(() => rotator?.stop());
 </script>
 
 <!-- The banner links are rendered via {@html}; a delegated click routes any of them through the
@@ -45,16 +59,13 @@
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div class="ad" bind:this={viewport} onclick={onExternalLinkClick}>
-  {#key current}
-    <div
-      class="track"
-      bind:this={track}
-      in:fade={{ duration: config.fadeMs }}
-      style="transform:translateX({tx}px); transition:transform {txDur}ms linear"
-    >
-      {@html linkify(items[current]?.md ?? '')}
-    </div>
-  {/key}
+  <div
+    class="track"
+    bind:this={track}
+    style="transform:translateX({tx}px); opacity:{opacity}; transition:transform {txDur}ms linear, opacity {opDur}ms ease"
+  >
+    {@html linkify(current)}
+  </div>
 </div>
 
 <style>
@@ -76,7 +87,7 @@
     /* The side inset lives on the track (not the clipping .ad) so the scroll distance
        (scrollWidth - viewport.clientWidth) reaches the very end of a long message. */
     padding: 0 var(--pad);
-    will-change: transform;
+    will-change: transform, opacity;
   }
   .track :global(a) {
     color: var(--accent);
diff --git a/ui/src/components/Screen.svelte b/ui/src/components/Screen.svelte
index 99128f8..0d16adb 100644
--- a/ui/src/components/Screen.svelte
+++ b/ui/src/components/Screen.svelte
@@ -2,6 +2,7 @@
   import type { Snippet } from 'svelte';
   import Header from './Header.svelte';
   import AdBanner from './AdBanner.svelte';
+  import { app } from '../lib/app.svelte';
   import { navigate } from '../lib/router.svelte';
 
   // The app-shell layout (all screens): the nav bar grows; the ad strip, content and
@@ -27,12 +28,6 @@
     column?: boolean;
   } = $props();
 
-  // The promotional banner is feature-gated OFF until it is polished after release. The flag is
-  // a compile-time `false`, so the {#if} branch — and with it the AdBanner import and its
-  // banner.ts logic — is dead-code-eliminated from the production bundle. Flip to
-  // true to bring it back.
-  const SHOW_AD_BANNER = false;
-
   // Edge-swipe back: a rightward drag begun in the left band returns to `back`, the standard
   // mobile gesture (instant on release — the route slide plays the animation). Listened at the
   // window in the CAPTURE phase so the board's own pointer handlers (which capture/stop the
@@ -94,7 +89,13 @@
 
 <div class="screen">
   <Header {title} {back} grow={growNav} />
-  {#if SHOW_AD_BANNER}<AdBanner />{/if}
+  {#if app.profile?.banner && app.profile.banner.campaigns.length}
+    <AdBanner
+      campaigns={app.profile.banner.campaigns}
+      timings={app.profile.banner.timings}
+      reduceMotion={app.reduceMotion}
+    />
+  {/if}
   <main class="content" class:scroll class:fill={!growNav} class:column>{@render children?.()}</main>
   {#if tabbar}
     <nav class="tabbar">{@render tabbar()}</nav>
diff --git a/ui/src/lib/app.svelte.ts b/ui/src/lib/app.svelte.ts
index 5a7a0b0..3be311a 100644
--- a/ui/src/lib/app.svelte.ts
+++ b/ui/src/lib/app.svelte.ts
@@ -276,6 +276,11 @@ function openStream(): void {
         if (e.sub === 'admin_reply') {
           app.feedbackReplyUnread = true;
         }
+        // The viewer's ad-banner eligibility may have changed (paid/hints/no_banner): re-fetch
+        // the profile, which carries the banner block, so the banner shows or hides in place.
+        if (e.sub === 'banner') {
+          void refreshProfile();
+        }
         void refreshNotifications();
       }
     },
@@ -300,6 +305,20 @@ function scheduleReconnect(): void {
   }, 4000);
 }
 
+/**
+ * refreshProfile re-fetches the account profile (which carries the ad-banner block),
+ * after a `banner` notify signals the viewer's banner eligibility changed. Best-effort:
+ * a transient failure leaves the previous profile in place.
+ */
+export async function refreshProfile(): Promise<void> {
+  if (!app.session) return;
+  try {
+    app.profile = await gateway.profileGet();
+  } catch {
+    // Best-effort; the banner just stays as it was until the next fetch.
+  }
+}
+
 /**
  * refreshNotifications recomputes the badge count (incoming friend requests).
  * Authoritative poll, complementing the live 'notify' push. Game invitations have
diff --git a/ui/src/lib/banner.test.ts b/ui/src/lib/banner.test.ts
index 6028bd6..26a9927 100644
--- a/ui/src/lib/banner.test.ts
+++ b/ui/src/lib/banner.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { createBannerRotator, defaultBannerConfig, linkify } from './banner';
+import { createBannerRotator, createScheduler, defaultBannerTimings, linkify, type BannerHost } from './banner';
+import type { BannerTimings } from './model';
 
 describe('linkify', () => {
   it('escapes html and renders markdown links', () => {
@@ -20,71 +21,147 @@ describe('linkify', () => {
   });
 });
 
-describe('banner rotator', () => {
+describe('createScheduler', () => {
+  it('serves each campaign its weight share over a cycle, evenly spread', () => {
+    const sched = createScheduler([
+      { weight: 3, messages: ['a'] },
+      { weight: 7, messages: ['b'] },
+    ]);
+    expect(sched.total).toBe(2);
+    const cycle = Array.from({ length: 10 }, () => sched.next());
+    const a = cycle.filter((m) => m === 'a').length;
+    const b = cycle.filter((m) => m === 'b').length;
+    expect(a).toBe(3);
+    expect(b).toBe(7);
+    // Smoothly interleaved, not clustered: the minority campaign appears in both halves.
+    expect(cycle.slice(0, 5)).toContain('a');
+    expect(cycle.slice(5)).toContain('a');
+  });
+
+  it('round-robins messages within a campaign', () => {
+    const sched = createScheduler([{ weight: 1, messages: ['m0', 'm1', 'm2'] }]);
+    expect(sched.total).toBe(3);
+    expect([sched.next(), sched.next(), sched.next(), sched.next()]).toEqual(['m0', 'm1', 'm2', 'm0']);
+  });
+
+  it('drops empty and non-positive-weight campaigns', () => {
+    const sched = createScheduler([
+      { weight: 0, messages: ['skip-zero'] },
+      { weight: 5, messages: [] },
+      { weight: 2, messages: ['keep'] },
+    ]);
+    expect(sched.total).toBe(1);
+    expect(sched.next()).toBe('keep');
+  });
+
+  it('is empty for no campaigns', () => {
+    const sched = createScheduler([]);
+    expect(sched.total).toBe(0);
+    expect(sched.next()).toBe('');
+  });
+});
+
+// recordingHost captures the rotator's host calls as a sequence, with a fixed overflow.
+function recordingHost(overflow = 0): { host: BannerHost; calls: string[]; shown: string[] } {
+  const calls: string[] = [];
+  const shown: string[] = [];
+  return {
+    calls,
+    shown,
+    host: {
+      show: (md) => {
+        shown.push(md);
+        calls.push('show');
+      },
+      resetScroll: () => calls.push('reset'),
+      hide: () => calls.push('hide'),
+      overflowPx: () => overflow,
+      scrollTo: () => calls.push('scroll'),
+    },
+  };
+}
+
+const cfg: BannerTimings = {
+  holdMs: 1000,
+  edgePauseMs: 100,
+  scrollPxPerSec: 200,
+  fadeOutMs: 300,
+  gapMs: 50,
+  fadeInMs: 200,
+};
+
+describe('createBannerRotator', () => {
   afterEach(() => vi.useRealTimers());
 
-  it('holds a fitting message then advances, and scrolls an overflowing one', () => {
+  it('runs the fade-out / gap / fade-in sequence between two messages', () => {
     vi.useFakeTimers();
-    const cfg = { ...defaultBannerConfig, holdMs: 1000, edgePauseMs: 100, fadeMs: 10, scrollPxPerSec: 50 };
-    const shown: number[] = [];
-    let scrolled = 0;
-    const overflow = [0, 200]; // item 0 fits, item 1 overflows
-    const r = createBannerRotator(
-      [{ md: 'a' }, { md: 'b' }],
-      {
-        overflowPx: (i) => overflow[i],
-        show: (i) => shown.push(i),
-        scrollTo: () => scrolled++,
-      },
-      cfg,
-    );
-
+    const { host, calls, shown } = recordingHost(0);
+    const r = createBannerRotator([{ weight: 1, messages: ['a'] }, { weight: 1, messages: ['b'] }], host, cfg);
     r.start();
-    expect(shown).toEqual([0]);
-    vi.advanceTimersByTime(cfg.fadeMs); // settle + measure item 0
-    vi.advanceTimersByTime(cfg.holdMs); // advance to item 1
-    expect(shown).toEqual([0, 1]);
-    vi.advanceTimersByTime(cfg.fadeMs); // settle + measure item 1 (overflows)
-    vi.advanceTimersByTime(cfg.edgePauseMs); // edge pause -> scrollTo
-    expect(scrolled).toBe(1);
+    expect(shown).toEqual(['a']); // first message shown immediately
+    vi.advanceTimersByTime(cfg.fadeInMs); // fade in -> measure (fits)
+    vi.advanceTimersByTime(cfg.holdMs - 1);
+    expect(calls).not.toContain('hide'); // still holding
+    vi.advanceTimersByTime(1); // hold elapsed -> fade out
+    expect(calls).toContain('hide');
+    expect(shown).toEqual(['a']); // next not shown yet (during fade-out + gap)
+    vi.advanceTimersByTime(cfg.fadeOutMs + cfg.gapMs); // -> show the next message
+    expect(shown).toEqual(['a', 'b']);
     r.stop();
   });
 
-  it('repeats the scroll cycle while under holdMs, then advances', () => {
+  it('scrolls an overflowing message', () => {
     vi.useFakeTimers();
-    const cfg = { holdMs: 2500, edgePauseMs: 100, fadeMs: 10, scrollPxPerSec: 100 };
-    const shown: number[] = [];
-    let scrolls = 0;
-    const r = createBannerRotator(
-      [{ md: 'long' }, { md: 'short' }],
-      { overflowPx: (i) => (i === 0 ? 100 : 0), show: (i) => shown.push(i), scrollTo: () => scrolls++ },
-      cfg,
-    );
+    const { host, calls } = recordingHost(200); // overflow 200px, 200px/s -> 1000ms scroll
+    const r = createBannerRotator([{ weight: 1, messages: ['long'] }, { weight: 1, messages: ['x'] }], host, cfg);
     r.start();
-    vi.advanceTimersByTime(110); // fade(10) + edgePause(100) -> first scroll
-    expect(scrolls).toBe(1);
-    expect(shown).toEqual([0]);
-    vi.advanceTimersByTime(1200); // scrollDur(1000) + edgePause + edgePause -> re-show + second scroll
-    expect(scrolls).toBe(2);
-    expect(shown).toEqual([0, 0]); // re-shown to reset scroll, still item 0 (under holdMs)
-    vi.advanceTimersByTime(10_000);
-    expect(shown).toContain(1); // eventually exceeds holdMs and advances to the fitting message
+    vi.advanceTimersByTime(cfg.fadeInMs + cfg.edgePauseMs); // fade in + edge pause -> scrollTo
+    expect(calls).toContain('scroll');
+    r.stop();
+  });
+
+  it('shows a single message once and never fades it out', () => {
+    vi.useFakeTimers();
+    const { host, calls, shown } = recordingHost(0);
+    const r = createBannerRotator([{ weight: 1, messages: ['solo'] }], host, cfg);
+    r.start();
+    vi.advanceTimersByTime(cfg.fadeInMs + cfg.holdMs * 5);
+    expect(shown).toEqual(['solo']);
+    expect(calls).not.toContain('hide');
+    r.stop();
+  });
+
+  it('swaps instantly when fade timings are zero (reduce-motion)', () => {
+    vi.useFakeTimers();
+    const zero: BannerTimings = { ...cfg, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 };
+    const { host, shown } = recordingHost(0); // reduce-motion host reports no overflow
+    const r = createBannerRotator([{ weight: 1, messages: ['a'] }, { weight: 1, messages: ['b'] }], host, zero);
+    r.start();
+    // fadeIn(0) + hold -> fadeOut(0) + gap(0) -> next; the +5 flushes the trailing
+    // zero-delay timer chain that lands on the hold boundary.
+    vi.advanceTimersByTime(zero.holdMs + 5);
+    expect(shown).toEqual(['a', 'b']);
     r.stop();
   });
 
   it('stop() halts further advancement', () => {
     vi.useFakeTimers();
-    const cfg = { ...defaultBannerConfig, holdMs: 100, fadeMs: 5, edgePauseMs: 5 };
-    const shown: number[] = [];
-    const r = createBannerRotator(
-      [{ md: 'a' }, { md: 'b' }],
-      { overflowPx: () => 0, show: (i) => shown.push(i), scrollTo: () => {} },
-      cfg,
-    );
+    const { host, shown } = recordingHost(0);
+    const r = createBannerRotator([{ weight: 1, messages: ['a'] }, { weight: 1, messages: ['b'] }], host, cfg);
     r.start();
-    vi.advanceTimersByTime(cfg.fadeMs);
+    vi.advanceTimersByTime(cfg.fadeInMs);
+    r.stop();
+    vi.advanceTimersByTime(60_000);
+    expect(shown).toEqual(['a']);
+  });
+
+  it('does not start with no campaigns', () => {
+    vi.useFakeTimers();
+    const { host, shown } = recordingHost(0);
+    const r = createBannerRotator([], host, defaultBannerTimings);
+    r.start();
+    vi.advanceTimersByTime(60_000);
+    expect(shown).toEqual([]);
     r.stop();
-    vi.advanceTimersByTime(10_000);
-    expect(shown).toEqual([0]);
   });
 });
diff --git a/ui/src/lib/banner.ts b/ui/src/lib/banner.ts
index e942752..34fdb6e 100644
--- a/ui/src/lib/banner.ts
+++ b/ui/src/lib/banner.ts
@@ -1,39 +1,72 @@
-// Announcement / "ad" banner — a parameterised rotator plus a tiny markdown linkifier.
-// The rotator is DOM-agnostic (the host measures overflow and applies the visual
-// effects through callbacks), so its timing is unit-testable with fake timers. Today
-// the content is a mock long↔short rotation; later it becomes a server-driven
-// announcements channel (see ARCHITECTURE).
+// Advertising banner — the server-driven rotation engine plus a tiny markdown
+// linkifier. The scheduler and rotator are DOM-agnostic (the host measures overflow
+// and applies the visual effects through callbacks), so their timing and fairness are
+// unit-testable with fake timers. The campaigns + timings come from the profile's
+// banner block (see lib/model, ARCHITECTURE §10); the host is AdBanner.svelte.
 
-export interface BannerConfig {
-  /** How long one message is shown before advancing (short text), ms. */
-  holdMs: number;
-  /** Pause at each end before/after scrolling a long message, ms. */
-  edgePauseMs: number;
-  /** Scroll speed for a long (overflowing) message, px/sec. */
-  scrollPxPerSec: number;
-  /** Cross-fade duration between messages, ms. */
-  fadeMs: number;
-}
+import type { BannerCampaign, BannerTimings } from './model';
 
-export const defaultBannerConfig: BannerConfig = {
+/** Fallback display timings, matching the seeded ad_settings defaults. */
+export const defaultBannerTimings: BannerTimings = {
   holdMs: 60_000,
   edgePauseMs: 5_000,
   scrollPxPerSec: 40,
-  fadeMs: 400,
+  fadeOutMs: 1_000,
+  gapMs: 250,
+  fadeInMs: 1_000,
 };
 
-export interface BannerItem {
-  /** Minimal markdown: plain text + `[label](url)` links. */
-  md: string;
+/** Scheduler yields the next message to show, fairly across weighted campaigns. */
+export interface Scheduler {
+  next(): string;
+  /** Total messages across all (non-empty, positive-weight) campaigns. */
+  readonly total: number;
 }
 
-/** The host the rotator drives; the Svelte component supplies the DOM measurements. */
+/**
+ * createScheduler builds a smooth weighted round-robin over campaigns: each call to
+ * next() picks the campaign whose running weight is highest (then decremented by the
+ * total weight), so over one cycle of `sum(weights)` picks every campaign appears
+ * exactly its weight share, evenly interleaved rather than clustered (the nginx/envoy
+ * algorithm). Within a campaign its messages advance round-robin. Campaigns with no
+ * messages or a non-positive weight are dropped.
+ */
+export function createScheduler(campaigns: BannerCampaign[]): Scheduler {
+  const cs = campaigns.filter((c) => c.weight > 0 && c.messages.length > 0);
+  const current = cs.map(() => 0); // SWRR running weights
+  const cursor = cs.map(() => 0); // per-campaign round-robin position
+  const totalWeight = cs.reduce((sum, c) => sum + c.weight, 0);
+  const total = cs.reduce((sum, c) => sum + c.messages.length, 0);
+
+  return {
+    total,
+    next(): string {
+      if (cs.length === 0) return '';
+      let best = 0;
+      for (let i = 0; i < cs.length; i++) {
+        current[i] += cs[i].weight;
+        if (current[i] > current[best]) best = i;
+      }
+      current[best] -= totalWeight;
+      const c = cs[best];
+      const md = c.messages[cursor[best] % c.messages.length];
+      cursor[best]++;
+      return md;
+    },
+  };
+}
+
+/** The host the rotator drives; AdBanner.svelte supplies the DOM measurements and effects. */
 export interface BannerHost {
-  /** Overflow width of item `index` in px (0 when it fits). */
-  overflowPx(index: number): number;
-  /** Render item `index` (the host fades it in and resets scroll to the start). */
-  show(index: number): void;
-  /** Animate the horizontal scroll to `toPx` over `durationMs`. */
+  /** Render md and fade it in (over fadeInMs), with the scroll reset to the start. */
+  show(md: string): void;
+  /** Reset the scroll to the start without re-fading (to loop a long message). */
+  resetScroll(): void;
+  /** Fade the current message out over durationMs. */
+  hide(durationMs: number): void;
+  /** Overflow width of the currently-shown message in px (0 when it fits or motion is reduced). */
+  overflowPx(): number;
+  /** Animate the horizontal scroll to toPx over durationMs. */
   scrollTo(toPx: number, durationMs: number): void;
 }
 
@@ -43,16 +76,19 @@ export interface Rotator {
 }
 
 /**
- * createBannerRotator drives a list of messages: a fitting message holds `holdMs`
- * then advances; an overflowing one pauses, scrolls to its right edge, pauses, then
- * repeats while the elapsed cycle is under `holdMs`, else advances.
+ * createBannerRotator rotates the scheduled messages: each message fades in, holds
+ * `holdMs` (an overflowing one scrolls to its right edge and back while under holdMs),
+ * then — when more than one message exists — fades out over `fadeOutMs`, waits `gapMs`,
+ * and fades the next one in. A single message stays put (a long one keeps scrolling).
+ * Reduce-motion is handled by the host: pass zeroed fade timings and an overflowPx that
+ * returns 0, and messages swap instantly without scrolling.
  */
 export function createBannerRotator(
-  items: BannerItem[],
+  campaigns: BannerCampaign[],
   host: BannerHost,
-  config: BannerConfig = defaultBannerConfig,
+  config: BannerTimings = defaultBannerTimings,
 ): Rotator {
-  let index = 0;
+  const sched = createScheduler(campaigns);
   let running = false;
   let cycleStart = 0;
   const timers: ReturnType<typeof setTimeout>[] = [];
@@ -65,26 +101,23 @@ export function createBannerRotator(
     timers.length = 0;
   };
 
-  function advance() {
-    if (!running) return;
-    index = (index + 1) % items.length;
-    present();
-  }
-
-  function present() {
+  function present(md: string) {
     if (!running) return;
     clear();
-    host.show(index);
-    // Let the swapped-in message render before measuring its overflow.
-    at(config.fadeMs, () => {
-      const over = host.overflowPx(index);
-      if (over <= 0) {
-        at(config.holdMs, advance);
-        return;
-      }
-      cycleStart = Date.now();
+    host.show(md);
+    at(config.fadeInMs, measure);
+  }
+
+  function measure() {
+    if (!running) return;
+    cycleStart = Date.now();
+    const over = host.overflowPx();
+    if (over > 0) {
       scrollCycle(over);
-    });
+      return;
+    }
+    if (sched.total > 1) at(config.holdMs, advance);
+    // A single fitting message stays put.
   }
 
   function scrollCycle(over: number) {
@@ -92,22 +125,27 @@ export function createBannerRotator(
     at(config.edgePauseMs, () => {
       host.scrollTo(over, dur);
       at(dur + config.edgePauseMs, () => {
-        if (Date.now() - cycleStart >= config.holdMs) {
+        if (sched.total > 1 && Date.now() - cycleStart >= config.holdMs) {
           advance();
         } else {
-          host.show(index); // resets scroll to the start
+          host.resetScroll();
           scrollCycle(over);
         }
       });
     });
   }
 
+  function advance() {
+    if (!running) return;
+    host.hide(config.fadeOutMs);
+    at(config.fadeOutMs + config.gapMs, () => present(sched.next()));
+  }
+
   return {
     start() {
-      if (running || items.length === 0) return;
+      if (running || sched.total === 0) return;
       running = true;
-      index = 0;
-      present();
+      present(sched.next());
     },
     stop() {
       running = false;
@@ -145,13 +183,3 @@ export function linkify(md: string): string {
   parts.push(escapeHtml(md.slice(last)));
   return parts.join('');
 }
-
-/** mockBanners is the placeholder rotation (long ↔ short) to demo the mechanics. */
-export function mockBanners(): BannerItem[] {
-  return [
-    { md: 'New season starts soon — [learn more](https://example.com/season).' },
-    {
-      md: 'Tip: a 7-tile play earns a +50 bonus. Try the daily tournament, climb the leaderboard, and challenge friends — more modes are coming, [stay tuned](https://example.com/news)!',
-    },
-  ];
-}
diff --git a/ui/src/lib/codec.test.ts b/ui/src/lib/codec.test.ts
index b96eda8..0d7ef77 100644
--- a/ui/src/lib/codec.test.ts
+++ b/ui/src/lib/codec.test.ts
@@ -12,6 +12,7 @@ import {
   decodeLinkResult,
   decodeMatchResult,
   decodeOutgoingList,
+  decodeProfile,
   decodeSession,
   decodeFeedbackState,
   decodeFeedbackUnread,
@@ -449,6 +450,40 @@ describe('codec', () => {
     expect(r.game?.id).toBe('g-open');
     expect(r.game?.status).toBe('open');
   });
+
+  it('decodes the profile banner block (campaigns + timings)', () => {
+    const b = new Builder(256);
+    const uid = b.createString('u-1');
+    const m0 = b.createString('promo-en');
+    const msgs = fb.BannerCampaign.createMessagesVector(b, [m0]);
+    const camp = fb.BannerCampaign.createBannerCampaign(b, 3, msgs);
+    const camps = fb.BannerInfo.createCampaignsVector(b, [camp]);
+    const banner = fb.BannerInfo.createBannerInfo(b, camps, 60000, 5000, 40, 1000, 250, 1000);
+    fb.Profile.startProfile(b);
+    fb.Profile.addUserId(b, uid);
+    fb.Profile.addBanner(b, banner);
+    b.finish(fb.Profile.endProfile(b));
+
+    const p = decodeProfile(b.asUint8Array());
+    expect(p.banner?.campaigns).toEqual([{ weight: 3, messages: ['promo-en'] }]);
+    expect(p.banner?.timings).toEqual({
+      holdMs: 60000,
+      edgePauseMs: 5000,
+      scrollPxPerSec: 40,
+      fadeOutMs: 1000,
+      gapMs: 250,
+      fadeInMs: 1000,
+    });
+  });
+
+  it('leaves the profile banner undefined when absent', () => {
+    const b = new Builder(64);
+    const uid = b.createString('u-1');
+    fb.Profile.startProfile(b);
+    fb.Profile.addUserId(b, uid);
+    b.finish(fb.Profile.endProfile(b));
+    expect(decodeProfile(b.asUint8Array()).banner).toBeUndefined();
+  });
 });
 
 // The live play loop exchanges alphabet indices, mapped through the per-variant
diff --git a/ui/src/lib/codec.ts b/ui/src/lib/codec.ts
index af97592..60d9676 100644
--- a/ui/src/lib/codec.ts
+++ b/ui/src/lib/codec.ts
@@ -9,6 +9,8 @@ import { indexForLetter, letterForIndex, setAlphabet, type AlphabetEntryWire } f
 import type { PlacedTile } from './client';
 import type {
   AccountRef,
+  Banner,
+  BannerCampaign,
   BlockStatus,
   ChatMessage,
   EvalResult,
@@ -316,6 +318,33 @@ export function decodeProfile(buf: Uint8Array): Profile {
     blockFriendRequests: p.blockFriendRequests(),
     isGuest: p.isGuest(),
     notificationsInAppOnly: p.notificationsInAppOnly(),
+    banner: decodeBanner(p),
+  };
+}
+
+// decodeBanner projects the optional advertising-banner block of a Profile, or
+// undefined when the viewer is not eligible (the field is absent).
+function decodeBanner(p: fb.Profile): Banner | undefined {
+  const b = p.banner();
+  if (!b) return undefined;
+  const campaigns: BannerCampaign[] = [];
+  for (let i = 0; i < b.campaignsLength(); i++) {
+    const c = b.campaigns(i);
+    if (!c) continue;
+    const messages: string[] = [];
+    for (let j = 0; j < c.messagesLength(); j++) messages.push(c.messages(j));
+    campaigns.push({ weight: c.weight(), messages });
+  }
+  return {
+    campaigns,
+    timings: {
+      holdMs: b.holdMs(),
+      edgePauseMs: b.edgePauseMs(),
+      scrollPxPerSec: b.scrollPxPerSec(),
+      fadeOutMs: b.fadeOutMs(),
+      gapMs: b.gapMs(),
+      fadeInMs: b.fadeInMs(),
+    },
   };
 }
 
diff --git a/ui/src/lib/model.ts b/ui/src/lib/model.ts
index faefcbe..32c1703 100644
--- a/ui/src/lib/model.ts
+++ b/ui/src/lib/model.ts
@@ -138,6 +138,32 @@ export interface Profile {
   isGuest: boolean;
   /** Confine notifications to the in-app stream (no out-of-app platform push). */
   notificationsInAppOnly: boolean;
+  /** The advertising-banner block, present only for a viewer eligible to see it. */
+  banner?: Banner;
+}
+
+/** Banner is the advertising-banner block of an eligible viewer's profile. */
+export interface Banner {
+  campaigns: BannerCampaign[];
+  timings: BannerTimings;
+}
+
+/** BannerCampaign is one campaign in the rotation feed. */
+export interface BannerCampaign {
+  /** GCD-reduced show weight for the client's smooth weighted round-robin. */
+  weight: number;
+  /** Messages in display order, already resolved to the viewer's bot language. */
+  messages: string[];
+}
+
+/** BannerTimings are the global banner display timings (ms, except scrollPxPerSec). */
+export interface BannerTimings {
+  holdMs: number;
+  edgePauseMs: number;
+  scrollPxPerSec: number;
+  fadeOutMs: number;
+  gapMs: number;
+  fadeInMs: number;
 }
 
 /** BlockStatus is the caller's current manual block, fetched after any call reports
-- 
2.52.0


From 53c6e34c13d970c9e549f90ea7a126b02be5ee5b Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Mon, 15 Jun 2026 23:35:52 +0200
Subject: [PATCH 2/9] feat(ads): add a link-formatting help aside to the banner
 message editor

On the campaign detail page, beside the "Add message" form, a static aside
explains the message markdown: plain text is escaped, `[text](url)` becomes a
link, and only http(s)/root-relative targets are linkified (others show as
plain text). New .form-help (flex row) + .help (muted aside) console styles;
wraps below the form on a narrow viewport.
---
 backend/internal/adminconsole/assets/console.css | 16 ++++++++++++++++
 .../templates/pages/banner_detail.gohtml         |  9 +++++++++
 2 files changed, 25 insertions(+)

diff --git a/backend/internal/adminconsole/assets/console.css b/backend/internal/adminconsole/assets/console.css
index 8002a48..706432e 100644
--- a/backend/internal/adminconsole/assets/console.css
+++ b/backend/internal/adminconsole/assets/console.css
@@ -86,6 +86,22 @@ h1 { font-size: 1.4rem; margin: 0 0 0.4rem; }
   font: inherit;
 }
 .form textarea { min-height: 4rem; resize: vertical; }
+/* A form beside a static help aside (e.g. message-formatting hints). The form keeps its
+   own max-width; the aside fills the remainder and wraps below on a narrow viewport. */
+.form-help { display: flex; flex-wrap: wrap; gap: 1rem; align-items: flex-start; }
+.help {
+  flex: 1 1 16rem;
+  min-width: 14rem;
+  max-width: 30rem;
+  background: var(--panel-hi);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 0.5rem 0.8rem;
+  font-size: 0.85rem;
+  color: var(--ink-dim);
+}
+.help h4 { margin: 0 0 0.4rem; font-size: 0.85rem; color: var(--ink); }
+.help p { margin: 0.35rem 0; }
 button {
   background: var(--accent);
   color: #06121f;
diff --git a/backend/internal/adminconsole/templates/pages/banner_detail.gohtml b/backend/internal/adminconsole/templates/pages/banner_detail.gohtml
index 90b154d..603e07f 100644
--- a/backend/internal/adminconsole/templates/pages/banner_detail.gohtml
+++ b/backend/internal/adminconsole/templates/pages/banner_detail.gohtml
@@ -39,11 +39,20 @@
 </div>
 {{else}}<p class="note">no messages yet</p>{{end}}
 <h3>Add message</h3>
+<div class="form-help">
 <form class="form col" method="post" action="/_gm/banners/{{.ID}}/messages">
 <label>English <input type="text" name="body_en" maxlength="500" required></label>
 <label>Russian <input type="text" name="body_ru" maxlength="500" required></label>
 <div><button type="submit">Add message</button></div>
 </form>
+<aside class="help">
+<h4>Formatting</h4>
+<p>Plain text is shown as-is (any HTML is escaped).</p>
+<p>Add a link with markdown — <code>[visible text](https://example.com)</code> — which renders as the linked <em>visible text</em>.</p>
+<p>Only <code>https://</code>, <code>http://</code> and root-relative <code>/path</code> targets become links; any other scheme (e.g. <code>javascript:</code>, <code>ftp:</code>) is dropped and shown as plain text.</p>
+<p>Keep it short: an over-long line scrolls in the strip. The same formatting applies when editing a message above.</p>
+</aside>
+</div>
 </section>
 {{end}}
 {{- end}}
-- 
2.52.0


From 9e72e2c7999c67a9257ee45cbe2be2291c6e4449 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Mon, 15 Jun 2026 23:53:42 +0200
Subject: [PATCH 3/9] =?UTF-8?q?feat(ads):=20banner=20message=20editor=20?=
 =?UTF-8?q?=E2=80=94=20top=20help=20aside=20+=20multi-line=20fields?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Admin campaign editor polish:
- move the link-formatting help aside to the top of the Messages section,
  beside the intro note (~40% width), so it no longer drops below and stretches
  the form fields.
- make the English/Russian message fields 3-row, vertically resizable textareas
  (was single-line inputs) so long text wraps instead of scrolling off to the
  right. The strip is white-space:nowrap, so a stray newline collapses to a space
  on display.
---
 .../internal/adminconsole/assets/console.css  | 12 ++++-----
 .../templates/pages/banner_detail.gohtml      | 26 +++++++++----------
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/backend/internal/adminconsole/assets/console.css b/backend/internal/adminconsole/assets/console.css
index 706432e..2f53bcc 100644
--- a/backend/internal/adminconsole/assets/console.css
+++ b/backend/internal/adminconsole/assets/console.css
@@ -86,13 +86,13 @@ h1 { font-size: 1.4rem; margin: 0 0 0.4rem; }
   font: inherit;
 }
 .form textarea { min-height: 4rem; resize: vertical; }
-/* A form beside a static help aside (e.g. message-formatting hints). The form keeps its
-   own max-width; the aside fills the remainder and wraps below on a narrow viewport. */
-.form-help { display: flex; flex-wrap: wrap; gap: 1rem; align-items: flex-start; }
+/* A static help aside (e.g. message-formatting hints) beside an intro note at the top of a
+   section: the note fills the row, the aside takes ~40% and both wrap on a narrow viewport. */
+.help-top { display: flex; flex-wrap: wrap; gap: 1rem; align-items: flex-start; margin: 0.2rem 0 0.6rem; }
+.help-top .note { flex: 1 1 16rem; margin: 0; }
 .help {
-  flex: 1 1 16rem;
-  min-width: 14rem;
-  max-width: 30rem;
+  flex: 0 1 40%;
+  min-width: 16rem;
   background: var(--panel-hi);
   border: 1px solid var(--line);
   border-radius: 6px;
diff --git a/backend/internal/adminconsole/templates/pages/banner_detail.gohtml b/backend/internal/adminconsole/templates/pages/banner_detail.gohtml
index 603e07f..aeeb1dc 100644
--- a/backend/internal/adminconsole/templates/pages/banner_detail.gohtml
+++ b/backend/internal/adminconsole/templates/pages/banner_detail.gohtml
@@ -21,12 +21,21 @@
 {{end}}
 </section>
 <section class="panel"><h2>Messages</h2>
+<div class="help-top">
 <p class="note">Each message must be filled in both languages; the viewer sees the variant for the bot they play through. The messages of a campaign share its show weight, rotating in this order.</p>
+<aside class="help">
+<h4>Formatting</h4>
+<p>Plain text is shown as-is (any HTML is escaped).</p>
+<p>Add a link with markdown — <code>[visible text](https://example.com)</code> — which renders as the linked <em>visible text</em>.</p>
+<p>Only <code>https://</code>, <code>http://</code> and root-relative <code>/path</code> targets become links; any other scheme (e.g. <code>javascript:</code>, <code>ftp:</code>) is dropped and shown as plain text.</p>
+<p>Keep it short: an over-long line scrolls in the strip; the same formatting applies when editing a message above.</p>
+</aside>
+</div>
 {{range .Messages}}
 <div class="row">
 <form class="form col" method="post" action="/_gm/banners/{{$.Data.ID}}/messages/{{.ID}}">
-<label>English <input type="text" name="body_en" value="{{.BodyEn}}" maxlength="500" required></label>
-<label>Russian <input type="text" name="body_ru" value="{{.BodyRu}}" maxlength="500" required></label>
+<label>English <textarea name="body_en" rows="3" maxlength="500" required>{{.BodyEn}}</textarea></label>
+<label>Russian <textarea name="body_ru" rows="3" maxlength="500" required>{{.BodyRu}}</textarea></label>
 <div class="actions">
 <button type="submit">Save</button>
 </div>
@@ -39,20 +48,11 @@
 </div>
 {{else}}<p class="note">no messages yet</p>{{end}}
 <h3>Add message</h3>
-<div class="form-help">
 <form class="form col" method="post" action="/_gm/banners/{{.ID}}/messages">
-<label>English <input type="text" name="body_en" maxlength="500" required></label>
-<label>Russian <input type="text" name="body_ru" maxlength="500" required></label>
+<label>English <textarea name="body_en" rows="3" maxlength="500" required></textarea></label>
+<label>Russian <textarea name="body_ru" rows="3" maxlength="500" required></textarea></label>
 <div><button type="submit">Add message</button></div>
 </form>
-<aside class="help">
-<h4>Formatting</h4>
-<p>Plain text is shown as-is (any HTML is escaped).</p>
-<p>Add a link with markdown — <code>[visible text](https://example.com)</code> — which renders as the linked <em>visible text</em>.</p>
-<p>Only <code>https://</code>, <code>http://</code> and root-relative <code>/path</code> targets become links; any other scheme (e.g. <code>javascript:</code>, <code>ftp:</code>) is dropped and shown as plain text.</p>
-<p>Keep it short: an over-long line scrolls in the strip. The same formatting applies when editing a message above.</p>
-</aside>
-</div>
 </section>
 {{end}}
 {{- end}}
-- 
2.52.0


From 3b20abe0bd2d609ba0472f385a73ce5e9451c7eb Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 16 Jun 2026 00:35:11 +0200
Subject: [PATCH 4/9] feat(ads): banner under the header, continuous across
 navigation, robust fades
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Banner UX refinements (owner feedback):
- Position: render the banner inside Header (under the title) instead of in
  Screen, so it sits in the same place on every screen. In the game the grown
  nav's spare height now falls below the banner (banner under title, board
  pinned to the bottom) — it no longer jumps to the game area.
- Continuity: move the rotation into a persistent module engine
  (lib/bannerEngine) — the scheduler + timer live outside the components, so a
  navigation (which remounts the view) continues the cycle instead of restarting
  it. Each AdBanner only attaches as the DOM host and resyncs to the live message.
- Fades: a long, scrolling message now fades at both ends. The fade is a
  {#if} transition:fade layer, independent of the scroll (the inner track's
  transform), so the two no longer interfere.

Verified live (mock + Playwright): same position in lobby and game; the cycle
continues across lobby↔game; opacity sampling shows fade-out + fade-in for the
long message. Engine continuity unit-tested.
---
 docs/UI_DESIGN.md                 |  51 +++++++-------
 ui/src/components/AdBanner.svelte | 106 +++++++++++++++++-------------
 ui/src/components/Header.svelte   |  12 ++++
 ui/src/components/Screen.svelte   |   9 ---
 ui/src/lib/banner.test.ts         |  55 ++++++++++++++++
 ui/src/lib/bannerEngine.ts        |  72 ++++++++++++++++++++
 6 files changed, 230 insertions(+), 75 deletions(-)
 create mode 100644 ui/src/lib/bannerEngine.ts

diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md
index 28c8151..5d03720 100644
--- a/docs/UI_DESIGN.md
+++ b/docs/UI_DESIGN.md
@@ -12,12 +12,13 @@ runtime; opened outside Telegram, the `/telegram/` path redirects to the site ro
 
 ## Layout shell (`components/Screen.svelte`)
 
-A full-height flex column: the nav bar, the announcement strip, the content, and an
-optional bottom tab bar (the tab bar always sits at the screen bottom). On most screens
-the nav is minimal and the **content fills** between nav and tab bar. **Only in the
-game** (`growNav`) does the nav bar grow to absorb spare height (buttons top-aligned),
-pinning the board and controls to the **bottom** for thumb reach. Every screen except
-Login uses `Screen`.
+A full-height flex column: the nav bar, the content, and an optional bottom tab bar (the
+tab bar always sits at the screen bottom). The **advertising strip** is docked **inside the
+nav** (`Header`), directly under the title, so it sits in the same place on every screen. On
+most screens the nav is minimal and the **content fills** between nav and tab bar. **Only in
+the game** (`growNav`) does the nav bar grow to absorb spare height, so the strip stays under
+the title while the board and controls pin to the **bottom** for thumb reach. Every screen
+except Login uses `Screen`.
 
 ## Navigation
 
@@ -195,24 +196,30 @@ Login uses `Screen`.
   under-board slot shows the **Scores: N** preview. The screen **title** is the variant's
   display name (Scrabble / Скрэббл / Erudite / Эрудит), not a constant "Scrabble".
 
-## Advertising banner (`components/AdBanner.svelte`, `lib/banner.ts`)
+## Advertising banner (`components/AdBanner.svelte` in `components/Header.svelte`, `lib/banner.ts` + `lib/bannerEngine.ts`)
 
-A one-line inset strip under the nav bar, drawn on a dedicated `--ad-bg` token —
-a subtle accent, a touch darker than the surroundings in the light theme and a touch lighter
-in the dark theme, mapped to Telegram's `secondary_bg_color` inside the Mini App. Content is
-minimal markdown (text + links, escaped + linkified). It is **server-driven**: the campaigns and
-display timings ride the `profile.get` response (`app.profile.banner`, present only for an eligible
-viewer — see ARCHITECTURE §10), so `Screen` renders the strip only when that block is present, and
-a `notify` `banner` event re-fetches the profile to show or hide it in place.
+A one-line inset strip docked inside the nav bar, directly under the title (so its position never
+jumps between screens), drawn on a dedicated `--ad-bg` token — a subtle accent, a touch darker than
+the surroundings in the light theme and a touch lighter in the dark theme, mapped to Telegram's
+`secondary_bg_color` inside the Mini App. Content is minimal markdown (text + links, escaped +
+linkified). It is **server-driven**: the campaigns and display timings ride the `profile.get`
+response (`app.profile.banner`, present only for an eligible viewer — see ARCHITECTURE §10), so
+`Header` renders the strip only when that block is present, and a `notify` `banner` event re-fetches
+the profile to show or hide it in place.
 
-A **smooth weighted round-robin** (`createScheduler`) picks the next message: campaigns compete by
-their weight (each appears its weight share per cycle, evenly interleaved, not at random), and a
-campaign's own messages advance round-robin. The **rotator** then drives one message: it fades in
-(`fadeInMs`), holds `holdMs` (a message wider than the strip pauses `edgePauseMs`, scrolls to its
-right edge at `scrollPxPerSec`, pauses, and repeats while under `holdMs`), then — when more than one
-message exists — fades out (`fadeOutMs`), waits `gapMs`, and fades the next in. A lone message stays
-put (a long one keeps scrolling). All timings are operator-set (`/_gm/banner-settings`). Under
-**reduce-motion** the fades collapse to an instant swap and a long message does not scroll.
+The rotation runs in a **persistent module engine** (`lib/bannerEngine`): the scheduler and timer
+live outside the components, so navigating between screens (which remounts the view) **continues the
+cycle** rather than restarting it — each mounted `AdBanner` only attaches as the DOM host and resyncs
+to the live message. A **smooth weighted round-robin** (`createScheduler`) picks the next message:
+campaigns compete by their weight (each appears its weight share per cycle, evenly interleaved, not
+at random), and a campaign's own messages advance round-robin. One message fades in (`fadeInMs`),
+holds `holdMs` (a message wider than the strip pauses `edgePauseMs`, scrolls to its right edge at
+`scrollPxPerSec`, pauses, and repeats while under `holdMs`), then — with more than one message —
+fades out (`fadeOutMs`), waits `gapMs`, and the next fades in. The fade (a `{#if}` `transition:fade`
+layer) is independent of the scroll (the inner track's transform), so a long, scrolling message
+still fades at both ends. A lone message stays put (a long one keeps scrolling). All timings are
+operator-set (`/_gm/banner-settings`). Under **reduce-motion** the fades collapse to an instant swap
+and a long message does not scroll.
 
 ## Result / status iconography (`lib/result.ts`)
 
diff --git a/ui/src/components/AdBanner.svelte b/ui/src/components/AdBanner.svelte
index a49baa4..ae9faa8 100644
--- a/ui/src/components/AdBanner.svelte
+++ b/ui/src/components/AdBanner.svelte
@@ -1,5 +1,7 @@
 <script lang="ts">
-  import { createBannerRotator, defaultBannerTimings, linkify } from '../lib/banner';
+  import { fade } from 'svelte/transition';
+  import { attachBannerHost, configureBanner, detachBannerHost } from '../lib/bannerEngine';
+  import { defaultBannerTimings, linkify, type BannerHost } from '../lib/banner';
   import type { BannerCampaign, BannerTimings } from '../lib/model';
   import { onExternalLinkClick } from '../lib/telegram';
 
@@ -9,48 +11,57 @@
     reduceMotion = false,
   }: { campaigns: BannerCampaign[]; timings?: BannerTimings; reduceMotion?: boolean } = $props();
 
+  let visible = $state(false);
   let current = $state('');
-  let opacity = $state(0);
-  let opDur = $state(0); // opacity transition duration, ms (fade-in / fade-out)
   let tx = $state(0);
   let txDur = $state(0);
   let track = $state<HTMLElement>();
   let viewport = $state<HTMLElement>();
 
-  // Recreate the rotator whenever the campaigns, timings or reduce-motion change (a
-  // `banner` notify re-fetches the profile, swapping the campaigns in place). Under
-  // reduce-motion the fade/gap timings collapse to 0 (instant swap) and overflowPx
-  // reports 0 (no scroll).
+  // Effective timings: reduce-motion collapses the fades (instant swap) and, via overflowPx, the
+  // scroll. The rotation engine is configured with the same effective timings, so the fade
+  // transition durations here stay in step with the rotator's hold/transition scheduling.
+  const eff = $derived<BannerTimings>(
+    reduceMotion ? { ...timings, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 } : timings,
+  );
+
+  // The DOM host the rotation engine drives. The fade lives on the {#if visible} layer (Svelte's
+  // transition:fade — reliable and independent of the scroll), the scroll on the inner track's
+  // transform, so a long message's scroll never blocks its fade in/out.
+  const host: BannerHost = {
+    show(md) {
+      current = md;
+      tx = 0;
+      txDur = 0;
+      visible = true;
+    },
+    resetScroll() {
+      tx = 0;
+      txDur = 0;
+    },
+    hide() {
+      visible = false;
+    },
+    overflowPx() {
+      return reduceMotion ? 0 : Math.max(0, (track?.scrollWidth ?? 0) - (viewport?.clientWidth ?? 0));
+    },
+    scrollTo(toPx, durationMs) {
+      txDur = durationMs;
+      tx = -toPx;
+    },
+  };
+
+  // Attach this view to the persistent engine on mount (and resync to the live message); detach on
+  // unmount without stopping the engine, so navigation continues the cycle. Declared before the
+  // configure effect so the host is attached when the rotator first measures overflow.
   $effect(() => {
-    const cfg: BannerTimings = reduceMotion ? { ...timings, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 } : timings;
-    const rotator = createBannerRotator(campaigns, {
-      show: (md) => {
-        current = md;
-        tx = 0;
-        txDur = 0;
-        opDur = 0;
-        opacity = 0;
-        requestAnimationFrame(() => {
-          opDur = cfg.fadeInMs;
-          opacity = 1;
-        });
-      },
-      resetScroll: () => {
-        tx = 0;
-        txDur = 0;
-      },
-      hide: (durationMs) => {
-        opDur = durationMs;
-        opacity = 0;
-      },
-      overflowPx: () => (reduceMotion ? 0 : Math.max(0, (track?.scrollWidth ?? 0) - (viewport?.clientWidth ?? 0))),
-      scrollTo: (toPx, durationMs) => {
-        txDur = durationMs;
-        tx = -toPx;
-      },
-    }, cfg);
-    rotator.start();
-    return () => rotator.stop();
+    attachBannerHost(host);
+    return () => detachBannerHost(host);
+  });
+  // (Re)configure the engine when the campaigns or effective timings change; a no-op when
+  // unchanged, so a remount does not restart the rotation.
+  $effect(() => {
+    configureBanner(campaigns, eff);
   });
 </script>
 
@@ -59,13 +70,17 @@
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div class="ad" bind:this={viewport} onclick={onExternalLinkClick}>
-  <div
-    class="track"
-    bind:this={track}
-    style="transform:translateX({tx}px); opacity:{opacity}; transition:transform {txDur}ms linear, opacity {opDur}ms ease"
-  >
-    {@html linkify(current)}
-  </div>
+  {#if visible}
+    <div class="fadewrap" in:fade={{ duration: eff.fadeInMs }} out:fade={{ duration: eff.fadeOutMs }}>
+      <div
+        class="track"
+        bind:this={track}
+        style="transform:translateX({tx}px); transition:transform {txDur}ms linear"
+      >
+        {@html linkify(current)}
+      </div>
+    </div>
+  {/if}
 </div>
 
 <style>
@@ -81,13 +96,16 @@
     border-top: 1px solid var(--border);
     border-bottom: 1px solid var(--border);
     user-select: none;
+    /* A stable height so the strip does not collapse during the fade gap (the message layer is
+       removed between fade-out and fade-in). */
+    min-height: calc(0.85rem * 1.2 + 12px);
   }
   .track {
     display: inline-block;
     /* The side inset lives on the track (not the clipping .ad) so the scroll distance
        (scrollWidth - viewport.clientWidth) reaches the very end of a long message. */
     padding: 0 var(--pad);
-    will-change: transform, opacity;
+    will-change: transform;
   }
   .track :global(a) {
     color: var(--accent);
diff --git a/ui/src/components/Header.svelte b/ui/src/components/Header.svelte
index 0e11a25..de17518 100644
--- a/ui/src/components/Header.svelte
+++ b/ui/src/components/Header.svelte
@@ -3,7 +3,9 @@
   import { insideTelegram } from '../lib/telegram';
   import { connection } from '../lib/connection.svelte';
   import { t } from '../lib/i18n/index.svelte';
+  import { app } from '../lib/app.svelte';
   import Spinner from './Spinner.svelte';
+  import AdBanner from './AdBanner.svelte';
 
   let { title, back, grow = false }: { title: string; back?: string; grow?: boolean } = $props();
 
@@ -29,6 +31,16 @@
     <!-- A right-hand spacer balances the back button so the title stays centred. -->
     <span class="spacer"></span>
   </div>
+  <!-- The ad banner lives inside the nav, directly under the title bar, so it sits in the
+       same place on every screen — and in the game (grown nav) the spare height falls below
+       it (banner under the title, board pinned to the bottom). -->
+  {#if app.profile?.banner && app.profile.banner.campaigns.length}
+    <AdBanner
+      campaigns={app.profile.banner.campaigns}
+      timings={app.profile.banner.timings}
+      reduceMotion={app.reduceMotion}
+    />
+  {/if}
 </header>
 
 <style>
diff --git a/ui/src/components/Screen.svelte b/ui/src/components/Screen.svelte
index 0d16adb..f428b59 100644
--- a/ui/src/components/Screen.svelte
+++ b/ui/src/components/Screen.svelte
@@ -1,8 +1,6 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
   import Header from './Header.svelte';
-  import AdBanner from './AdBanner.svelte';
-  import { app } from '../lib/app.svelte';
   import { navigate } from '../lib/router.svelte';
 
   // The app-shell layout (all screens): the nav bar grows; the ad strip, content and
@@ -89,13 +87,6 @@
 
 <div class="screen">
   <Header {title} {back} grow={growNav} />
-  {#if app.profile?.banner && app.profile.banner.campaigns.length}
-    <AdBanner
-      campaigns={app.profile.banner.campaigns}
-      timings={app.profile.banner.timings}
-      reduceMotion={app.reduceMotion}
-    />
-  {/if}
   <main class="content" class:scroll class:fill={!growNav} class:column>{@render children?.()}</main>
   {#if tabbar}
     <nav class="tabbar">{@render tabbar()}</nav>
diff --git a/ui/src/lib/banner.test.ts b/ui/src/lib/banner.test.ts
index 26a9927..da5a237 100644
--- a/ui/src/lib/banner.test.ts
+++ b/ui/src/lib/banner.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createBannerRotator, createScheduler, defaultBannerTimings, linkify, type BannerHost } from './banner';
+import { attachBannerHost, configureBanner, detachBannerHost } from './bannerEngine';
 import type { BannerTimings } from './model';
 
 describe('linkify', () => {
@@ -165,3 +166,57 @@ describe('createBannerRotator', () => {
     r.stop();
   });
 });
+
+describe('bannerEngine', () => {
+  afterEach(() => vi.useRealTimers());
+
+  // A minimal host that records the messages it is told to show.
+  function engineHost(): { host: BannerHost; shown: string[] } {
+    const shown: string[] = [];
+    return {
+      shown,
+      host: { show: (md) => shown.push(md), resetScroll() {}, hide() {}, overflowPx: () => 0, scrollTo() {} },
+    };
+  }
+
+  const period = (c: BannerTimings) => c.fadeInMs + c.holdMs + c.fadeOutMs + c.gapMs + 5;
+
+  it('continues the cycle across a host detach/attach (does not restart)', () => {
+    vi.useFakeTimers();
+    const cfg: BannerTimings = { holdMs: 1000, edgePauseMs: 100, scrollPxPerSec: 200, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
+    const camps = [{ weight: 1, messages: ['x0'] }, { weight: 1, messages: ['x1'] }];
+    const a = engineHost();
+    configureBanner(camps, cfg);
+    attachBannerHost(a.host);
+    expect(a.shown).toEqual(['x0']); // resynced to the live message
+
+    // Swap the host mid-cycle (as navigation remounts the view): the new host resyncs to the
+    // same live message rather than restarting at the first.
+    detachBannerHost(a.host);
+    const b = engineHost();
+    attachBannerHost(b.host);
+    expect(b.shown).toEqual(['x0']);
+
+    // The sequence advances to the next message on the new host (it continued, not restarted).
+    vi.advanceTimersByTime(period(cfg));
+    expect(b.shown).toContain('x1');
+    detachBannerHost(b.host);
+  });
+
+  it('does not restart on a no-op reconfigure with unchanged data', () => {
+    vi.useFakeTimers();
+    const cfg: BannerTimings = { holdMs: 1000, edgePauseMs: 100, scrollPxPerSec: 200, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
+    const camps = [{ weight: 1, messages: ['y0'] }, { weight: 1, messages: ['y1'] }];
+    const a = engineHost();
+    configureBanner(camps, cfg);
+    attachBannerHost(a.host);
+    vi.advanceTimersByTime(period(cfg));
+    expect(a.shown).toEqual(['y0', 'y1']);
+
+    // Re-configuring with identical data keeps the running cycle (no fresh 'y0' burst).
+    configureBanner(camps, cfg);
+    vi.advanceTimersByTime(5);
+    expect(a.shown).toEqual(['y0', 'y1']);
+    detachBannerHost(a.host);
+  });
+});
diff --git a/ui/src/lib/bannerEngine.ts b/ui/src/lib/bannerEngine.ts
new file mode 100644
index 0000000..6758ab2
--- /dev/null
+++ b/ui/src/lib/bannerEngine.ts
@@ -0,0 +1,72 @@
+// A single, persistent banner rotation engine. The rotator and scheduler live here at module
+// scope, so the rotation keeps running across screen navigations: each screen mounts its own
+// AdBanner view, which only attaches as the DOM host. This makes the banner continuous and
+// independent of route transitions (the cycle is not restarted on navigation).
+
+import { createBannerRotator, type BannerHost, type Rotator } from './banner';
+import type { BannerCampaign, BannerTimings } from './model';
+
+let rotator: Rotator | null = null;
+let mounted: BannerHost | null = null;
+let current = '';
+let key = '';
+
+// proxy is the rotator's host: it records the current message (so a freshly-mounted view can
+// resync to it) and forwards every effect to the currently-attached DOM host, if any.
+const proxy: BannerHost = {
+  show(md) {
+    current = md;
+    mounted?.show(md);
+  },
+  resetScroll() {
+    mounted?.resetScroll();
+  },
+  hide(durationMs) {
+    mounted?.hide(durationMs);
+  },
+  overflowPx() {
+    return mounted?.overflowPx() ?? 0;
+  },
+  scrollTo(toPx, durationMs) {
+    mounted?.scrollTo(toPx, durationMs);
+  },
+};
+
+// bannerKey identifies a campaigns+timings set so configureBanner restarts the cycle only on a
+// real change, not on every (re)mount.
+function bannerKey(campaigns: BannerCampaign[], timings: BannerTimings): string {
+  return JSON.stringify({ campaigns, timings });
+}
+
+/**
+ * configureBanner (re)starts the rotation for the given campaigns and timings, or leaves the
+ * running rotation untouched when they are unchanged — so navigating between screens (which
+ * remounts the view with the same data) continues the cycle rather than restarting it.
+ */
+export function configureBanner(campaigns: BannerCampaign[], timings: BannerTimings): void {
+  const k = bannerKey(campaigns, timings);
+  if (k === key && rotator) return;
+  key = k;
+  rotator?.stop();
+  current = '';
+  rotator = createBannerRotator(campaigns, proxy, timings);
+  rotator.start();
+}
+
+/**
+ * attachBannerHost connects a freshly-mounted view as the DOM host and resyncs it to the live
+ * message, so the banner resumes mid-cycle instead of restarting.
+ */
+export function attachBannerHost(host: BannerHost): void {
+  mounted = host;
+  if (current) host.show(current);
+}
+
+/**
+ * detachBannerHost disconnects a view on unmount without stopping the engine. It clears the host
+ * only when it is still the current one, so an outgoing view leaving after the incoming view has
+ * already attached does not detach the new host (the transition briefly double-mounts).
+ */
+export function detachBannerHost(host: BannerHost): void {
+  if (mounted === host) mounted = null;
+}
-- 
2.52.0


From 5fb0daa7465b4ebf72efb35850012c1cc4acaebf Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 16 Jun 2026 05:45:38 +0200
Subject: [PATCH 5/9] fix(ads): banner truly continuous across navigation +
 re-measure on resize
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous engine kept the scheduler running but the view re-`show()`-ed the
current message on every (re)mount, replaying the fade on each navigation — which
looked like the cycle restarting (especially for a single message). Now:

- A mounted AdBanner reads the engine's live message (bannerCurrent) and renders
  it immediately, with no fade; attach no longer re-shows. Only a real advance
  fades. Verified: opacity stays 1.0 across a navigation, message preserved.
- The fade is manual opacity on a .fadewrap layer (not transition:fade), kept
  independent of the scroll (inner track transform), so a long message still
  fades at both ends and a {#key} remount cannot force an intro fade.
- A viewport size change (portrait↔landscape) re-measures the current message
  (remeasureBanner on resize/orientationchange, debounced) so the scroll
  re-evaluates for the new width — the owner accepts the restart on resize.
  Rotator gains restart(); engine gains bannerCurrent()/remeasureBanner().

Engine continuity + remeasure unit-tested.
---
 docs/UI_DESIGN.md                 | 24 ++++++----
 ui/src/components/AdBanner.svelte | 77 ++++++++++++++++++++-----------
 ui/src/lib/banner.test.ts         | 70 ++++++++++++++++++++--------
 ui/src/lib/banner.ts              |  8 ++++
 ui/src/lib/bannerEngine.ts        | 25 ++++++++--
 5 files changed, 144 insertions(+), 60 deletions(-)

diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md
index 5d03720..f95410b 100644
--- a/docs/UI_DESIGN.md
+++ b/docs/UI_DESIGN.md
@@ -209,16 +209,20 @@ the profile to show or hide it in place.
 
 The rotation runs in a **persistent module engine** (`lib/bannerEngine`): the scheduler and timer
 live outside the components, so navigating between screens (which remounts the view) **continues the
-cycle** rather than restarting it — each mounted `AdBanner` only attaches as the DOM host and resyncs
-to the live message. A **smooth weighted round-robin** (`createScheduler`) picks the next message:
-campaigns compete by their weight (each appears its weight share per cycle, evenly interleaved, not
-at random), and a campaign's own messages advance round-robin. One message fades in (`fadeInMs`),
-holds `holdMs` (a message wider than the strip pauses `edgePauseMs`, scrolls to its right edge at
-`scrollPxPerSec`, pauses, and repeats while under `holdMs`), then — with more than one message —
-fades out (`fadeOutMs`), waits `gapMs`, and the next fades in. The fade (a `{#if}` `transition:fade`
-layer) is independent of the scroll (the inner track's transform), so a long, scrolling message
-still fades at both ends. A lone message stays put (a long one keeps scrolling). All timings are
-operator-set (`/_gm/banner-settings`). Under **reduce-motion** the fades collapse to an instant swap
+cycle** rather than restarting it. A mounted `AdBanner` reads the engine's live message at init and
+renders it **immediately, without a fade** (`bannerCurrent`), and attaches only as the DOM host — so
+a screen change does not replay the fade; only a real message advance fades. A **smooth weighted
+round-robin** (`createScheduler`) picks the next message: campaigns compete by their weight (each
+appears its weight share per cycle, evenly interleaved, not at random), and a campaign's own messages
+advance round-robin. One message fades in (`fadeInMs`), holds `holdMs` (a message wider than the
+strip pauses `edgePauseMs`, scrolls to its right edge at `scrollPxPerSec`, pauses, and repeats while
+under `holdMs`), then — with more than one message — fades out (`fadeOutMs`), waits `gapMs`, and the
+next fades in. The fade (opacity on a `.fadewrap` layer) is independent of the scroll (the inner
+track's transform), so a long, scrolling message still fades at both ends. A lone message stays put
+(a long one keeps scrolling). A **viewport size change** (e.g. a portrait↔landscape rotation)
+re-measures the current message (`remeasureBanner`, debounced), so its scroll re-evaluates for the
+new width. All timings are operator-set (`/_gm/banner-settings`). Under **reduce-motion** the fades
+collapse to an instant swap
 and a long message does not scroll.
 
 ## Result / status iconography (`lib/result.ts`)
diff --git a/ui/src/components/AdBanner.svelte b/ui/src/components/AdBanner.svelte
index ae9faa8..b50d3c2 100644
--- a/ui/src/components/AdBanner.svelte
+++ b/ui/src/components/AdBanner.svelte
@@ -1,6 +1,11 @@
 <script lang="ts">
-  import { fade } from 'svelte/transition';
-  import { attachBannerHost, configureBanner, detachBannerHost } from '../lib/bannerEngine';
+  import {
+    attachBannerHost,
+    bannerCurrent,
+    configureBanner,
+    detachBannerHost,
+    remeasureBanner,
+  } from '../lib/bannerEngine';
   import { defaultBannerTimings, linkify, type BannerHost } from '../lib/banner';
   import type { BannerCampaign, BannerTimings } from '../lib/model';
   import { onExternalLinkClick } from '../lib/telegram';
@@ -11,36 +16,42 @@
     reduceMotion = false,
   }: { campaigns: BannerCampaign[]; timings?: BannerTimings; reduceMotion?: boolean } = $props();
 
-  let visible = $state(false);
-  let current = $state('');
+  // Initialise from the persistent engine's live message: a view mounted by navigation shows the
+  // current message immediately (opacity 1, no transition), so a screen change does not replay the
+  // fade — only a real message advance fades. Empty on the very first mount (engine not started).
+  let current = $state(bannerCurrent());
+  let opacity = $state(bannerCurrent() ? 1 : 0);
+  let opDur = $state(0);
   let tx = $state(0);
   let txDur = $state(0);
   let track = $state<HTMLElement>();
   let viewport = $state<HTMLElement>();
 
   // Effective timings: reduce-motion collapses the fades (instant swap) and, via overflowPx, the
-  // scroll. The rotation engine is configured with the same effective timings, so the fade
-  // transition durations here stay in step with the rotator's hold/transition scheduling.
+  // scroll. The engine is configured with the same effective timings, so the fade durations here
+  // stay in step with the rotator's hold/transition scheduling.
   const eff = $derived<BannerTimings>(
     reduceMotion ? { ...timings, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 } : timings,
   );
 
-  // The DOM host the rotation engine drives. The fade lives on the {#if visible} layer (Svelte's
-  // transition:fade — reliable and independent of the scroll), the scroll on the inner track's
-  // transform, so a long message's scroll never blocks its fade in/out.
+  // The DOM host the engine drives. Opacity (fade) lives on the .fadewrap layer and the transform
+  // (scroll) on the inner track, so a long message's scroll never blocks its fade in/out. show()
+  // fades in from the (already painted) faded-out state left by the preceding hide().
   const host: BannerHost = {
     show(md) {
       current = md;
       tx = 0;
       txDur = 0;
-      visible = true;
+      opDur = eff.fadeInMs;
+      opacity = 1;
     },
     resetScroll() {
       tx = 0;
       txDur = 0;
     },
     hide() {
-      visible = false;
+      opDur = eff.fadeOutMs;
+      opacity = 0;
     },
     overflowPx() {
       return reduceMotion ? 0 : Math.max(0, (track?.scrollWidth ?? 0) - (viewport?.clientWidth ?? 0));
@@ -51,18 +62,33 @@
     },
   };
 
-  // Attach this view to the persistent engine on mount (and resync to the live message); detach on
-  // unmount without stopping the engine, so navigation continues the cycle. Declared before the
-  // configure effect so the host is attached when the rotator first measures overflow.
+  // Attach to the persistent engine on mount, detach on unmount (without stopping it). Declared
+  // before configure so the host is attached when the rotator first measures overflow.
   $effect(() => {
     attachBannerHost(host);
     return () => detachBannerHost(host);
   });
   // (Re)configure the engine when the campaigns or effective timings change; a no-op when
-  // unchanged, so a remount does not restart the rotation.
+  // unchanged, so a remount continues the running cycle rather than restarting it.
   $effect(() => {
     configureBanner(campaigns, eff);
   });
+  // Re-measure on a viewport size change (e.g. a portrait↔landscape rotation): a message that fit
+  // may now overflow, or vice versa, so the scroll must be re-evaluated. Debounced.
+  $effect(() => {
+    let t: ReturnType<typeof setTimeout>;
+    const onResize = () => {
+      clearTimeout(t);
+      t = setTimeout(remeasureBanner, 250);
+    };
+    window.addEventListener('resize', onResize);
+    window.addEventListener('orientationchange', onResize);
+    return () => {
+      clearTimeout(t);
+      window.removeEventListener('resize', onResize);
+      window.removeEventListener('orientationchange', onResize);
+    };
+  });
 </script>
 
 <!-- The banner links are rendered via {@html}; a delegated click routes any of them through the
@@ -70,17 +96,15 @@
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div class="ad" bind:this={viewport} onclick={onExternalLinkClick}>
-  {#if visible}
-    <div class="fadewrap" in:fade={{ duration: eff.fadeInMs }} out:fade={{ duration: eff.fadeOutMs }}>
-      <div
-        class="track"
-        bind:this={track}
-        style="transform:translateX({tx}px); transition:transform {txDur}ms linear"
-      >
-        {@html linkify(current)}
-      </div>
+  <div class="fadewrap" style="opacity:{opacity}; transition:opacity {opDur}ms ease">
+    <div
+      class="track"
+      bind:this={track}
+      style="transform:translateX({tx}px); transition:transform {txDur}ms linear"
+    >
+      {@html linkify(current)}
     </div>
-  {/if}
+  </div>
 </div>
 
 <style>
@@ -96,9 +120,6 @@
     border-top: 1px solid var(--border);
     border-bottom: 1px solid var(--border);
     user-select: none;
-    /* A stable height so the strip does not collapse during the fade gap (the message layer is
-       removed between fade-out and fade-in). */
-    min-height: calc(0.85rem * 1.2 + 12px);
   }
   .track {
     display: inline-block;
diff --git a/ui/src/lib/banner.test.ts b/ui/src/lib/banner.test.ts
index da5a237..6eb0aa8 100644
--- a/ui/src/lib/banner.test.ts
+++ b/ui/src/lib/banner.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createBannerRotator, createScheduler, defaultBannerTimings, linkify, type BannerHost } from './banner';
-import { attachBannerHost, configureBanner, detachBannerHost } from './bannerEngine';
+import { attachBannerHost, bannerCurrent, configureBanner, detachBannerHost, remeasureBanner } from './bannerEngine';
 import type { BannerTimings } from './model';
 
 describe('linkify', () => {
@@ -181,42 +181,74 @@ describe('bannerEngine', () => {
 
   const period = (c: BannerTimings) => c.fadeInMs + c.holdMs + c.fadeOutMs + c.gapMs + 5;
 
-  it('continues the cycle across a host detach/attach (does not restart)', () => {
-    vi.useFakeTimers();
-    const cfg: BannerTimings = { holdMs: 1000, edgePauseMs: 100, scrollPxPerSec: 200, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
-    const camps = [{ weight: 1, messages: ['x0'] }, { weight: 1, messages: ['x1'] }];
-    const a = engineHost();
-    configureBanner(camps, cfg);
-    attachBannerHost(a.host);
-    expect(a.shown).toEqual(['x0']); // resynced to the live message
+  const cfg: BannerTimings = { holdMs: 1000, edgePauseMs: 100, scrollPxPerSec: 200, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
 
-    // Swap the host mid-cycle (as navigation remounts the view): the new host resyncs to the
-    // same live message rather than restarting at the first.
+  it('keeps the live message across a host detach/attach, and keeps advancing (continuity)', () => {
+    vi.useFakeTimers();
+    const camps = [{ weight: 1, messages: ['x0'] }, { weight: 1, messages: ['x1'] }];
+    configureBanner(camps, cfg);
+    const a = engineHost();
+    attachBannerHost(a.host);
+    // Advance mid-sequence so the live message is no longer the first.
+    vi.advanceTimersByTime(period(cfg));
+    expect(bannerCurrent()).toBe('x1');
+
+    // Remount the view (as navigation does): the live message is preserved (not reset to 'x0'),
+    // and a fresh view receives no replayed show() on attach (it reads bannerCurrent() itself).
     detachBannerHost(a.host);
     const b = engineHost();
     attachBannerHost(b.host);
-    expect(b.shown).toEqual(['x0']);
+    expect(bannerCurrent()).toBe('x1');
+    expect(b.shown).toEqual([]);
 
-    // The sequence advances to the next message on the new host (it continued, not restarted).
+    // The engine keeps advancing and drives the new host — the cycle continued, not restarted.
     vi.advanceTimersByTime(period(cfg));
-    expect(b.shown).toContain('x1');
+    expect(b.shown).toContain('x0');
+    expect(bannerCurrent()).toBe('x0');
     detachBannerHost(b.host);
   });
 
   it('does not restart on a no-op reconfigure with unchanged data', () => {
     vi.useFakeTimers();
-    const cfg: BannerTimings = { holdMs: 1000, edgePauseMs: 100, scrollPxPerSec: 200, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
     const camps = [{ weight: 1, messages: ['y0'] }, { weight: 1, messages: ['y1'] }];
-    const a = engineHost();
     configureBanner(camps, cfg);
+    const a = engineHost();
     attachBannerHost(a.host);
     vi.advanceTimersByTime(period(cfg));
-    expect(a.shown).toEqual(['y0', 'y1']);
+    expect(bannerCurrent()).toBe('y1');
 
-    // Re-configuring with identical data keeps the running cycle (no fresh 'y0' burst).
+    // Re-configuring with identical data keeps the running cycle (the live message is unchanged).
     configureBanner(camps, cfg);
     vi.advanceTimersByTime(5);
-    expect(a.shown).toEqual(['y0', 'y1']);
+    expect(bannerCurrent()).toBe('y1');
     detachBannerHost(a.host);
   });
+
+  it('re-presents the current message on remeasure, engaging the scroll on a size change', () => {
+    vi.useFakeTimers();
+    const big: BannerTimings = { ...cfg, holdMs: 5000 };
+    const shown: string[] = [];
+    let scrolled = 0;
+    let overflow = 0;
+    const host: BannerHost = {
+      show: (md) => shown.push(md),
+      resetScroll() {},
+      hide() {},
+      overflowPx: () => overflow,
+      scrollTo: () => scrolled++,
+    };
+    configureBanner([{ weight: 1, messages: ['z0'] }], big);
+    attachBannerHost(host);
+    vi.advanceTimersByTime(big.fadeInMs + 5); // initial measure: fits, no scroll
+    expect(scrolled).toBe(0);
+
+    // The viewport shrank so the message now overflows; remeasure re-presents it and the scroll
+    // engages (the owner accepts the cycle restarting on a size change).
+    overflow = 300;
+    remeasureBanner();
+    expect(shown).toContain('z0');
+    vi.advanceTimersByTime(big.fadeInMs + big.edgePauseMs + 5);
+    expect(scrolled).toBeGreaterThan(0);
+    detachBannerHost(host);
+  });
 });
diff --git a/ui/src/lib/banner.ts b/ui/src/lib/banner.ts
index 34fdb6e..9e3ded5 100644
--- a/ui/src/lib/banner.ts
+++ b/ui/src/lib/banner.ts
@@ -73,6 +73,9 @@ export interface BannerHost {
 export interface Rotator {
   start(): void;
   stop(): void;
+  /** Re-present the current message (re-measure overflow + restart its scroll), e.g. after the
+   *  viewport size changed. A no-op before start(). */
+  restart(): void;
 }
 
 /**
@@ -91,6 +94,7 @@ export function createBannerRotator(
   const sched = createScheduler(campaigns);
   let running = false;
   let cycleStart = 0;
+  let lastShown = ''; // the message currently presented, for restart() (re-measure)
   const timers: ReturnType<typeof setTimeout>[] = [];
 
   const at = (ms: number, fn: () => void) => {
@@ -104,6 +108,7 @@ export function createBannerRotator(
   function present(md: string) {
     if (!running) return;
     clear();
+    lastShown = md;
     host.show(md);
     at(config.fadeInMs, measure);
   }
@@ -151,6 +156,9 @@ export function createBannerRotator(
       running = false;
       clear();
     },
+    restart() {
+      if (running && lastShown) present(lastShown);
+    },
   };
 }
 
diff --git a/ui/src/lib/bannerEngine.ts b/ui/src/lib/bannerEngine.ts
index 6758ab2..1ea25f8 100644
--- a/ui/src/lib/bannerEngine.ts
+++ b/ui/src/lib/bannerEngine.ts
@@ -54,12 +54,31 @@ export function configureBanner(campaigns: BannerCampaign[], timings: BannerTimi
 }
 
 /**
- * attachBannerHost connects a freshly-mounted view as the DOM host and resyncs it to the live
- * message, so the banner resumes mid-cycle instead of restarting.
+ * bannerCurrent returns the message the engine is currently displaying (empty before the first
+ * one). A freshly-mounted view reads it to render the live message immediately, without a fade —
+ * so navigating between screens does not visibly restart the cycle.
+ */
+export function bannerCurrent(): string {
+  return current;
+}
+
+/**
+ * attachBannerHost connects a freshly-mounted view as the DOM host. It does NOT re-show the
+ * current message (the view renders it itself from bannerCurrent on mount): re-showing here would
+ * replay the fade-in on every navigation, which looks like the cycle restarting. The engine's own
+ * timer keeps driving show/hide for real message changes through this host.
  */
 export function attachBannerHost(host: BannerHost): void {
   mounted = host;
-  if (current) host.show(current);
+}
+
+/**
+ * remeasureBanner re-presents the current message (re-measuring overflow and restarting its
+ * scroll), for when the viewport size changed (e.g. a portrait↔landscape rotation) and a message
+ * that fit may now overflow, or vice versa.
+ */
+export function remeasureBanner(): void {
+  rotator?.restart();
 }
 
 /**
-- 
2.52.0


From dc582e9f730770c3d3a95037ea465c445cc5fd93 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 16 Jun 2026 06:09:35 +0200
Subject: [PATCH 6/9] fix(ads): restore reliable banner fades + keep banner on
 profile update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two regressions from the previous banner pass:

- Fade (#2): the manual-opacity fade could paint opacity 0 and 1 in one frame and
  skip the transition — most visible for a single (default) campaign message,
  whose only fade is the first show. Revert the fade to Svelte transition:fade
  (which forces the from-state, so even the first/only message fades), keeping it
  on its own {#if} layer independent of the scroll. A freshly-mounted view onto a
  running cycle still renders the live message instantly (inFade duration 0 once),
  so navigation does not replay the fade. Verified by opacity sampling: advances
  fade, navigation stays at opacity 1.

- Profile update (#3): the banner block was attached only to GET /profile, so a
  profile.update (e.g. a language switch) returned a profile without it and the
  banner vanished until reload. A shared profileResponse() now attaches the banner
  to GET, PUT and the link/merge profile responses. Regression test added
  (TestBannerSurvivesProfileUpdate).

Still open: the scroll position is not preserved across navigation (the view
remounts); discussed separately.
---
 .../internal/inttest/banner_console_test.go   | 26 +++++++++
 backend/internal/server/banner.go             | 10 ++++
 backend/internal/server/handlers_account.go   |  2 +-
 backend/internal/server/handlers_link.go      |  2 +-
 backend/internal/server/handlers_user.go      |  4 +-
 ui/src/components/AdBanner.svelte             | 57 ++++++++++++-------
 6 files changed, 75 insertions(+), 26 deletions(-)

diff --git a/backend/internal/inttest/banner_console_test.go b/backend/internal/inttest/banner_console_test.go
index 67ee9fa..8c33350 100644
--- a/backend/internal/inttest/banner_console_test.go
+++ b/backend/internal/inttest/banner_console_test.go
@@ -6,6 +6,7 @@ import (
 	"context"
 	"encoding/json"
 	"net/http"
+	"net/http/httptest"
 	"strings"
 	"testing"
 
@@ -247,3 +248,28 @@ func TestBannerProfileEligibility(t *testing.T) {
 		t.Fatal("a non-empty hint wallet still shows the banner")
 	}
 }
+
+// TestBannerSurvivesProfileUpdate guards that a profile update (e.g. a language switch) returns the
+// banner block too, so the client's profile keeps the banner instead of losing it until reload.
+func TestBannerSurvivesProfileUpdate(t *testing.T) {
+	srv, _ := bannerServer(t)
+	id := provisionAccount(t)
+
+	body := `{"display_name":"Tester","preferred_language":"ru","time_zone":"UTC","away_start":"00:00",` +
+		`"away_end":"00:00","block_chat":false,"block_friend_requests":false,"notifications_in_app_only":true}`
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut, "/api/v1/user/profile", strings.NewReader(body))
+	req.Header.Set("X-User-ID", id.String())
+	req.Header.Set("Content-Type", "application/json")
+	srv.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("update profile = %d: %s", rec.Code, rec.Body.String())
+	}
+	var p profileBanner
+	if err := json.Unmarshal(rec.Body.Bytes(), &p); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if p.Banner == nil || len(p.Banner.Campaigns) == 0 {
+		t.Fatalf("profile update dropped the banner block: %v", p.Banner)
+	}
+}
diff --git a/backend/internal/server/banner.go b/backend/internal/server/banner.go
index 1fa0f94..af91626 100644
--- a/backend/internal/server/banner.go
+++ b/backend/internal/server/banner.go
@@ -38,6 +38,16 @@ type bannerTimingsDTO struct {
 	FadeInMs       int `json:"fade_in_ms"`
 }
 
+// profileResponse builds the account's profile DTO with the advertising-banner block attached when
+// the viewer is eligible. Every endpoint returning the caller's own profile (get, update, link)
+// uses it, so the banner never drops off the client's profile after a non-get profile change (e.g.
+// a language switch).
+func (s *Server) profileResponse(ctx context.Context, acc account.Account) profileResponse {
+	r := profileResponseFor(acc)
+	r.Banner = s.bannerFor(ctx, acc)
+	return r
+}
+
 // bannerFor builds the advertising-banner block for the account's profile, or
 // nil when the ads service is not configured or the viewer is not eligible to
 // see a banner. The message language follows the account's bot (service)
diff --git a/backend/internal/server/handlers_account.go b/backend/internal/server/handlers_account.go
index 1bd974a..55ae838 100644
--- a/backend/internal/server/handlers_account.go
+++ b/backend/internal/server/handlers_account.go
@@ -83,7 +83,7 @@ func (s *Server) handleUpdateProfile(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	c.JSON(http.StatusOK, profileResponseFor(acc))
+	c.JSON(http.StatusOK, s.profileResponse(c.Request.Context(), acc))
 }
 
 // blockStatusResponse reports the caller's current block to the client. Until is an RFC3339 UTC
diff --git a/backend/internal/server/handlers_link.go b/backend/internal/server/handlers_link.go
index 27a318d..de37628 100644
--- a/backend/internal/server/handlers_link.go
+++ b/backend/internal/server/handlers_link.go
@@ -180,7 +180,7 @@ func (s *Server) profileFor(ctx context.Context, id uuid.UUID) *profileResponse
 	if err != nil {
 		return nil
 	}
-	p := profileResponseFor(acc)
+	p := s.profileResponse(ctx, acc)
 	return &p
 }
 
diff --git a/backend/internal/server/handlers_user.go b/backend/internal/server/handlers_user.go
index e46e408..bd5973a 100644
--- a/backend/internal/server/handlers_user.go
+++ b/backend/internal/server/handlers_user.go
@@ -23,9 +23,7 @@ func (s *Server) handleProfile(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	resp := profileResponseFor(acc)
-	resp.Banner = s.bannerFor(c.Request.Context(), acc)
-	c.JSON(http.StatusOK, resp)
+	c.JSON(http.StatusOK, s.profileResponse(c.Request.Context(), acc))
 }
 
 // submitPlayRequest places tiles on the player's turn; the engine infers the
diff --git a/ui/src/components/AdBanner.svelte b/ui/src/components/AdBanner.svelte
index b50d3c2..c5b5a05 100644
--- a/ui/src/components/AdBanner.svelte
+++ b/ui/src/components/AdBanner.svelte
@@ -1,4 +1,5 @@
 <script lang="ts">
+  import { fade } from 'svelte/transition';
   import {
     attachBannerHost,
     bannerCurrent,
@@ -17,41 +18,50 @@
   }: { campaigns: BannerCampaign[]; timings?: BannerTimings; reduceMotion?: boolean } = $props();
 
   // Initialise from the persistent engine's live message: a view mounted by navigation shows the
-  // current message immediately (opacity 1, no transition), so a screen change does not replay the
-  // fade — only a real message advance fades. Empty on the very first mount (engine not started).
+  // current message and is visible at once (no fade — see inFade), so a screen change does not
+  // replay the fade. Empty on the very first mount (engine not yet started).
   let current = $state(bannerCurrent());
-  let opacity = $state(bannerCurrent() ? 1 : 0);
-  let opDur = $state(0);
+  let visible = $state(bannerCurrent() !== '');
   let tx = $state(0);
   let txDur = $state(0);
   let track = $state<HTMLElement>();
   let viewport = $state<HTMLElement>();
 
+  // The first appearance after mounting onto an already-running cycle is instant; every later
+  // message change fades. (Consumed by the first in:fade.)
+  let instantOnce = bannerCurrent() !== '';
+
   // Effective timings: reduce-motion collapses the fades (instant swap) and, via overflowPx, the
-  // scroll. The engine is configured with the same effective timings, so the fade durations here
-  // stay in step with the rotator's hold/transition scheduling.
+  // scroll. The engine is configured with the same effective timings, so the fade durations stay in
+  // step with the rotator's hold/transition scheduling.
   const eff = $derived<BannerTimings>(
     reduceMotion ? { ...timings, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 } : timings,
   );
 
-  // The DOM host the engine drives. Opacity (fade) lives on the .fadewrap layer and the transform
-  // (scroll) on the inner track, so a long message's scroll never blocks its fade in/out. show()
-  // fades in from the (already painted) faded-out state left by the preceding hide().
+  // in:fade with a reliable from-state (Svelte forces opacity 0 → 1), so even the first message
+  // fades — unlike a bare opacity toggle, which can paint 0 and 1 in one frame and skip the fade.
+  // The resync mount renders the live message instantly (duration 0).
+  function inFade(node: Element) {
+    const duration = instantOnce ? 0 : eff.fadeInMs;
+    instantOnce = false;
+    return fade(node, { duration });
+  }
+
+  // The DOM host the engine drives. The fade lives on the {#if} layer (transition:fade), the scroll
+  // on the inner track's transform, so a long message's scroll never blocks its fade in/out.
   const host: BannerHost = {
     show(md) {
       current = md;
       tx = 0;
       txDur = 0;
-      opDur = eff.fadeInMs;
-      opacity = 1;
+      visible = true;
     },
     resetScroll() {
       tx = 0;
       txDur = 0;
     },
     hide() {
-      opDur = eff.fadeOutMs;
-      opacity = 0;
+      visible = false;
     },
     overflowPx() {
       return reduceMotion ? 0 : Math.max(0, (track?.scrollWidth ?? 0) - (viewport?.clientWidth ?? 0));
@@ -96,15 +106,17 @@
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div class="ad" bind:this={viewport} onclick={onExternalLinkClick}>
-  <div class="fadewrap" style="opacity:{opacity}; transition:opacity {opDur}ms ease">
-    <div
-      class="track"
-      bind:this={track}
-      style="transform:translateX({tx}px); transition:transform {txDur}ms linear"
-    >
-      {@html linkify(current)}
+  {#if visible}
+    <div class="fadewrap" in:inFade out:fade={{ duration: eff.fadeOutMs }}>
+      <div
+        class="track"
+        bind:this={track}
+        style="transform:translateX({tx}px); transition:transform {txDur}ms linear"
+      >
+        {@html linkify(current)}
+      </div>
     </div>
-  </div>
+  {/if}
 </div>
 
 <style>
@@ -120,6 +132,9 @@
     border-top: 1px solid var(--border);
     border-bottom: 1px solid var(--border);
     user-select: none;
+    /* A stable height so the strip does not collapse during the fade gap (the message layer is
+       removed between fade-out and fade-in). */
+    min-height: calc(0.85rem * 1.2 + 12px);
   }
   .track {
     display: inline-block;
-- 
2.52.0


From 9f83962bf75e6a60e8853e28087754e54b3d2ab5 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 16 Jun 2026 06:26:12 +0200
Subject: [PATCH 7/9] feat(ads): carry the banner scroll position across
 navigation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per the owner's idea: instead of moving the banner out of the per-screen header
(which would change its position), remember the banner's "life stage" and resume
it on the next screen. The engine already keeps the message + rotation timing;
this adds the scroll offset:

- bannerEngine tracks the in-flight scroll (target, duration, start). On attach,
  if a scroll is still running, it computes the current offset and calls the new
  host's resumeScroll(fromTx, toPx, remaining) — the view jumps to the carried
  offset and continues to the end over the remaining time, instead of restarting
  at the left.
- A finished scroll is left at its end; the rotator's own loop then takes over.

Verified: spot-checked in the browser (a long message at offset -785 resumes at
-788 on the next screen, not 0) and unit-tested (attach mid-scroll calls
resumeScroll with a partial offset and the remaining duration).
---
 ui/src/components/AdBanner.svelte | 10 ++++++++++
 ui/src/lib/banner.test.ts         | 28 +++++++++++++++++++++++++++-
 ui/src/lib/banner.ts              |  4 ++++
 ui/src/lib/bannerEngine.ts        | 23 +++++++++++++++++++++--
 4 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/ui/src/components/AdBanner.svelte b/ui/src/components/AdBanner.svelte
index c5b5a05..66e878f 100644
--- a/ui/src/components/AdBanner.svelte
+++ b/ui/src/components/AdBanner.svelte
@@ -70,6 +70,16 @@
       txDur = durationMs;
       tx = -toPx;
     },
+    resumeScroll(fromTx, toPx, durationMs) {
+      // Jump to the carried-over offset instantly, then continue to the end over the remaining
+      // time — so a long message keeps its scroll position across a navigation.
+      txDur = 0;
+      tx = fromTx;
+      requestAnimationFrame(() => {
+        txDur = durationMs;
+        tx = -toPx;
+      });
+    },
   };
 
   // Attach to the persistent engine on mount, detach on unmount (without stopping it). Declared
diff --git a/ui/src/lib/banner.test.ts b/ui/src/lib/banner.test.ts
index 6eb0aa8..d0b94f1 100644
--- a/ui/src/lib/banner.test.ts
+++ b/ui/src/lib/banner.test.ts
@@ -78,6 +78,7 @@ function recordingHost(overflow = 0): { host: BannerHost; calls: string[]; shown
       hide: () => calls.push('hide'),
       overflowPx: () => overflow,
       scrollTo: () => calls.push('scroll'),
+      resumeScroll: () => calls.push('resume'),
     },
   };
 }
@@ -175,7 +176,7 @@ describe('bannerEngine', () => {
     const shown: string[] = [];
     return {
       shown,
-      host: { show: (md) => shown.push(md), resetScroll() {}, hide() {}, overflowPx: () => 0, scrollTo() {} },
+      host: { show: (md) => shown.push(md), resetScroll() {}, hide() {}, overflowPx: () => 0, scrollTo() {}, resumeScroll() {} },
     };
   }
 
@@ -236,6 +237,7 @@ describe('bannerEngine', () => {
       hide() {},
       overflowPx: () => overflow,
       scrollTo: () => scrolled++,
+      resumeScroll() {},
     };
     configureBanner([{ weight: 1, messages: ['z0'] }], big);
     attachBannerHost(host);
@@ -251,4 +253,28 @@ describe('bannerEngine', () => {
     expect(scrolled).toBeGreaterThan(0);
     detachBannerHost(host);
   });
+
+  it('resumes a long message scroll mid-flight on a new host (navigation)', () => {
+    vi.useFakeTimers();
+    const big: BannerTimings = { holdMs: 10000, edgePauseMs: 100, scrollPxPerSec: 100, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
+    const noop: BannerHost = { show() {}, resetScroll() {}, hide() {}, overflowPx: () => 500, scrollTo() {}, resumeScroll() {} };
+    let resumed: { fromTx: number; toPx: number; dur: number } | null = null;
+    const b: BannerHost = { ...noop, resumeScroll: (fromTx, toPx, dur) => (resumed = { fromTx, toPx, dur }) };
+
+    configureBanner([{ weight: 1, messages: ['scrollme'] }], big);
+    attachBannerHost(noop);
+    // fadeIn(100) + edgePause(100) -> scrollTo (dur = 500/100*1000 = 5000ms); then 2000ms into it.
+    vi.advanceTimersByTime(big.fadeInMs + big.edgePauseMs + 2000);
+
+    // Remount mid-scroll: the new host resumes from ~40% of the way, not from the start.
+    detachBannerHost(noop);
+    attachBannerHost(b);
+    expect(resumed).not.toBeNull();
+    expect(resumed!.toPx).toBe(500);
+    expect(resumed!.fromTx).toBeLessThan(0); // already scrolled left of 0
+    expect(resumed!.fromTx).toBeGreaterThan(-500); // but not yet at the end
+    expect(resumed!.dur).toBeGreaterThan(0);
+    expect(resumed!.dur).toBeLessThan(5000); // only the remaining time
+    detachBannerHost(b);
+  });
 });
diff --git a/ui/src/lib/banner.ts b/ui/src/lib/banner.ts
index 9e3ded5..318c6f0 100644
--- a/ui/src/lib/banner.ts
+++ b/ui/src/lib/banner.ts
@@ -68,6 +68,10 @@ export interface BannerHost {
   overflowPx(): number;
   /** Animate the horizontal scroll to toPx over durationMs. */
   scrollTo(toPx: number, durationMs: number): void;
+  /** Resume an in-flight scroll on a freshly-mounted view: jump to fromTx (px, signed) instantly,
+   *  then continue to toPx over durationMs. Used by the engine on attach to carry the scroll
+   *  position across a navigation; the rotator itself never calls it. */
+  resumeScroll(fromTx: number, toPx: number, durationMs: number): void;
 }
 
 export interface Rotator {
diff --git a/ui/src/lib/bannerEngine.ts b/ui/src/lib/bannerEngine.ts
index 1ea25f8..4fcd0b2 100644
--- a/ui/src/lib/bannerEngine.ts
+++ b/ui/src/lib/bannerEngine.ts
@@ -10,15 +10,20 @@ let rotator: Rotator | null = null;
 let mounted: BannerHost | null = null;
 let current = '';
 let key = '';
+// The in-flight horizontal scroll of the current message, so a view mounted by navigation can
+// resume it from the same offset instead of restarting at the left. Null when not scrolling.
+let activeScroll: { toPx: number; dur: number; start: number } | null = null;
 
-// proxy is the rotator's host: it records the current message (so a freshly-mounted view can
-// resync to it) and forwards every effect to the currently-attached DOM host, if any.
+// proxy is the rotator's host: it records the current message + scroll (so a freshly-mounted view
+// can resume them) and forwards every effect to the currently-attached DOM host, if any.
 const proxy: BannerHost = {
   show(md) {
     current = md;
+    activeScroll = null;
     mounted?.show(md);
   },
   resetScroll() {
+    activeScroll = null;
     mounted?.resetScroll();
   },
   hide(durationMs) {
@@ -28,8 +33,12 @@ const proxy: BannerHost = {
     return mounted?.overflowPx() ?? 0;
   },
   scrollTo(toPx, durationMs) {
+    activeScroll = { toPx, dur: durationMs, start: Date.now() };
     mounted?.scrollTo(toPx, durationMs);
   },
+  resumeScroll(fromTx, toPx, durationMs) {
+    mounted?.resumeScroll(fromTx, toPx, durationMs);
+  },
 };
 
 // bannerKey identifies a campaigns+timings set so configureBanner restarts the cycle only on a
@@ -70,6 +79,16 @@ export function bannerCurrent(): string {
  */
 export function attachBannerHost(host: BannerHost): void {
   mounted = host;
+  // Resume the current message's scroll from where it had reached, so navigation does not restart
+  // a long message at the left. Only while a scroll is still in flight; a finished scroll is left
+  // at its end and the rotator's own loop takes over.
+  if (activeScroll) {
+    const elapsed = Date.now() - activeScroll.start;
+    if (elapsed < activeScroll.dur) {
+      const progress = elapsed / activeScroll.dur;
+      host.resumeScroll(-activeScroll.toPx * progress, activeScroll.toPx, activeScroll.dur - elapsed);
+    }
+  }
 }
 
 /**
-- 
2.52.0


From 115c92b39aae72dccd3c4051e85bf248430f7408 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 16 Jun 2026 06:39:12 +0200
Subject: [PATCH 8/9] fix(ads): pulse a lone banner message through the fade
 cycle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A single campaign message (e.g. the default campaign's one message) faded in once
on load and then sat frozen — the rotator only ran the fade/advance cycle when
more than one message existed, so with one message there were no further fades.
Drop the `total > 1` guards: every message now runs the full hold → fade-out →
gap → fade-in cycle, so a lone message pulses (the same message fades back in)
and a lone long message fades at each scroll-loop boundary. Multi-message
rotation is unchanged. Verified by opacity sampling (single message pulses
1→0→gap→0→1 without navigation); the single-message test now asserts the pulse.
---
 ui/src/lib/banner.test.ts |  8 +++++---
 ui/src/lib/banner.ts      | 11 ++++++-----
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/ui/src/lib/banner.test.ts b/ui/src/lib/banner.test.ts
index d0b94f1..88e4aa3 100644
--- a/ui/src/lib/banner.test.ts
+++ b/ui/src/lib/banner.test.ts
@@ -122,14 +122,16 @@ describe('createBannerRotator', () => {
     r.stop();
   });
 
-  it('shows a single message once and never fades it out', () => {
+  it('pulses a lone message through the fade cycle (fades out, then back in)', () => {
     vi.useFakeTimers();
     const { host, calls, shown } = recordingHost(0);
     const r = createBannerRotator([{ weight: 1, messages: ['solo'] }], host, cfg);
     r.start();
-    vi.advanceTimersByTime(cfg.fadeInMs + cfg.holdMs * 5);
     expect(shown).toEqual(['solo']);
-    expect(calls).not.toContain('hide');
+    vi.advanceTimersByTime(cfg.fadeInMs + cfg.holdMs); // hold elapses -> fade out
+    expect(calls).toContain('hide');
+    vi.advanceTimersByTime(cfg.fadeOutMs + cfg.gapMs + 1); // -> the same message fades back in
+    expect(shown).toEqual(['solo', 'solo']);
     r.stop();
   });
 
diff --git a/ui/src/lib/banner.ts b/ui/src/lib/banner.ts
index 318c6f0..03aa349 100644
--- a/ui/src/lib/banner.ts
+++ b/ui/src/lib/banner.ts
@@ -85,8 +85,8 @@ export interface Rotator {
 /**
  * createBannerRotator rotates the scheduled messages: each message fades in, holds
  * `holdMs` (an overflowing one scrolls to its right edge and back while under holdMs),
- * then — when more than one message exists — fades out over `fadeOutMs`, waits `gapMs`,
- * and fades the next one in. A single message stays put (a long one keeps scrolling).
+ * then fades out over `fadeOutMs`, waits `gapMs`, and fades the next one in. A lone
+ * message pulses (the same message fades back in) so the cycle keeps its rhythm.
  * Reduce-motion is handled by the host: pass zeroed fade timings and an overflowPx that
  * returns 0, and messages swap instantly without scrolling.
  */
@@ -125,8 +125,9 @@ export function createBannerRotator(
       scrollCycle(over);
       return;
     }
-    if (sched.total > 1) at(config.holdMs, advance);
-    // A single fitting message stays put.
+    // Hold, then run the fade cycle. A lone message pulses (fades out, then back in) rather than
+    // sitting frozen, so the banner keeps its rhythm even with a single campaign message.
+    at(config.holdMs, advance);
   }
 
   function scrollCycle(over: number) {
@@ -134,7 +135,7 @@ export function createBannerRotator(
     at(config.edgePauseMs, () => {
       host.scrollTo(over, dur);
       at(dur + config.edgePauseMs, () => {
-        if (sched.total > 1 && Date.now() - cycleStart >= config.holdMs) {
+        if (Date.now() - cycleStart >= config.holdMs) {
           advance();
         } else {
           host.resetScroll();
-- 
2.52.0


From dd45af20ef75ce7cbe605a2a3f3e70972f453055 Mon Sep 17 00:00:00 2001
From: Ilia Denisov <evilcart@gmail.com>
Date: Tue, 16 Jun 2026 07:18:50 +0200
Subject: [PATCH 9/9] fix(ads): fade the scroll rewind + keep the banner strip
 height constant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two polish fixes (owner feedback):

- Scroll loop: a long message that scrolled to its right edge rewound with a hard
  jump (no fade). It now runs the same fade as a message change at each rewind:
  fade out at the edge, reset the scroll while hidden, fade the same message back
  in, then scroll again.
- Strip height: during the fade gap the message layer is removed, which let the
  strip collapse by ~1-2px. An always-present invisible spacer now reserves one
  line of height and the message is overlaid absolutely, so the strip height is
  constant whether or not the message is showing.

Verified live: opacity sampling shows a full fade-out → gap → fade-in at each
scroll rewind (~every 6s), and the .ad height stays a single constant value
(30.31px) across the whole cycle including the gap. Loop-fade unit-tested.
---
 ui/src/components/AdBanner.svelte | 20 +++++++++++++++++---
 ui/src/lib/banner.test.ts         | 15 +++++++++++++++
 ui/src/lib/banner.ts              | 10 ++++++++--
 3 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/ui/src/components/AdBanner.svelte b/ui/src/components/AdBanner.svelte
index 66e878f..2a527fa 100644
--- a/ui/src/components/AdBanner.svelte
+++ b/ui/src/components/AdBanner.svelte
@@ -116,6 +116,10 @@
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div class="ad" bind:this={viewport} onclick={onExternalLinkClick}>
+  <!-- An always-present, invisible spacer reserves exactly one line of height, so the strip never
+       collapses while the message layer is absent during the fade gap (the message is overlaid
+       absolutely, so its presence/absence does not change the strip height). -->
+  <span class="reserve" aria-hidden="true">&nbsp;</span>
   {#if visible}
     <div class="fadewrap" in:inFade out:fade={{ duration: eff.fadeOutMs }}>
       <div
@@ -131,6 +135,7 @@
 
 <style>
   .ad {
+    position: relative;
     overflow: hidden;
     white-space: nowrap;
     padding: 6px 0;
@@ -142,9 +147,18 @@
     border-top: 1px solid var(--border);
     border-bottom: 1px solid var(--border);
     user-select: none;
-    /* A stable height so the strip does not collapse during the fade gap (the message layer is
-       removed between fade-out and fade-in). */
-    min-height: calc(0.85rem * 1.2 + 12px);
+  }
+  /* Reserves one line of height inside the padding so .ad keeps a constant height even during the
+     fade gap; invisible and non-interactive. */
+  .reserve {
+    visibility: hidden;
+  }
+  /* The message layer is overlaid on the reserved line, so showing/hiding it never resizes .ad. */
+  .fadewrap {
+    position: absolute;
+    top: 6px;
+    left: 0;
+    right: 0;
   }
   .track {
     display: inline-block;
diff --git a/ui/src/lib/banner.test.ts b/ui/src/lib/banner.test.ts
index 88e4aa3..78c0afa 100644
--- a/ui/src/lib/banner.test.ts
+++ b/ui/src/lib/banner.test.ts
@@ -135,6 +135,21 @@ describe('createBannerRotator', () => {
     r.stop();
   });
 
+  it('fades the scroll loop of a long message (out, rewind, in) instead of a hard reset', () => {
+    vi.useFakeTimers();
+    const c: BannerTimings = { holdMs: 30000, edgePauseMs: 100, scrollPxPerSec: 1000, fadeOutMs: 100, gapMs: 50, fadeInMs: 100 };
+    const { host, calls } = recordingHost(200); // overflows -> scroll dur = 200ms
+    const r = createBannerRotator([{ weight: 1, messages: ['long'] }], host, c);
+    r.start();
+    // fadeIn -> measure -> edgePause -> scrollTo -> (dur + edgePause) -> loop boundary
+    vi.advanceTimersByTime(c.fadeInMs + c.edgePauseMs + 200 + c.edgePauseMs + 5);
+    expect(calls).toContain('scroll');
+    expect(calls).toContain('hide'); // the loop fades out at the right edge (not a hard reset)
+    vi.advanceTimersByTime(c.fadeOutMs + c.gapMs + 5); // -> the same message fades back in
+    expect(calls.filter((x) => x === 'show').length).toBeGreaterThanOrEqual(2);
+    r.stop();
+  });
+
   it('swaps instantly when fade timings are zero (reduce-motion)', () => {
     vi.useFakeTimers();
     const zero: BannerTimings = { ...cfg, fadeOutMs: 0, gapMs: 0, fadeInMs: 0 };
diff --git a/ui/src/lib/banner.ts b/ui/src/lib/banner.ts
index 03aa349..3a09ac8 100644
--- a/ui/src/lib/banner.ts
+++ b/ui/src/lib/banner.ts
@@ -138,8 +138,14 @@ export function createBannerRotator(
         if (Date.now() - cycleStart >= config.holdMs) {
           advance();
         } else {
-          host.resetScroll();
-          scrollCycle(over);
+          // Loop the same message with a fade: fade out at the right edge, rewind to the start
+          // while hidden, fade the same message back in, then scroll again — so the rewind gets
+          // the same fade as a message change, not a hard jump.
+          host.hide(config.fadeOutMs);
+          at(config.fadeOutMs + config.gapMs, () => {
+            host.show(lastShown);
+            at(config.fadeInMs, () => scrollCycle(over));
+          });
         }
       });
     });
-- 
2.52.0