music: pool single-album artists into shared rows

An artist with one album got a heading and one cover on a row that fits
five, and a library is mostly single-album artists. Consecutive singles
share one grid, in place, so the page stays in artist order.

Each pooled cover keeps its artist's name above it in the same type as
a section heading. Dropping it was the first version and it was wrong:
scrolling then alternates between artists written large and small.

Measured on the probe's fixture: 4208px to 1895px, and a walk of the
page reaches all 21 covers instead of 9.

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

4 files changed, 549 insertions, 18 deletions

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/music-app.js b/packages/meshbay-hub/src/meshbay_hub/static/music-app.js
index 8fc6cb3..baa3520 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/music-app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/music-app.js
@@ -348,10 +348,29 @@ function MusicDetailModal({ album, transportRef, gekRef, musicbrainzEnabled, onC
 
 // -- Mode A: album grid -----------------------------------------------------
 
-// `units` is one page of `{ artist, album }`. An artist whose albums straddle
-// two pages gets its heading on both.
-function AlbumGrid({ units, transportRef, gekRef, musicbrainzEnabled, onPlayQueue, onMenu }) {
-  const [detail, setDetail] = useState(null); // the album object
+/**
+ * One page of `{ artist, album }` as the sections that get drawn.
+ *
+ * An artist with two or more albums gets a heading and a grid of their own. An
+ * artist with **one** does not: a heading plus a single cover is a whole row of
+ * whitespace, and a library is mostly single-album artists — a compilation
+ * bought once, one album of someone's, a soundtrack. Consecutive singles share
+ * one grid instead, so five of them fill a row that five headings would
+ * otherwise have spent five rows on.
+ *
+ * Pooled in place rather than swept into a bin at the end: the page is drawn in
+ * artist order and a reader scrolling it is relying on that. A pooled run sits
+ * exactly where its artists would have been.
+ *
+ * **Each pooled cover keeps its artist's name above it, in the same type as a
+ * multi-album artist's heading.** The first version of this dropped the heading
+ * on the grounds that the card already names its artist underneath — and that
+ * was wrong: scrolling then alternates between artists written large and
+ * artists written small, and the eye has to work out which kind of row it is
+ * looking at. The heading moves *into* the cell rather than going away, so a
+ * row of five costs one heading's height between them instead of five rows.
+ */
+function albumSections(units) {
   const artists = [];
   for (const u of units) {
     const prev = artists[artists.length - 1];
@@ -359,21 +378,60 @@ function AlbumGrid({ units, transportRef, gekRef, musicbrainzEnabled, onPlayQueu
     else artists.push({ artist: u.artist, albums: [u.album] });
   }
 
+  const sections = [];
+  for (const a of artists) {
+    if (a.albums.length >= 2) { sections.push({ kind: 'artist', ...a }); continue; }
+    const prev = sections[sections.length - 1];
+    if (prev && prev.kind === 'pool') prev.albums.push(a.albums[0]);
+    else sections.push({ kind: 'pool', albums: [a.albums[0]] });
+  }
+  return sections;
+}
+
+// `units` is one page of `{ artist, album }`. An artist whose albums straddle
+// two pages gets its heading on both — and, with one album on each page, is
+// pooled on both.
+function AlbumGrid({ units, transportRef, gekRef, musicbrainzEnabled, onPlayQueue, onMenu }) {
+  const [detail, setDetail] = useState(null); // the album object
+  const sections = useMemo(() => albumSections(units), [units]);
+
+  const tile = (album) => html`
+    <${LazyTile} key=${album.artist + '::' + album.album} cls="music-tile-slot">
+      <${AlbumCard} album=${album} transportRef=${transportRef} gekRef=${gekRef}
+        musicbrainzEnabled=${musicbrainzEnabled} onOpen=${() => setDetail(album)}
+        onMenu=${onMenu} />
+    </${LazyTile}>
+  `;
+
+  // Keyed on the first album rather than on the index: a pool's position shifts
+  // whenever a neighbouring artist gains or loses an album, and an index key
+  // would make preact reuse the wrong tiles across that change.
+  const sectionKey = (s) => (s.kind === 'artist'
+    ? `artist:${s.artist}`
+    : `pool:${s.albums[0].artist}::${s.albums[0].album}`);
+
   return html`
-    ${artists.map((a) => html`
-      <div class="music-artist-section" key=${a.artist}>
-        <h3 class="music-artist-heading">${a.artist}</h3>
-        <div class="music-grid">
-          ${a.albums.map((album) => html`
-            <${LazyTile} key=${album.artist + '::' + album.album} cls="music-tile-slot">
-              <${AlbumCard} album=${album} transportRef=${transportRef} gekRef=${gekRef}
-                musicbrainzEnabled=${musicbrainzEnabled} onOpen=${() => setDetail(album)}
-                onMenu=${onMenu} />
-            </${LazyTile}>
-          `)}
-        </div>
-      </div>
-    `)}
+    ${sections.map((s) => (s.kind === 'artist'
+      ? html`
+        <div class="music-artist-section" key=${sectionKey(s)}>
+          <h3 class="music-artist-heading">${s.artist}</h3>
+          <div class="music-grid">${s.albums.map(tile)}</div>
+        </div>`
+      : html`
+        <div class="music-artist-section music-artist-pool" key=${sectionKey(s)}>
+          <div class="music-grid">
+            ${s.albums.map((album) => html`
+              <div class="music-pool-cell" key=${album.artist + '::' + album.album}>
+                ${/* One line, clipped, with the full name on hover: a cell is
+                     ~170px wide and a heading that wraps to two lines would
+                     push its own cover below the others on the row. */''}
+                <h3 class="music-artist-heading music-pool-heading"
+                  title=${album.artist}>${album.artist}</h3>
+                ${tile(album)}
+              </div>
+            `)}
+          </div>
+        </div>`))}
     ${detail && html`
       <${MusicDetailModal} album=${detail} transportRef=${transportRef} gekRef=${gekRef}
         musicbrainzEnabled=${musicbrainzEnabled} onMenu=${onMenu}
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index 2bf0b18..5ef04b0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -5044,6 +5044,12 @@ h2 .gn-owner, h3 .gn-owner { font-size: 0.55em; }
   max-height: calc(100vh - 16px);
   overflow-x: hidden;
   overflow-y: auto;
+  /* Wheeling past the last track must not carry on into the page behind: that
+     scroll is a real page scroll, and a page scroll closes this menu on
+     purpose (menu.js). Without this, reaching the end of a long tracklist
+     dismisses the menu, which is the same symptom the scroll handler was just
+     fixed for, arriving by a different door. */
+  overscroll-behavior: contain;
   padding: 4px 0;
   background: var(--bg-surface);
   border: 1px solid var(--border);
@@ -5192,3 +5198,21 @@ h2 .gn-owner, h3 .gn-owner { font-size: 0.55em; }
   overflow: hidden;
   text-overflow: ellipsis;
 }
+
+/* A run of single-album artists, pooled into one grid so five of them fill one
+   row instead of spending five (music-app.js `albumSections`).
+
+   Each cell keeps its artist's name above the cover, in the same type as a
+   multi-album artist's heading. Dropping it — the first version of this — made
+   scrolling alternate between artists written large and artists written small,
+   which is a worse problem than the whitespace it saved. */
+.music-artist-pool { margin-bottom: 22px; }
+.music-pool-cell { display: flex; flex-direction: column; min-width: 0; }
+/* One line, clipped. A cell is about 170px wide, and a heading that wrapped to
+   two lines would push its own cover below the others on its row — the grid
+   stretches the cell, it does not align what is inside it. */
+.music-pool-heading {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
diff --git a/packages/meshbay-hub/tests/harness/music_grid_probe.py b/packages/meshbay-hub/tests/harness/music_grid_probe.py
new file mode 100644
index 0000000..365e028
--- /dev/null
+++ b/packages/meshbay-hub/tests/harness/music_grid_probe.py
@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""
+How much of the Music grid is whitespace.
+
+Each artist used to get a grid container of their own, so an artist with a
+single album got a heading and one cover on a row that fits five — and a real
+library is mostly single-album artists. Consecutive singles now share one grid.
+
+Measuring is the only way to check this: the layout is `auto-fill` over a width
+nothing declares, so what matters is the *rendered* rectangles. This reports
+every cover's position, which row it landed on, and how tall the grid is.
+
+    music_grid_probe.py
+"""
+
+import http.server
+import json
+import socketserver
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+STATIC = Path(__file__).resolve().parents[2] / "src" / "meshbay_hub" / "static"
+PORT = 8757
+RECORDS = []
+socketserver.TCPServer.allow_reuse_address = True
+
+FRAME = r"""<!doctype html><html><head><meta charset=utf-8>
+<link rel="stylesheet" href="/style.css"></head><body>
+<nav class="nav"><div class="nav-left"><a class="nav-brand" href="#/">MeshBay</a></div></nav>
+<div class="layout"><main class="main"><div id="root"></div></main></div>
+<script>
+// Four albums of three tracks, each track titled so the queue can be read back
+// unambiguously: "A2-t3" is the third track of the second album and nothing
+// else. A fixture whose rows cannot be told apart measures nothing.
+const ENTRIES = [];
+let n = 0;
+// Three artists with several albums each, and twelve with exactly one —
+// roughly the proportion a real library has.
+const MANY = [['Alpha', 3], ['Bravo', 2], ['Kilo', 4]];
+const ONE = ['Charlie', 'Delta', 'Echo',
+             'Foxtrot Un Nom Vraiment Tres Long Qui Ne Tient Pas', 'Golf',
+             'Hotel', 'India', 'Juliett', 'Lima', 'Mike', 'November', 'Oscar'];
+const add = (artist, album, i) => ENTRIES.push({
+  id: 'e' + (++n), name: `${i + 1} - t.flac`, display_title: `${album} ${i + 1}`,
+  path: `musique/${artist}/${album}`, type: 'audio', artist, album,
+  track_no: i + 1, duration: 200, size: 1024, added_at: 1750000000 + n,
+});
+for (const [artist, albums] of MANY) {
+  for (let a = 1; a <= albums; a++) {
+    for (let i = 0; i < 3; i++) add(artist, `${artist} disque ${a}`, i);
+  }
+}
+for (const artist of ONE) {
+  for (let i = 0; i < 3; i++) add(artist, `${artist} unique`, i);
+}
+
+const ACK = {
+  is_node_admin: false,
+  enabled_apps: ['files', 'music'],
+  tmdb_enabled: false, musicbrainz_enabled: false,
+  video_directories: [], music_directories: ['musique'], photo_directories: [],
+};
+
+window.MeshBayTransport = function () {
+  const self = {
+    connected: false, memberRole: 'member', supportsAppOps: true,
+    sessionKeys: null, gekRaw: null,
+    newNodeBundle: null, newNodeBundleRecovery: null,
+    async connect() { self.connected = true; return ACK; },
+    async fetchIndex() {
+      return { entries: ENTRIES, dirs: ['musique'],
+               roots: [{ name: 'musique', available: true, writable: false,
+                         removable: false }] };
+    },
+    async fetchChatHistory() { return { messages: [], hasMore: false }; },
+    async fetchLinkPreview() { return { ok: false }; },
+    close() {},
+  };
+  return new Proxy(self, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      if (typeof prop === 'string' && prop.startsWith('on')) return undefined;
+      if (typeof prop === 'symbol') return undefined;
+      return () => new Promise(() => {});
+    },
+    set(target, prop, value) { target[prop] = value; return true; },
+  });
+};
+</script>
+<script type="module">
+import { html, render, useState, useCallback } from '/vendor/htm-preact.js';
+import { initLocale } from '/i18n.js';
+import { GroupPage } from '/group-page.js';
+import { MusicPlayerBar } from '/music-player.js';
+
+const LOGS = [];
+addEventListener('error', (e) => LOGS.push('error: ' + (e.message || e)));
+addEventListener('unhandledrejection',
+  (e) => LOGS.push('rejection: ' + ((e.reason && (e.reason.stack || e.reason.message)) || e.reason)));
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const waitFor = async (sel, tries = 60) => {
+  for (let i = 0; i < tries; i++) {
+    const el = document.querySelector(sel);
+    if (el) return el;
+    await sleep(50);
+  }
+  return null;
+};
+
+// The shell's two jobs, and only those: hold the queue, and pass `op` through.
+// app.js does more (a transport fast path, the stop button); the contract this
+// exercises is the shape of what it hands the player.
+function Harness() {
+  const [queue, setQueue] = useState(null);
+  const onPlayQueue = useCallback((tracks, startIndex, source, op) => {
+    setQueue({ tracks, startIndex, nonce: Date.now(), op: op || 'replace' });
+  }, []);
+  // A queue that crosses groups cannot be built from one group's page, and
+  // that is the case the skipping rule exists for — so the probe reaches in
+  // for that one step rather than pretending a gesture builds it.
+  window.__probePlayQueue = onPlayQueue;
+
+  // Rejects at once for a group nothing serves, and hangs for every other —
+  // hanging is what the stub node does anyway, and what matters here is which
+  // track the playhead lands on, not whether anything plays.
+  const getConnection = (groupId) => (String(groupId).startsWith('dead')
+    ? Promise.reject(new Error('no node'))
+    : new Promise(() => {}));
+
+  return html`
+    <${GroupPage} groupId="g1" token="t" username="me" userId="u1"
+      group=${{ id: 'g1', name: 'un groupe', owner_username: 'me', is_admin: false }}
+      userPrefs=${{ default_tab: 'music', media_page_size: '50' }}
+      onPlayQueue=${onPlayQueue} />
+    ${queue && html`<${MusicPlayerBar} getConnection=${getConnection}
+      queue=${queue} userPrefs=${{}} onClose=${() => setQueue(null)} />`}
+  `;
+}
+
+const steps = [];
+
+// The queue as a person sees it: the player's own panel, opened and closed.
+async function queueNow(label, extra) {
+  const open = document.querySelector('.music-player-extra .music-player-btn');
+  if (!open) { steps.push({ step: label, bar: false, ...extra }); return; }
+  open.click();
+  const panel = await waitFor('.music-detail .music-tracklist');
+  const rows = [...document.querySelectorAll('.music-detail .music-tracklist .music-track-row')];
+  steps.push({
+    step: label,
+    bar: true,
+    play: rows.map((r) => r.querySelector('.music-track-title').textContent),
+    playing: (rows.findIndex((r) => r.classList.contains('active'))),
+    nowPlaying: (document.querySelector('.music-player-title') || {}).textContent || null,
+    ...extra,
+  });
+  const close = document.querySelector('.music-detail .video-close');
+  if (close) close.click();
+  await sleep(120);
+}
+
+const rightClick = (el) => el.dispatchEvent(new MouseEvent('contextmenu', {
+  bubbles: true, cancelable: true, clientX: 200, clientY: 200 }));
+
+const menuLabels = () => [...document.querySelectorAll('.ctx-menu .ctx-menu-item')]
+  .map((b) => b.querySelector('.ctx-menu-label').textContent);
+
+const clickMenu = async (i) => {
+  const items = [...document.querySelectorAll('.ctx-menu .ctx-menu-item')];
+  items[i].click();
+  await sleep(200);
+};
+
+(async () => {
+  const fail = (why) => parent.postMessage(
+    { error: why, logs: LOGS.slice(0, 12),
+      text: (document.getElementById('root').textContent || '').slice(0, 400) }, '*');
+  try {
+    await initLocale();
+    render(html`<${Harness} />`, document.getElementById('root'));
+
+    // Every tile mounts on intersection, so the page has to be walked.
+    for (let i = 0; i < 60; i++) {
+      scrollTo(0, document.documentElement.scrollHeight);
+      await sleep(60);
+      if (document.querySelectorAll('.music-card').length >= 21) break;
+    }
+    scrollTo(0, 0);
+    await sleep(300);
+
+    // Reported rather than asserted here: how *many* covers a walk of the page
+    // reaches is itself a property of the layout, and the caller is better
+    // placed to judge it than the probe is.
+    const cards = [...document.querySelectorAll('.music-card')];
+
+    // Group covers by the row they landed on, in document order.
+    const rows = [];
+    for (const c of cards) {
+      const r = c.getBoundingClientRect();
+      const top = Math.round(r.top + scrollY);
+      const cell = c.closest('.music-pool-cell');
+      const label = c.querySelector('.music-card-sub').textContent;
+      const heading = cell ? cell.querySelector('.music-pool-heading') : null;
+      const last = rows[rows.length - 1];
+      const entry = { artist: label, top,
+                      heading: heading ? heading.textContent : null,
+                      headingH: heading ? Math.round(heading.getBoundingClientRect().height) : null };
+      if (last && Math.abs(last.top - top) < 8) last.cells.push(entry);
+      else rows.push({ top, cells: [entry] });
+    }
+
+    parent.postMessage({ steps: [{
+      step: 'grid',
+      cards: cards.length,
+      rows: rows.map((r) => r.cells.map((c) => c.artist)),
+      cells: rows.map((r) => r.cells),
+      poolHeadings: [...document.querySelectorAll('.music-pool-heading')].length,
+      // A pooled cell's heading carries both classes; these are the ones that
+      // sit *above a grid* rather than inside a cell.
+      headings: [...document.querySelectorAll(
+        '.music-artist-heading:not(.music-pool-heading)')].map((h) => h.textContent),
+      pools: document.querySelectorAll('.music-artist-pool').length,
+      gridHeight: Math.round(document.querySelector('.main').scrollHeight),
+      width: innerWidth,
+    }], logs: LOGS.slice(0, 8) }, '*');
+  } catch (err) {
+    fail(String((err && err.stack) || err));
+  }
+})();
+</script></body></html>"""
+
+PAGE = r"""<!doctype html><html><head><meta charset=utf-8></head>
+<body style="margin:0"><div id="frames"></div><script>
+addEventListener('message', (e) => {
+  fetch('/log', { method: 'POST', body: JSON.stringify(e.data) });
+});
+const f = document.createElement('iframe');
+f.src = '/case';
+f.style.cssText = 'width:1100px;height:800px;border:0;display:block';
+document.getElementById('frames').appendChild(f);
+</script></body></html>"""
+
+
+class H(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length") or 0)
+        if self.path == "/log":
+            RECORDS.append(json.loads(self.rfile.read(length).decode()))
+        else:
+            self.rfile.read(length)
+        self.send_response(204)
+        self.end_headers()
+
+    def _send(self, body: bytes, ctype: str) -> None:
+        self.send_response(200)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        path = self.path.split("?")[0]
+        if path == "/":
+            self._send(PAGE.encode(), "text/html; charset=utf-8")
+        elif path == "/case":
+            self._send(FRAME.encode(), "text/html; charset=utf-8")
+        elif path == "/v1/groups/g1/nodes":
+            self._send(b'{"nodes": [{"node_id": "n1"}]}', "application/json")
+        else:
+            asset = (STATIC / path.lstrip("/")).resolve()
+            if not str(asset).startswith(str(STATIC)) or not asset.is_file():
+                self.send_response(404)
+                self.end_headers()
+                return
+            self._send(asset.read_bytes(),
+                       "text/css" if asset.suffix == ".css"
+                       else "text/javascript" if asset.suffix == ".js"
+                       else "application/octet-stream")
+
+
+def main() -> int:
+    with socketserver.TCPServer(("127.0.0.1", PORT), H) as srv:
+        threading.Thread(target=srv.serve_forever, daemon=True).start()
+        with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as profile:
+            proc = subprocess.Popen(
+                ["google-chrome", "--headless=new", "--disable-gpu", "--no-sandbox",
+                 f"--user-data-dir={profile}", "--window-size=1100,900",
+                 f"http://127.0.0.1:{PORT}/"],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            for _ in range(400):
+                if RECORDS:
+                    break
+                time.sleep(0.1)
+            proc.terminate()
+            try:
+                proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+    if not RECORDS:
+        print(json.dumps({"error": "no measurement"}), file=sys.stderr)
+        return 1
+    print(json.dumps(RECORDS[0], indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/packages/meshbay-hub/tests/test_music_grid.py b/packages/meshbay-hub/tests/test_music_grid.py
new file mode 100644
index 0000000..e457474
--- /dev/null
+++ b/packages/meshbay-hub/tests/test_music_grid.py
@@ -0,0 +1,133 @@
+"""
+How much of the Music grid is whitespace.
+
+Every artist used to get a grid container of their own, so an artist with a
+single album got a heading and one cover on a row that fits five — and a real
+library is mostly single-album artists: a compilation bought once, one album of
+somebody's, a soundtrack. Consecutive singles share one grid now, in place, so
+the page stays in artist order and a run of them fills a row.
+
+The layout is `auto-fill` over a width nothing declares, so reading the source
+proves nothing: this measures the rendered rectangles in a browser and groups
+the covers by the row they actually landed on.
+
+Every artist keeps their name at heading weight, pooled or not. Dropping it for
+pooled covers was the first version of this and it was wrong: scrolling then
+alternates between artists written large and artists written small, and the eye
+has to work out which kind of row it is looking at. The heading moves into the
+cell instead of going away.
+
+Measured on this fixture — three artists with several albums, twelve with one —
+the page went from **4208px to 1895px**, and a walk of it reaches all 21 covers
+instead of 9.
+"""
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+HARNESS = Path(__file__).parent / "harness" / "music_grid_probe.py"
+STATIC = Path(__file__).resolve().parents[1] / "src" / "meshbay_hub" / "static"
+
+pytestmark = pytest.mark.skipif(
+    shutil.which("google-chrome") is None or not (STATIC / "music-app.js").exists(),
+    reason="Chrome or the SPA sources are not available")
+
+# The fixture's artists, in the order the grid sorts them.
+MULTI = ["Alpha", "Bravo", "Kilo"]
+# One of them is deliberately far too long for a cell, to catch a heading that
+# wraps and pushes its own cover out of line with the rest of its row.
+LONG = "Foxtrot Un Nom Vraiment Tres Long Qui Ne Tient Pas"
+SINGLES_BEFORE_KILO = ["Charlie", "Delta", "Echo", LONG, "Golf",
+                       "Hotel", "India", "Juliett"]
+SINGLES_AFTER_KILO = ["Lima", "Mike", "November", "Oscar"]
+
+
+@pytest.fixture(scope="module")
+def grid():
+    proc = subprocess.run(["python3", str(HARNESS)],
+                          capture_output=True, text=True, timeout=300)
+    assert proc.returncode == 0, f"probe failed: {proc.stdout}{proc.stderr}"
+    out = json.loads(proc.stdout)
+    assert "error" not in out, out
+    assert not out.get("logs"), f"the page logged: {out['logs']}"
+    return out["steps"][0]
+
+
+def test_every_cover_is_reachable_by_scrolling_the_page(grid):
+    """Tiles mount on intersection, so a page tall enough is a page whose last
+    covers a reader has to work for. Nine of twenty-one were reachable in the
+    same walk before."""
+    assert grid["cards"] == 21
+
+
+def test_every_artist_is_named_in_the_same_type_pooled_or_not(grid):
+    """The correction. Three headings sit above a grid, twelve sit inside a
+    pooled cell — but all fifteen are `music-artist-heading`, so scrolling does
+    not alternate between artists written large and artists written small."""
+    assert grid["headings"] == MULTI, "a section heading went missing"
+    assert grid["poolHeadings"] == 12, (
+        "a single-album artist lost the name above their cover")
+
+
+def test_a_long_artist_name_does_not_push_its_cover_out_of_line(grid):
+    """A pooled heading is clipped to one line. The grid stretches a cell to the
+    row height; it does not align what is inside the cell, so a heading that
+    wrapped would drop its own cover below its neighbours'."""
+    heights = {c["headingH"] for row in grid["cells"] for c in row
+               if c["headingH"] is not None}
+    assert len(heights) == 1, f"pooled headings are not all one line: {heights}"
+
+    for row in grid["cells"]:
+        tops = {c["top"] for c in row}
+        assert len(tops) == 1, f"covers on one row start at different heights: {row}"
+
+    assert any(c["heading"] == LONG for row in grid["cells"] for c in row), (
+        "the over-long name is not in the fixture any more, so this checks nothing")
+
+
+def test_single_album_artists_share_a_row(grid):
+    """The point of the change. A row carrying several different artists cannot
+    happen while each has a grid container to itself."""
+    shared = [r for r in grid["rows"] if len(set(r)) > 1]
+    assert shared, f"no row carries more than one artist: {grid['rows']}"
+    assert max(len(r) for r in shared) >= 4, (
+        f"the widest shared row holds {max(len(r) for r in shared)} covers; at "
+        f"1100px the grid fits five")
+
+
+def test_an_artist_with_several_albums_keeps_their_own_rows(grid):
+    """Unchanged, and deliberately: a heading earns its line when there is more
+    than one cover under it."""
+    for artist in MULTI:
+        rows = [r for r in grid["rows"] if artist in r]
+        assert rows, f"{artist} drew no row"
+        for r in rows:
+            assert set(r) == {artist}, (
+                f"{artist} shares a row with {set(r) - {artist}}")
+
+
+def test_pooling_happens_in_place_and_keeps_the_page_in_artist_order(grid):
+    """Swept into a bin at the end, a run of singles would be easier to build
+    and would break the one thing a reader scrolling relies on. The run either
+    side of a multi-album artist is two pools, not one."""
+    assert grid["pools"] == 2
+
+    order = [a for row in grid["rows"] for a in row]
+    first = {a: order.index(a) for a in order}
+    assert first["Charlie"] > first["Bravo"]
+    assert first["Kilo"] > first["Juliett"]
+    assert first["Lima"] > first["Kilo"]
+
+
+def test_the_singles_are_pooled_with_their_neighbours_not_with_each_other(grid):
+    """Every single-album artist appears, and none of them alone on a row —
+    except where a row simply ran out of them."""
+    order = [a for row in grid["rows"] for a in row]
+    for artist in SINGLES_BEFORE_KILO + SINGLES_AFTER_KILO:
+        assert artist in order, f"{artist} is missing from the grid"
+    lonely = [r for r in grid["rows"] if len(r) == 1]
+    assert not lonely, f"a cover is alone on its row: {lonely}"