@doitian/dsh-music 0.1.4 → 0.1.5

package/lib/dj.js

@@ -17,10 +17,11 @@
  *      Without it the request reaches such a provider looking like an anonymous
  *      client that ignores its conventions.
  *   2. **Heuristic tier** — always available, no model required: NetEase's own
- *      signals (similar songs, daily recommendations, anonymous new-song feed,
- *      charts, keyword search) scored by artist affinity, novelty, and the
- *      listener's like/dislike/skip feedback, then interleaved so consecutive
- *      tracks do not share an artist.
+ *      signals (similar songs, personal FM, rested likes, daily
+ *      recommendations, anonymous new-song feed, charts, keyword search)
+ *      scored by mood match, artist affinity, and the listener's
+ *      like/dislike/skip feedback, then interleaved so consecutive tracks do
+ *      not share an artist.
  *
  * The DJ never blocks playback: every entry point resolves to a plan or to
  * `null`, and the caller keeps whatever is already queued.
@@ -28,7 +29,9 @@
  * @module dsh-music/dj
  */
 
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+
+import { Pacer, TtlCache, sampleInOrder } from './cache.js';
 
 /**
  * Render a model-tier failure so its stable code survives.
@@ -52,11 +55,79 @@ function describeFailure(error) {
 }
 
 /** Candidate pool handed to the model; keeps the prompt inside a small budget. */
-const MAX_POOL = 45;
+const MAX_POOL = 70;
 
-/** Only the first `MAX_SEEDS` history entries seed similarity expansion. */
+/** How many tracks seed similarity expansion. */
 const MAX_SEEDS = 4;
 
+/** How far back in the history a seed may come from, so seeds stay current. */
+const SEED_HISTORY = 20;
+
+/** Liked tracks offered back to the pool per plan. */
+const LIKED_SAMPLE = 6;
+
+/** A liked track played more recently than this is not offered back yet. */
+const LIKED_REST_MS = 3 * 24 * 60 * 60 * 1000;
+
+/**
+ * The order the pool is assembled in: a track two sources share is claimed by
+ * the earlier one, and the model reads the catalogue in this order.
+ */
+const ORIGINS = ['prompt', 'liked', 'fm', 'similar', 'daily', 'new', 'chart'];
+
+/**
+ * Tracks each source may contribute per plan. Every source gets a share, so
+ * no single one can crowd discovery out of the pool; without a brief they sum
+ * to 48, and a brief adds up to 23 that match it.
+ */
+const QUOTA = { promptPlaylists: 15, promptSongs: 8, similar: 14, daily: 8, new: 6, chart: 8 };
+
+const HOUR = 60 * 60 * 1000;
+
+/**
+ * How long each source is kept. Matched to how often it actually changes:
+ * similarity effectively never, a chart daily or weekly, the daily
+ * recommendations once a day. Personal FM is never cached, because every call
+ * answers something new.
+ */
+const TTL = {
+  similar: 24 * HOUR,
+  track: 24 * HOUR,
+  playlist: 12 * HOUR,
+  chart: 6 * HOUR,
+  search: 6 * HOUR,
+  daily: 3 * HOUR,
+  new: HOUR,
+  /** A brief's rewrite into search terms: what it means does not drift. */
+  terms: 7 * 24 * HOUR,
+  /** A brief that could not be rewritten is searched as written, and retried after this. */
+  termsRetry: HOUR / 2,
+};
+
+/** 飙升榜, 新歌榜, 原创榜, 热歌榜: the general charts, updated daily or weekly. */
+const CHARTS = [19723756, 3779629, 2884035, 3778678];
+
+/** How many of a brief's playlists are drawn from. */
+const BRIEF_PLAYLISTS = 3;
+
+/** How many search terms a brief is rewritten into. */
+const BRIEF_TERMS = 3;
+
+/** A playlist shorter than this is too thin to stand for a mood. */
+const MIN_PLAYLIST_TRACKS = 10;
+
+/** Personal FM calls per plan; NetEase answers three tracks per call. */
+const FM_CALLS = 2;
+
+/**
+ * A track skipped this often leaves the pool for good, like a dislike. One
+ * skip is only a penalty: it may have been the wrong moment, not the wrong song.
+ */
+const SKIPS_TO_EXCLUDE = 2;
+
+/** An artist is reported to the model as often skipped from this many skips. */
+const SKIPS_TO_REPORT_ARTIST = 2;
+
 /** Prefix for the minted curation identity, so logs and health read clearly. */
 const SESSION_ID_PREFIX = 'music-dj-';
 
@@ -132,6 +203,8 @@ export class AiDj {
    * @param {string} [options.sessionId] configured curation identity, overriding the minted one.
    * @param {{warn: Function, info: Function, debug: Function}} [options.logger]
    * @param {object} [options.model] `{ provider, model }` enabling the model tier.
+   * @param {() => number} [options.now] the source cache's clock, injectable for tests.
+   * @param {Pacer} [options.pacer] spaces out the NetEase requests a plan sends.
    */
   constructor({
     api,
@@ -142,6 +215,8 @@ export class AiDj {
     sessionId,
     logger,
     model = {},
+    now = Date.now,
+    pacer = new Pacer(),
   } = {}) {
     this.api = api;
     this.player = player;
@@ -172,6 +247,10 @@ export class AiDj {
     this.modelError = null;
     /** Guards against overlapping plans when a track ends mid-plan. */
     this.busy = false;
+    /** The sources' answers, each kept for as long as it plausibly stays the same. */
+    this.cache = new TtlCache({ now });
+    /** Every source request goes through this, so a plan never arrives as a burst. */
+    this.pacer = pacer;
   }
 
   /** Record a model-tier decline and carry on with the heuristic tier. */
@@ -285,58 +364,314 @@ export class AiDj {
 
   // ------------------------------------------------------------- candidates
 
+  /**
+   * The tracks similarity expands from: what is playing and what was recently
+   * heard through, topped up with likes when the history is thin.
+   *
+   * A rejected track never seeds. The ✕ records a dislike and then moves on, so
+   * seeding from the raw history would make the very next plan fetch more of
+   * exactly what was just turned down.
+   */
+  #seeds(digest) {
+    const rejected = (id) => this.store.taste(id) === 'disliked' || digest.skipCounts.has(id);
+    const seeds = [];
+    const offer = (id) => {
+      if (seeds.length < MAX_SEEDS && id && !rejected(id) && !seeds.includes(id)) seeds.push(id);
+    };
+    offer(this.player.current()?.id);
+    for (const entry of this.store.state.history.slice(0, SEED_HISTORY)) {
+      if (!entry.skipped) offer(entry.id);
+    }
+    for (const id of this.store.feedback.likes) offer(id);
+    return seeds;
+  }
+
+  /**
+   * A random handful of liked tracks that have rested long enough to be worth
+   * hearing again. A personal DJ that never returns to what the listener loves
+   * is only a discovery feed.
+   */
+  #likedSample(excluded) {
+    const restedSince = Date.now() - LIKED_REST_MS;
+    const heardRecently = new Set(
+      this.store.state.history.filter((entry) => (entry.at ?? 0) > restedSince).map((entry) => entry.id),
+    );
+    const ids = this.store.feedback.likes.filter((id) => !excluded.has(id) && !heardRecently.has(id));
+    return sampleInOrder(ids, LIKED_SAMPLE);
+  }
+
   /**
    * Gather a de-duplicated candidate pool from every available signal.
    *
    * Every source is independent and failure-tolerant: a source that throws or
    * needs a session the listener lacks contributes nothing.
    */
-  async #candidates({ prompt = '', count = 30 } = {}) {
+  async #candidates({ prompt = '' } = {}) {
     const digest = this.store.tasteDigest();
-    const excluded = new Set([...digest.dislikedIds, ...digest.recentIds]);
+    // Queued tracks are excluded too: a batch is appended, and a pick the queue
+    // already holds is dropped there, so the batch would silently come up short.
+    const excluded = new Set([
+      ...digest.dislikedIds,
+      ...digest.recentIds,
+      ...this.player.queue.map((track) => track.id),
+      ...[...digest.skipCounts].filter(([, skips]) => skips >= SKIPS_TO_EXCLUDE).map(([id]) => id),
+    ]);
+    const brief = prompt.trim();
+    const seeds = this.#seeds(digest);
+    // Every source is fetched at once and fails alone; the pool is then
+    // assembled in priority order, so a track two sources share is claimed by
+    // the one that ranks it higher, however the requests happened to finish.
+    const settled = (promise) => promise.catch(() => []);
+    const briefing = brief ? this.#briefTracks(brief, excluded).catch(() => ({ tracks: [], terms: [brief] })) : null;
+    const sources = {
+      prompt: brief ? settled(briefing.then((result) => result.tracks)) : [],
+      liked: settled(this.#tracksByIds(this.#likedSample(excluded))),
+      fm: settled(this.#fmTracks()),
+      similar: settled(this.#similarTracks(seeds, excluded)),
+      daily: settled(this.#feedTracks(`daily:${this.#account()}`, TTL.daily, () => this.api.recommendSongs(30), QUOTA.daily, excluded)),
+      new: settled(this.#feedTracks('new', TTL.new, () => this.api.personalizedNewsongs(30), QUOTA.new, excluded)),
+      chart: settled(this.#chartTracks(excluded)),
+    };
+
     const pool = [];
     const seen = new Set();
-    const add = (tracks, origin) => {
-      for (const track of tracks ?? []) {
+    for (const origin of ORIGINS) {
+      for (const track of await sources[origin]) {
         if (!track?.id || seen.has(track.id) || excluded.has(track.id)) continue;
         seen.add(track.id);
         pool.push({ ...track, origin });
       }
-    };
+    }
+    const trimmed = pool.slice(0, MAX_POOL);
+    // Covers cost a request only when some track came without one.
+    const covered = trimmed.some((track) => !track.picUrl)
+      ? await this.pacer.run(() => this.api.withCovers(trimmed)).catch(() => trimmed)
+      : trimmed;
+    return { pool: covered, digest, terms: briefing ? (await briefing).terms : [] };
+  }
 
-    const current = this.player.current();
-    const seeds = [current?.id, ...this.store.recentIds(MAX_SEEDS)].filter(Boolean).slice(0, MAX_SEEDS);
+  /**
+   * Who the personal sources belong to. The cookie, not the account record,
+   * because the record is fetched after a sign-in and would briefly read the
+   * same for two different people. Only a digest of it is ever kept.
+   */
+  #account() {
+    const cookie = this.api.jar?.get?.('MUSIC_U');
+    if (cookie) return createHash('sha256').update(cookie).digest('hex').slice(0, 12);
+    return this.api.authenticated ? 'session' : 'anonymous';
+  }
 
-    const tasks = [];
-    // Similarity expansion from what is playing and what was played recently.
-    for (const seed of seeds) {
-      tasks.push(
-        this.api.simiSongs(seed, { limit: 12 }).then((tracks) => add(tracks, 'similar')).catch(() => {}),
-      );
+  /** Track details by id, each cached on its own so a sample costs only the misses. */
+  async #tracksByIds(ids) {
+    if (ids.length === 0 || !this.api.songDetail) return [];
+    const missing = ids.filter((id) => this.cache.peek(`track:${id}`) === undefined);
+    if (missing.length > 0) {
+      for (const track of await this.pacer.run(() => this.api.songDetail(missing))) {
+        if (track?.id) this.cache.set(`track:${track.id}`, track, TTL.track);
+      }
     }
-    // A mood brief is a search term; the raw text searches well enough.
-    if (prompt.trim()) {
-      tasks.push(
-        this.api.searchSongs(prompt.trim(), { limit: 15 }).then((r) => add(r.tracks, 'prompt')).catch(() => {}),
-      );
+    return ids.map((id) => this.cache.peek(`track:${id}`)).filter(Boolean);
+  }
+
+  /** A cached list, sampled down to its quota of eligible tracks. */
+  async #feedTracks(key, ttlMs, load, quota, excluded) {
+    const tracks = await this.cache.get(key, ttlMs, () => this.pacer.run(load));
+    return sampleInOrder((tracks ?? []).filter((track) => track?.id && !excluded.has(track.id)), quota);
+  }
+
+  /** Personal FM answers a different three on every call, so it is never cached. */
+  async #fmTracks() {
+    if (!this.api.authenticated || !this.api.personalFm) return [];
+    const calls = Array.from({ length: FM_CALLS }, () => this.pacer.run(() => this.api.personalFm()).catch(() => []));
+    return (await Promise.all(calls)).flat();
+  }
+
+  /**
+   * Similar tracks for each seed. Every eligible track of the first seed — the
+   * one playing — is kept, and the other seeds share what is left of the quota.
+   */
+  async #similarTracks(seeds, excluded) {
+    const lists = await Promise.all(
+      seeds.map((seed) =>
+        this.cache
+          .get(`similar:${seed}`, TTL.similar, () => this.pacer.run(() => this.api.simiSongs(seed, { limit: 20 })))
+          .catch(() => []),
+      ),
+    );
+    const eligible = (tracks) => (tracks ?? []).filter((track) => track?.id && !excluded.has(track.id));
+    const [first = [], ...rest] = lists.map(eligible);
+    const lead = first.slice(0, QUOTA.similar);
+    return [...lead, ...sampleInOrder(rest.flat(), QUOTA.similar - lead.length)];
+  }
+
+  /**
+   * One playlist's track ids and whatever full tracks came with them, cached.
+   *
+   * For a playlist the account does not own NetEase returns full tracks only
+   * for the first 20, but every id. Sampling from the ids is what reaches the
+   * rest of a 100-track playlist, rather than serving its first 20 forever.
+   */
+  async #playlist(id, ttlMs) {
+    const playlist = await this.cache.get(`playlist:${id}`, ttlMs, () =>
+      this.pacer.run(() => this.api.playlistDetail(id, { limit: 1000 })),
+    );
+    const tracks = playlist?.tracks ?? [];
+    return {
+      ids: playlist?.trackIds?.length ? playlist.trackIds : tracks.map((track) => track.id),
+      known: new Map(tracks.map((track) => [track.id, track])),
+    };
+  }
+
+  /** Sample eligible ids from playlists, resolving only those that came without details. */
+  async #samplePlaylists(playlists, quota, excluded) {
+    const known = new Map();
+    const ids = [];
+    for (const playlist of playlists) {
+      for (const [id, track] of playlist.known) known.set(id, track);
+      for (const id of playlist.ids) if (!excluded.has(id) && !ids.includes(id)) ids.push(id);
     }
-    // Editorial and anonymous feeds keep the pool from collapsing to one genre.
-    tasks.push(this.api.recommendSongs(20).then((tracks) => add(tracks, 'daily')).catch(() => {}));
-    tasks.push(this.api.personalizedNewsongs(15).then((tracks) => add(tracks, 'new')).catch(() => {}));
-    tasks.push(
-      this.api
-        .playlistDetail('3778678', { limit: 40 })
-        .then((playlist) => add(playlist.tracks, 'chart'))
-        .catch(() => {}),
+    const chosen = sampleInOrder(ids, quota);
+    const resolved = await this.#tracksByIds(chosen.filter((id) => !known.has(id))).catch(() => []);
+    for (const track of resolved) known.set(track.id, track);
+    return chosen.map((id) => known.get(id)).filter(Boolean);
+  }
+
+  /**
+   * A sample across the four general charts. One chart alone served the same
+   * forty hits every plan; the genre charts are left out because a classical
+   * or rap chart is as likely to be off-taste as on it.
+   */
+  async #chartTracks(excluded) {
+    const charts = await Promise.all(CHARTS.map((id) => this.#playlist(id, TTL.chart).catch(() => null)));
+    return this.#samplePlaylists(charts.filter(Boolean), QUOTA.chart, excluded);
+  }
+
+  /**
+   * Tracks for a mood brief. Song search only matches titles and lyrics, so a
+   * mood mostly finds tracks literally named after it; listeners name and tag
+   * playlists by mood, so the brief's best-loved playlists carry most of it.
+   *
+   * @returns {Promise<{tracks: object[], terms: string[]}>}
+   */
+  async #briefTracks(brief, excluded) {
+    const terms = await this.#briefTerms(brief);
+    const songs = this.#feedTracks(
+      `songs:${terms[0]}`,
+      TTL.search,
+      () => this.api.searchSongs(terms[0], { limit: 30 }).then((result) => result.tracks),
+      QUOTA.promptSongs,
+      excluded,
+    ).catch(() => []);
+    const playlists = (async () => {
+      if (!this.api.searchPlaylists) return [];
+      // Every term gets its share, so one broad term cannot take every slot.
+      const perTerm = Math.ceil(BRIEF_PLAYLISTS / terms.length);
+      const found = await Promise.all(
+        terms.map((term) =>
+          this.cache
+            .get(`playlists:${term}`, TTL.search, () => this.pacer.run(() => this.api.searchPlaylists(term, { limit: 10 })))
+            .catch(() => []),
+        ),
+      );
+      // Among the most relevant few, the most played: relevance alone surfaces
+      // a 14-track playlist nobody listens to as readily as a curated one.
+      const chosen = new Map();
+      for (const results of found) {
+        const best = results
+          .slice(0, 6)
+          .filter((playlist) => playlist.trackCount >= MIN_PLAYLIST_TRACKS && !chosen.has(playlist.id))
+          .sort((a, b) => b.playCount - a.playCount)
+          .slice(0, perTerm);
+        for (const playlist of best) chosen.set(playlist.id, playlist);
+      }
+      const ids = [...chosen.keys()].slice(0, BRIEF_PLAYLISTS);
+      const loaded = await Promise.all(ids.map((id) => this.#playlist(id, TTL.playlist).catch(() => null)));
+      return this.#samplePlaylists(loaded.filter(Boolean), QUOTA.promptPlaylists, excluded);
+    })().catch(() => []);
+    // Playlist tracks first: they are the stronger match for a mood.
+    return { tracks: [...(await playlists), ...(await songs)], terms };
+  }
+
+  /**
+   * The search terms a brief is looked up by: the model's rewrite when there is
+   * one, the brief as written otherwise.
+   *
+   * NetEase playlists are named in Chinese, so an English brief matches badly —
+   * "90s cantopop" finds 90s hip-hop. One model call turns the brief into the
+   * terms a listener would name such a playlist, and it is made once per brief,
+   * not per plan: a brief means the same thing next week. A brief that could
+   * not be rewritten is searched as written, and retried after a while rather
+   * than on every plan.
+   *
+   * @returns {Promise<string[]>}
+   */
+  #briefTerms(brief) {
+    const key = `terms:${brief}`;
+    const cached = this.cache.peek(key);
+    if (cached !== undefined) return cached;
+    const pending = this.#rewriteBrief(brief).then(
+      (terms) => {
+        if (!terms) {
+          this.cache.set(key, Promise.resolve([brief]), TTL.termsRetry);
+          return [brief];
+        }
+        this.cache.set(key, Promise.resolve(terms), TTL.terms);
+        this.logger?.info?.(`[music] DJ brief "${brief}" will be searched as: ${terms.join('; ')}`);
+        return terms;
+      },
+      (error) => {
+        this.logger?.warn?.(`[music] DJ brief could not be rewritten, searching it as written: ${describeFailure(error)}`);
+        this.cache.set(key, Promise.resolve([brief]), TTL.termsRetry);
+        return [brief];
+      },
     );
-    await Promise.all(tasks);
+    this.cache.set(key, pending, TTL.termsRetry);
+    return pending;
+  }
 
-    // Keep the prompt cheap when the pool overflowed: prefer prompt/similar
-    // matches, then the feeds.
-    const priority = { prompt: 0, similar: 1, daily: 2, new: 3, chart: 4 };
-    pool.sort((a, b) => (priority[a.origin] ?? 9) - (priority[b.origin] ?? 9));
-    const trimmed = pool.slice(0, Math.max(count, MAX_POOL));
-    return { pool: await this.api.withCovers(trimmed).catch(() => trimmed), digest };
+  /**
+   * Ask the model for a brief's search terms, on the same route and under the
+   * same identity as curation.
+   *
+   * @returns {Promise<string[] | null>} `null` when no model route is available.
+   * @throws {Error} when the model answered with nothing usable.
+   */
+  async #rewriteBrief(brief) {
+    const llm = this.resolveLlm?.();
+    if (!llm?.stream) return null;
+    const target = await this.#resolveTarget(llm);
+    if (!target?.provider || !target?.model) return null;
+    const request = curationRequest({
+      target,
+      sessionId: this.sessionId,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'text',
+              text:
+                "Rewrite a listener's music brief into short search keywords for NetEase Cloud Music playlist search. " +
+                `Give up to ${BRIEF_TERMS} keywords, each 2 to 8 words, the way listeners name playlists there: ` +
+                'in Chinese, by genre, mood, era, language or scene; keep an artist or genre name in its usual form. ' +
+                'Each keyword should find the brief on its own. ' +
+                'Reply with JSON only, no prose, no code fence: {"terms":["<keyword>"]}',
+            },
+            { type: 'text', text: `Brief: ${brief}` },
+          ],
+        },
+      ],
+    });
+    const text = await this.#collect(llm.stream(request));
+    const json = /\{[\s\S]*\}/.exec(text ?? '');
+    if (!json) throw new Error('the rewrite contained no JSON object');
+    const terms = (JSON.parse(json[0]).terms ?? [])
+      .filter((term) => typeof term === 'string')
+      .map((term) => term.trim())
+      .filter((term) => term.length > 0 && term.length <= 40);
+    const unique = [...new Set(terms)].slice(0, BRIEF_TERMS);
+    if (unique.length === 0) throw new Error('the model returned no search terms');
+    return unique;
   }
 
   // --------------------------------------------------------------- model tier
@@ -438,17 +773,30 @@ export class AiDj {
    * One place builds the prompt, so a leaf call and any future caller reason
    * about exactly the same brief.
    */
-  #brief({ pool, digest, prompt, count }) {
+  #brief({ pool, digest, prompt, count, follows }) {
+    const label = (track) => `${track.name} — ${(track.artists ?? []).join('/')}`;
     const catalogue = pool
-      .map((track, index) => `${index}. ${track.name} — ${(track.artists ?? []).join('/')}${track.album ? ` (${track.album})` : ''}`)
+      .map((track, index) =>
+        `${index}. ${label(track)}${track.album ? ` (${track.album})` : ''}${track.origin === 'liked' ? ' [liked]' : ''}`)
       .join('\n');
+    const current = this.player.current();
+    const upNext = follows ? this.player.remaining().slice(-5) : [];
+    const skippedArtists = [...digest.skippedArtists]
+      .filter(([, skips]) => skips >= SKIPS_TO_REPORT_ARTIST)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 8)
+      .map(([artist, skips]) => `${artist} (${skips})`);
     return [
       `Mood or request: ${prompt?.trim() || '(none — continue the current listening session)'}`,
-      `Currently playing: ${this.player.current() ? `${this.player.current().name} — ${this.player.current().artists.join('/')}` : '(nothing)'}`,
+      `Currently playing: ${current ? label(current) : '(nothing)'}`,
+      upNext.length ? `Already queued after it: ${upNext.map(label).join('; ')}` : '',
+      follows && follows !== current ? `Your picks play after: ${label(follows)}` : '',
       digest.recentlyPlayed.length ? `Recently played: ${digest.recentlyPlayed.join('; ')}` : '',
       digest.topArtists.length ? `Favourite artists: ${digest.topArtists.join(', ')}` : '',
       digest.liked.length ? `Liked: ${digest.liked.join('; ')}` : '',
       digest.disliked.length ? `Disliked (never pick): ${digest.disliked.join('; ')}` : '',
+      digest.skipped.length ? `Skipped early (steer away from these): ${digest.skipped.join('; ')}` : '',
+      skippedArtists.length ? `Often skipped artists (skips): ${skippedArtists.join(', ')}` : '',
       '',
       `CANDIDATES (choose only by index):\n${catalogue}`,
       '',
@@ -470,7 +818,8 @@ export class AiDj {
               'You are the music programmer for a personal NetEase Cloud Music player. ' +
               'Choose the next tracks from the CANDIDATES list only, by index. ' +
               'Favour artists the listener likes and the requested mood; keep variety — never place two tracks by the same artist back to back; ' +
-              'avoid anything listed as recently played or disliked. ' +
+              'avoid anything listed as recently played or disliked, and pick less of what the listener skips. ' +
+              'Candidates marked [liked] are the listener\'s own likes, not heard for a while: mix one in when it fits, but do not fill the set with them. ' +
               'Reply with JSON only, no prose, no code fence: ' +
               '{"vibe":"<one short line describing the set>","picks":[{"index":<candidate index>,"why":"<max 8 words>"}]}',
           },
@@ -488,7 +837,7 @@ export class AiDj {
    *
    * @throws {Error} when the answer carries no JSON object or no usable index.
    */
-  #parseAnswer(text, pool) {
+  #parseAnswer(text, pool, count) {
     const json = /\{[\s\S]*\}/.exec(text ?? '');
     if (!json) throw new Error('response contained no JSON object');
     const parsed = JSON.parse(json[0]);
@@ -503,7 +852,8 @@ export class AiDj {
       seen.add(index);
       ordered.push(index);
     }
-    return { picks: ordered, vibe: typeof parsed.vibe === 'string' ? parsed.vibe : '' };
+    // A model asked for five that answers with twenty would otherwise flood the queue.
+    return { picks: ordered.slice(0, count), vibe: typeof parsed.vibe === 'string' ? parsed.vibe : '' };
   }
 
   /** Record a model-tier success: clear the stale reason and log what ran. */
@@ -528,7 +878,7 @@ export class AiDj {
    * @returns {Promise<{picks: number[], vibe: string} | null>}
    *   `null` when the tier is unavailable or answered with nothing usable.
    */
-  async #askModel({ pool, digest, prompt, count }) {
+  async #askModel({ pool, digest, prompt, count, follows }) {
     const llm = this.resolveLlm?.();
     if (!llm?.stream) {
       return this.#decline('no LLM service is mounted (ctx.get("llm") returned nothing)');
@@ -545,7 +895,7 @@ export class AiDj {
     }
     this.resolvedFrom = target.source;
 
-    const brief = this.#brief({ pool, digest, prompt, count });
+    const brief = this.#brief({ pool, digest, prompt, count, follows });
     try {
       const request = curationRequest({
         target,
@@ -553,7 +903,7 @@ export class AiDj {
         sessionId: this.sessionId,
       });
       const text = await this.#collect(llm.stream(request));
-      return this.#accept(this.#parseAnswer(text, pool), target);
+      return this.#accept(this.#parseAnswer(text, pool, count), target);
     } catch (error) {
       return this.#decline(describeFailure(error));
     }
@@ -564,41 +914,52 @@ export class AiDj {
   /**
    * Score and interleave candidates without a model.
    *
-   * Scoring is deliberately simple and explainable: artist affinity dominates,
-   * familiarity is penalised, explicit dislikes are excluded earlier, and a
-   * small jitter keeps repeat requests from returning an identical order.
+   * Scoring is deliberately simple and explainable: a mood-brief match and
+   * artist affinity dominate, skips count against a track and its artists,
+   * recently played and disliked tracks were already excluded from the pool,
+   * and a small jitter keeps repeat requests from returning an identical order.
    */
-  #rank({ pool, digest, count }) {
+  #rank({ pool, digest, count, follows }) {
     const favourites = new Set(digest.topArtists);
     const currentArtists = new Set(this.player.current()?.artists ?? []);
     const playedArtists = new Map();
     for (const entry of this.store.state.history.slice(0, 60)) {
+      if (entry.skipped) continue;
       for (const artist of entry.artists ?? []) playedArtists.set(artist, (playedArtists.get(artist) ?? 0) + 1);
     }
-    const recentlyPlayed = new Set(digest.recentIds);
 
     const scored = pool.map((track) => {
       let score = Math.random() * 0.8;
+      // The brief is the listener's explicit ask; without this weight a chart
+      // hit by a favourite artist outranks every track that matches it.
+      // FM is personalised, similarity is not; a like is a known good song,
+      // weighted lightly so the set stays a discovery rather than a replay.
+      if (track.origin === 'prompt') score += 3.0;
+      else if (track.origin === 'fm') score += 1.0;
+      else if (track.origin === 'similar') score += 0.6;
+      else if (track.origin === 'liked') score += 0.5;
       for (const artist of track.artists ?? []) {
         if (favourites.has(artist)) score += 2.2;
         if (currentArtists.has(artist)) score += 1.4;
         score += Math.min((playedArtists.get(artist) ?? 0) * 0.15, 1.0);
+        score -= Math.min((digest.skippedArtists.get(artist) ?? 0) * 0.6, 2.4);
       }
-      if (!recentlyPlayed.has(track.id)) score += 1.0;
+      if (digest.skipCounts.has(track.id)) score -= 1.5;
       if (track.vip) score -= 0.4; // still playable when signed in, but riskier
       return { track, score };
     });
     scored.sort((a, b) => b.score - a.score);
 
-    // Interleave so one artist cannot own consecutive slots.
+    // Interleave so one artist cannot own consecutive slots, starting from the
+    // track the batch will actually follow.
     const picked = [];
-    let lastArtist = this.player.current()?.artists?.[0] ?? null;
+    let lastArtists = new Set(follows?.artists ?? []);
     while (picked.length < count && scored.length > 0) {
-      let chosen = scored.findIndex((entry) => entry.track.artists?.[0] !== lastArtist);
+      let chosen = scored.findIndex((entry) => !(entry.track.artists ?? []).some((artist) => lastArtists.has(artist)));
       if (chosen === -1) chosen = 0;
       const [entry] = scored.splice(chosen, 1);
       picked.push(entry.track);
-      lastArtist = entry.track.artists?.[0] ?? null;
+      lastArtists = new Set(entry.track.artists ?? []);
     }
     return picked;
   }
@@ -610,15 +971,19 @@ export class AiDj {
    * @param {object} [options]
    * @param {string} [options.prompt] mood/request brief.
    * @param {number} [options.count] how many tracks to choose.
+   * @param {object|null} [options.follows] the track the batch will play after;
+   *   the queue's last track by default, since a batch is appended.
    * @returns {Promise<Plan>}
    */
-  async plan({ prompt = '', count = 5 } = {}) {
+  async plan({ prompt = '', count = 5, follows = this.player.queue.at(-1) ?? null } = {}) {
     const size = Math.min(Math.max(Number(count) || 5, 1), 25);
-    const { pool, digest } = await this.#candidates({ prompt, count: size });
+    const { pool, digest, terms } = await this.#candidates({ prompt });
+    /** What the brief was searched as, so a rewrite is observable. */
+    const searchedAs = terms;
     if (pool.length === 0) {
-      return { tracks: [], source: 'heuristic', note: 'no candidates were available', poolSize: 0 };
+      return { tracks: [], source: 'heuristic', note: 'no candidates were available', poolSize: 0, searchedAs };
     }
-    const answer = await this.#askModel({ pool, digest, prompt, count: size });
+    const answer = await this.#askModel({ pool, digest, prompt, count: size, follows });
     if (answer) {
       return {
         tracks: answer.picks.map((index) => pool[index]),
@@ -627,24 +992,29 @@ export class AiDj {
         /** Which provider route curated, so the choice is observable. */
         route: `${answer.target.provider}/${answer.target.model}`,
         poolSize: pool.length,
+        searchedAs,
       };
     }
     return {
-      tracks: this.#rank({ pool, digest, count: size }),
+      tracks: this.#rank({ pool, digest, count: size, follows }),
       source: 'heuristic',
       note: this.modelError
         ? `model tier unavailable (${this.modelError}); used similarity, charts and taste feedback`
         : 'no model configured; used similarity, charts and taste feedback',
       poolSize: pool.length,
+      searchedAs,
     };
   }
 
   /**
    * Extend the queue when it runs low. Safe to call on every track change: the
    * busy flag and the threshold check make it a no-op most of the time.
+   * @param {object} [options]
+   * @param {boolean} [options.force] plan even when disabled or the queue is deep.
+   * @param {number} [options.count] batch size, overriding the player's setting.
    * @returns {Promise<Plan | null>}
    */
-  async topUp({ force = false } = {}) {
+  async topUp({ force = false, count } = {}) {
     const settings = this.store.settings;
     if (!this.player.dj.enabled && !force) return null;
     if (this.busy) return null;
@@ -655,7 +1025,10 @@ export class AiDj {
     this.player.dj.busy = true;
     this.player.bump();
     try {
-      const plan = await this.plan({ prompt: settings.djPrompt ?? '', count: settings.djBatchSize ?? 5 });
+      const planned = await this.plan({ prompt: settings.djPrompt ?? '', count: count ?? settings.djBatchSize ?? 5 });
+      // The queue can change while the plan is in flight; report only what lands.
+      const queued = new Set(this.player.queue.map((track) => track.id));
+      const plan = { ...planned, tracks: planned.tracks.filter((track) => !queued.has(track.id)) };
       if (plan.tracks.length === 0) {
         this.player.dj = { ...this.player.dj, busy: false, error: plan.note ?? 'no tracks found', lastPlanAt: Date.now() };
         return plan;
@@ -676,6 +1049,7 @@ export class AiDj {
           route: plan.route ?? null,
           added: plan.tracks.length,
           names: plan.tracks.map((track) => `${track.name} — ${(track.artists ?? []).join('/')}`),
+          searchedAs: plan.searchedAs ?? [],
         },
       };
       this.player.bump();
@@ -699,7 +1073,8 @@ export class AiDj {
   async start({ prompt, count = 8 } = {}) {
     this.store.updateSettings({ djEnabled: true, ...(prompt === undefined ? {} : { djPrompt: prompt }) });
     this.player.dj.enabled = true;
-    const plan = await this.plan({ prompt: prompt ?? this.store.settings.djPrompt ?? '', count });
+    // The batch replaces the queue, so nothing precedes its first track.
+    const plan = await this.plan({ prompt: prompt ?? this.store.settings.djPrompt ?? '', count, follows: null });
     if (plan.tracks.length > 0) {
       this.player.setQueue(plan.tracks, { startIndex: 0, play: true, source: plan.source });
       this.player.dj.lastPlanAt = Date.now();
@@ -709,6 +1084,7 @@ export class AiDj {
         route: plan.route ?? null,
         added: plan.tracks.length,
         names: plan.tracks.map((track) => `${track.name} — ${(track.artists ?? []).join('/')}`),
+        searchedAs: plan.searchedAs ?? [],
       };
       this.player.dj.error = null;
     } else {