@doitian/dsh-music 0.1.2 → 0.1.5

package/lib/router.js

@@ -12,12 +12,17 @@
  * only lives 20 minutes and needs the session cookie at *resolution* time, and
  * proxying keeps playback same-origin so the page never mixes http and https.
  *
+ * Every state response annotates each queued track with its taste — `liked`
+ * from the NetEase account, `disliked` from the local feedback — because that
+ * is what the panel draws its hearts from. See {@link MusicRouter#snapshot}.
+ *
  * @module dsh-music/router
  */
 
 import { Readable } from 'node:stream';
 
 import { DEFAULT_LEVEL, LEVELS, isLevel } from './netease.js';
+import { TASTE_LEVELS } from './session.js';
 
 /** Resolved CDN URLs are reused for this long (they live 20 minutes). */
 const URL_CACHE_MS = 15 * 60 * 1000;
@@ -42,6 +47,16 @@ const FORWARDED_HEADERS = {
   'last-modified': 'Last-Modified',
 };
 
+/**
+ * HTTP status for a refused taste change, so the panel can tell "sign in" from
+ * "NetEase refused" from "the network is down" without parsing a sentence.
+ */
+const TASTE_STATUS = {
+  BAD_ID: 400,
+  ANONYMOUS: 401,
+  NETWORK: 502,
+};
+
 /** A small JSON/HTTP helper set. */
 function sendJson(res, status, value) {
   const body = Buffer.from(JSON.stringify(value ?? null), 'utf8');
@@ -85,6 +100,7 @@ export class MusicRouter {
    * @param {import('./session.js').SessionStore} options.store
    * @param {import('./session.js').QrLogin} options.qr
    * @param {import('./dj.js').AiDj} options.dj
+   * @param {import('./likes.js').LikeState} options.likes
    * @param {string} options.panelHtml
    * @param {string} options.qrcodeJs
    * @param {object} [options.config]
@@ -92,13 +108,14 @@ export class MusicRouter {
    * @param {() => object} [options.diagnostics] extra facts for `/health`.
    * @param {{warn: Function, info: Function, debug: Function}} [options.logger]
    */
-  constructor({ base, api, player, store, qr, dj, panelHtml, qrcodeJs, config = {}, listRoutes, diagnostics, logger }) {
+  constructor({ base, api, player, store, qr, dj, likes, panelHtml, qrcodeJs, config = {}, listRoutes, diagnostics, logger }) {
     this.base = base.replace(/\/+$/, '');
     this.api = api;
     this.player = player;
     this.store = store;
     this.qr = qr;
     this.dj = dj;
+    this.likes = likes;
     this.panelHtml = panelHtml;
     this.qrcodeJs = qrcodeJs;
     this.config = config;
@@ -266,10 +283,49 @@ export class MusicRouter {
 
   // -------------------------------------------------------------------- API
 
-  /** The panel's poll target: full player snapshot including account and DJ. */
-  snapshot(extra = {}) {
+  /**
+   * Resolve the like state of everything the panel is about to draw.
+   *
+   * A like is the account's, so this is a network read — but a cached one: only
+   * tracks with no fresh answer cost a call, which after the first poll of a
+   * queue is normally none of them.
+   */
+  async refreshLikes() {
+    const ids = [this.player.current()?.id, ...this.player.queue.map((track) => track.id)].filter(Boolean);
+    if (ids.length > 0) await this.likes.ensure(ids);
+  }
+
+  /**
+   * One track as the panel needs it: the metadata plus its taste.
+   *
+   * `liked` is the account's answer (cached, see {@link LikeState}) and
+   * `disliked` is the local level. They are two values of one three-level
+   * taste, never both true: liking a disliked track clears the dislike and
+   * disliking a liked track removes it on NetEase.
+   */
+  tasteView(track) {
+    if (!track) return null;
+    return {
+      ...track,
+      liked: this.likes.isLiked(track.id),
+      disliked: this.store.taste(track.id) === 'disliked',
+    };
+  }
+
+  /**
+   * The panel's poll target: full player snapshot including account and DJ.
+   *
+   * Async because `liked` is NetEase's answer rather than the host's: the queued
+   * tracks' like state is resolved (once, then cached) before the document is
+   * written, so a heart never lags a poll behind the track it belongs to.
+   */
+  async snapshot(extra = {}) {
+    await this.refreshLikes();
+    const base = this.player.snapshot();
     return {
-      ...this.player.snapshot(),
+      ...base,
+      queue: base.queue.map((track) => this.tasteView(track)),
+      current: this.tasteView(base.current),
       account: this.api.account,
       authenticated: this.api.authenticated,
       settings: this.store.settings,
@@ -291,6 +347,101 @@ export class MusicRouter {
     return 'discovered';
   }
 
+  /**
+   * Move one track to a taste level, keeping the account and the local mirror
+   * in step.
+   *
+   * The NetEase half is written first: a level that claimed a like the account
+   * never received would be contradicted by the next poll's heart. Removing a
+   * like is therefore a real request, which is why a track the account has not
+   * liked can be cleared locally without one.
+   *
+   * @param {number|string} trackId
+   * @param {'liked'|'none'|'disliked'} level
+   * @returns {Promise<{ok: boolean, id?: number, level?: string, status?: number, code?: string, reason?: string}>}
+   */
+  async applyTaste(trackId, level) {
+    const id = Number(trackId);
+    if (!Number.isFinite(id)) {
+      return { ok: false, status: 400, code: 'BAD_ID', reason: `invalid track id "${trackId}"` };
+    }
+    if (!TASTE_LEVELS.includes(level)) {
+      return {
+        ok: false,
+        status: 400,
+        code: 'BAD_LEVEL',
+        reason: `unknown taste level "${level}" (expected ${TASTE_LEVELS.join(', ')})`,
+      };
+    }
+
+    // Any level but `liked` means the account must not still have the like —
+    // including `disliked`, because the two are exclusive. A track with no
+    // cached answer is resolved first, so the two levels cannot both end up
+    // true; an anonymous session has nothing to resolve and skips the call.
+    if (level !== 'liked' && !this.likes.known(id)) await this.likes.ensure([id]);
+    if (level !== 'liked' && this.likes.isLiked(id)) {
+      const removed = await this.likes.set(id, false);
+      if (!removed.ok) return { ok: false, status: TASTE_STATUS[removed.code] ?? 502, code: removed.code, reason: removed.reason };
+    }
+    if (level === 'liked') {
+      const added = await this.likes.set(id, true);
+      if (!added.ok) return { ok: false, status: TASTE_STATUS[added.code] ?? 502, code: added.code, reason: added.reason };
+    }
+
+    this.store.setTaste(id, level);
+    return { ok: true, id, level };
+  }
+
+  /**
+   * Start a queue action and report the track it acts on.
+   *
+   * Only `jump` and `remove` name a position, and only `remove` is read as a
+   * judgement about the track — see {@link MusicRouter#removeFromQueue}. The two
+   * share this so the index is resolved the same way, and so a track is never
+   * re-read from a queue it has already left.
+   *
+   * @returns {{track: object|null, wasCurrent: boolean, dropped: boolean}}
+   */
+  #queueAction(action, index) {
+    const at = Number(index);
+    const track = Number.isInteger(at) ? (this.player.queue[at] ?? null) : null;
+    if (action === 'remove') return { ...this.player.removeAt(at), dropped: Boolean(track) };
+    this.player.jump(at);
+    return { track, wasCurrent: false, dropped: false };
+  }
+
+  /**
+   * Take one track out of the queue, and read that as a dislike of it.
+   *
+   * Removing a queued track is the listener saying "not this one", and the row
+   * is gone afterwards — so the judgement has to be recorded now or not at all.
+   * Without it the DJ re-derives the same track from the same similarity and
+   * charts within a batch or two, which is what "removing does nothing" looks
+   * like from the outside.
+   *
+   * Two edges are deliberate. A track already rated does not get its level
+   * changed, because `remove` is often just queue housekeeping — clearing out
+   * music already heard — and silently rewriting a like would be worse than
+   * missing a signal. And a *failed* dislike write never comes back to the
+   * panel as a failed removal: the queue action is what the click asked for, and
+   * the taste write is a consequence of it.
+   *
+   * @param {object|null} track the track that was removed.
+   * @param {boolean} wasCurrent whether it was the playing one.
+   * @returns {Promise<object|null>} the applied level, or null when nothing was.
+   */
+  async removeFromQueue(track, wasCurrent) {
+    if (!track) return null;
+    if (this.store.taste(track.id) !== 'none') return null;
+    const applied = await this.applyTaste(track.id, 'disliked');
+    if (applied.ok) return applied;
+    this.logger?.debug?.(`[music] track ${track.id} removed but not marked disliked: ${applied.reason}`);
+    // The track left the queue and it was the one playing, so playback has
+    // nowhere to go. A disliked track auto-advances; a removal must too.
+    if (wasCurrent) this.player.move(1, { auto: true });
+    return null;
+  }
+
   /** Route one `/music/api/*` request. */
   async handleApi(req, res, pathname) {
     const route = pathname.slice(`${this.base}/api`.length).replace(/\/+$/, '') || '/';
@@ -299,16 +450,16 @@ export class MusicRouter {
 
     // ---- player state -----------------------------------------------------
     if (route === '/state' && method === 'GET') {
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
     if (route === '/report' && method === 'POST') {
       const body = await readJson(req);
       this.player.report(body);
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
     if (route === '/seek-consumed' && method === 'POST') {
       this.player.takeSeek();
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
     if (route === '/control' && method === 'POST') {
       const { action, value } = await readJson(req);
@@ -324,7 +475,7 @@ export class MusicRouter {
         case 'mode': this.player.setMode(value); break;
         default: return sendJson(res, 400, { error: `unknown action "${action}"` });
       }
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
 
     // ---- queue ------------------------------------------------------------
@@ -335,18 +486,22 @@ export class MusicRouter {
       }
       this.player.setQueue(tracks, { startIndex, source: 'user' });
       this.store.recordPlay(this.player.current() ?? tracks[0]);
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
     if (route === '/queue' && method === 'POST') {
       const { action, tracks, index } = await readJson(req);
+      let removal = null;
       if (action === 'replace' && Array.isArray(tracks)) this.player.setQueue(tracks, { source: 'user' });
       else if (action === 'append' && Array.isArray(tracks)) this.player.append(tracks, { source: 'user' });
       else if (action === 'insert' && Array.isArray(tracks)) this.player.insertNext(tracks, { source: 'user' });
-      else if (action === 'remove') this.player.remove(Number(index));
-      else if (action === 'jump') this.player.jump(Number(index));
+      else if (action === 'remove' || action === 'jump') removal = this.#queueAction(action, index);
       else if (action === 'clear') this.player.clear();
       else return sendJson(res, 400, { error: `unknown queue action "${action}"` });
-      return sendJson(res, 200, this.snapshot());
+      // Answer with the queue as it now stands, but record the judgement first:
+      // the snapshot's hearts should already show it.
+      if (removal?.dropped && removal.wasCurrent) await this.removeFromQueue(removal.track, true);
+      else if (removal?.dropped) void this.removeFromQueue(removal.track, false);
+      return sendJson(res, 200, await this.snapshot());
     }
 
     // ---- catalogue --------------------------------------------------------
@@ -389,14 +544,42 @@ export class MusicRouter {
       });
     }
 
+    // ---- taste ------------------------------------------------------------
+    /**
+     * Move one track to a taste level: `liked`, `none` (the like removed), or
+     * `disliked`.
+     *
+     * One endpoint rather than a like/unlike pair, because the three levels are
+     * exclusive states of one thing: the panel always says which level it wants,
+     * so a click cannot be turned into the wrong direction by a stale poll, and
+     * disliking a liked track is one request rather than two racing ones.
+     */
+    if (route === '/taste' && method === 'POST') {
+      const { trackId, level } = await readJson(req);
+      const applied = await this.applyTaste(trackId, level);
+      if (!applied.ok) return sendJson(res, applied.status ?? 502, { error: applied.reason, code: applied.code });
+      return sendJson(res, 200, await this.snapshot());
+    }
+
     // ---- feedback ---------------------------------------------------------
+    /**
+     * The local taste signals: skips, and dislikes, plus the older toggle
+     * spelling of a like. Kept because a page cached from an earlier build
+     * still reaches for it.
+     */
     if (route === '/feedback' && method === 'POST') {
       const { kind, trackId } = await readJson(req);
-      if (!['likes', 'dislikes', 'skips'].includes(kind)) {
-        return sendJson(res, 400, { error: `unknown feedback kind "${kind}"` });
+      if (kind === 'skips') {
+        this.store.recordFeedback(kind, trackId);
+        return sendJson(res, 200, await this.snapshot());
+      }
+      if (kind === 'likes' || kind === 'dislikes') {
+        const level = kind === 'likes' ? 'liked' : 'disliked';
+        const applied = await this.applyTaste(trackId, this.store.taste(trackId) === level ? 'none' : level);
+        if (!applied.ok) return sendJson(res, applied.status ?? 502, { error: applied.reason, code: applied.code });
+        return sendJson(res, 200, await this.snapshot());
       }
-      this.store.recordFeedback(kind, trackId);
-      return sendJson(res, 200, { feedback: this.store.feedback });
+      return sendJson(res, 400, { error: `unknown feedback kind "${kind}"` });
     }
 
     // ---- streaming quality ------------------------------------------------
@@ -414,7 +597,7 @@ export class MusicRouter {
       this.store.updateSettings({ level });
       this.logger?.info?.(`[music] streaming quality set to ${level} from the player`);
       // The running stream keeps its bytes; the next load or seek uses this.
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
 
     // ---- AI DJ ------------------------------------------------------------
@@ -469,7 +652,7 @@ export class MusicRouter {
       } else if (prompt !== undefined && this.player.dj.enabled) {
         void this.dj.topUp({ force: true });
       }
-      return sendJson(res, 200, this.snapshot());
+      return sendJson(res, 200, await this.snapshot());
     }
 
     // ---- login ------------------------------------------------------------
@@ -495,6 +678,8 @@ export class MusicRouter {
     if (route === '/login/logout' && method === 'POST') {
       this.api.clearCookie();
       this.store.clearSession();
+      // The likes belong to the account that just left, not to the next one.
+      this.likes.clear();
       this.qr.reset();
       return sendJson(res, 200, { loggedIn: false });
     }

package/lib/session.js

@@ -20,6 +20,15 @@ const MAX_HISTORY = 300;
 /** Feedback lists are bounded so the file cannot grow without limit. */
 const MAX_FEEDBACK = 500;
 
+/**
+ * The three levels a track's taste can hold, mutually exclusive.
+ *
+ * `liked` mirrors the NetEase account — the API call that changes it there is
+ * what writes this — while `disliked` is local, because the plain web API has
+ * no dislike endpoint. `none` is "never rated", not a fourth signal.
+ */
+export const TASTE_LEVELS = ['liked', 'none', 'disliked'];
+
 /** QR codes are refreshed before the API reports them expired. */
 const QR_TTL_MS = 110_000;
 
@@ -187,10 +196,11 @@ export class SessionStore {
     return this.state.history.slice(0, limit).map((entry) => entry.id);
   }
 
-  /** Most-played artists, most frequent first. */
+  /** Most-played artists, most frequent first. A skipped play is not a play. */
   topArtists(limit = 8) {
     const counts = new Map();
     for (const entry of this.state.history.slice(0, 150)) {
+      if (entry.skipped) continue;
       for (const artist of entry.artists) counts.set(artist, (counts.get(artist) ?? 0) + 1);
     }
     return [...counts.entries()]
@@ -199,26 +209,94 @@ export class SessionStore {
       .map(([artist]) => artist);
   }
 
-  /** Record like/dislike/skip feedback for one track. */
-  recordFeedback(kind, trackId) {
-    const list = this.state.feedback[kind];
-    if (!list || !Number.isFinite(Number(trackId))) return this.state.feedback;
+  /**
+   * One track's taste level: `liked`, `disliked`, or `none` (never rated).
+   * @param {number|string} trackId
+   * @returns {'liked'|'disliked'|'none'}
+   */
+  taste(trackId) {
     const id = Number(trackId);
-    const index = list.indexOf(id);
-    if (kind === 'skips') {
-      // Skips are counters, not membership: keep the newest occurrence.
-      list.unshift(id);
-      if (list.length > MAX_FEEDBACK) list.length = MAX_FEEDBACK;
-    } else if (index >= 0) {
-      list.splice(index, 1);
-    } else {
-      list.unshift(id);
+    if (this.state.feedback.likes.includes(id)) return 'liked';
+    if (this.state.feedback.dislikes.includes(id)) return 'disliked';
+    return 'none';
+  }
+
+  /**
+   * Set one track's taste level, keeping the two lists mutually exclusive.
+   *
+   * The caller owns the NetEase half. `setTaste(id, 'liked')` records the local
+   * mirror *after* the API call that liked the track for real, so the DJ's taste
+   * digest and the heart in the list agree with the account instead of
+   * promising a like NetEase never received.
+   *
+   * @param {number|string} trackId
+   * @param {'liked'|'none'|'disliked'} level
+   */
+  setTaste(trackId, level) {
+    const id = Number(trackId);
+    if (!Number.isFinite(id) || !TASTE_LEVELS.includes(level)) return this.state.feedback;
+    for (const [name, list] of Object.entries({
+      liked: this.state.feedback.likes,
+      disliked: this.state.feedback.dislikes,
+    })) {
+      const index = list.indexOf(id);
+      if (name === level && index < 0) list.unshift(id);
+      else if (name !== level && index >= 0) list.splice(index, 1);
       if (list.length > MAX_FEEDBACK) list.length = MAX_FEEDBACK;
-      // Liking and disliking a track are mutually exclusive.
-      const opposite = kind === 'likes' ? this.state.feedback.dislikes : this.state.feedback.likes;
-      const oppositeIndex = opposite.indexOf(id);
-      if (oppositeIndex >= 0) opposite.splice(oppositeIndex, 1);
     }
+    // Written through rather than debounced like the play history: a taste level
+    // is a deliberate, rare action whose loss would be surprising.
+    this.save();
+    return this.state.feedback;
+  }
+
+  /**
+   * Replace the liked mirror with the account's own list.
+   *
+   * The account is where likes live, so this list is a copy rather than a
+   * record: reconciling at startup is what keeps the DJ's taste digest from
+   * carrying a like the account does not have (or missing one it does).
+   *
+   * @param {Iterable<number|string>} ids
+   */
+  setLikedIds(ids) {
+    const list = [...new Set([...ids].map(Number).filter(Number.isFinite))];
+    this.state.feedback.likes = list.slice(0, MAX_FEEDBACK);
+    this.save();
+    return this.state.feedback;
+  }
+
+  /**
+   * Toggle like/dislike, or count a skip. The likes and dislikes of a track are
+   * mutually exclusive, so a dislike replaces a like and vice versa.
+   */
+  recordFeedback(kind, trackId) {
+    const id = Number(trackId);
+    if (!Number.isFinite(id)) return this.state.feedback;
+    if (kind === 'skips') return this.recordSkip(id);
+    const level = kind === 'likes' ? 'liked' : kind === 'dislikes' ? 'disliked' : null;
+    if (!level) return this.state.feedback;
+    return this.setTaste(id, this.taste(id) === level ? 'none' : level);
+  }
+
+  /**
+   * Count a skip: the listener moved past the track early.
+   *
+   * Skips are counters, not membership, so each one is kept as an occurrence.
+   * The play it cut short is marked as well, because the history is what the
+   * DJ reads artist affinity from, and a track abandoned after ten seconds
+   * would otherwise count as one more play of that artist.
+   *
+   * @param {number|string} trackId
+   */
+  recordSkip(trackId) {
+    const id = Number(trackId);
+    if (!Number.isFinite(id)) return this.state.feedback;
+    const skips = this.state.feedback.skips;
+    skips.unshift(id);
+    if (skips.length > MAX_FEEDBACK) skips.length = MAX_FEEDBACK;
+    const play = this.state.history.find((entry) => entry.id === id);
+    if (play) play.skipped = true;
     this.touch();
     return this.state.feedback;
   }
@@ -235,13 +313,26 @@ export class SessionStore {
     const name = (entry) =>
       typeof entry === 'object' ? `${entry.name} — ${(entry.artists ?? []).join('/')}` : `#${entry}`;
     const byId = new Map(this.state.history.map((entry) => [entry.id, entry]));
+    const skipCounts = new Map();
+    for (const id of this.state.feedback.skips) skipCounts.set(id, (skipCounts.get(id) ?? 0) + 1);
+    const skippedArtists = new Map();
+    for (const entry of this.state.history.slice(0, 150)) {
+      if (!entry.skipped) continue;
+      for (const artist of entry.artists ?? []) skippedArtists.set(artist, (skippedArtists.get(artist) ?? 0) + 1);
+    }
     return {
       recentlyPlayed: this.state.history.slice(0, history).map(name),
       topArtists: this.topArtists(8),
       liked: this.state.feedback.likes.slice(0, 15).map((id) => byId.get(id)).filter(Boolean).map(name),
       disliked: this.state.feedback.dislikes.slice(0, 15).map((id) => byId.get(id)).filter(Boolean).map(name),
+      // Newest first, one line per track however often it was skipped.
+      skipped: [...skipCounts.keys()].slice(0, 15).map((id) => byId.get(id)).filter(Boolean).map(name),
       dislikedIds: this.state.feedback.dislikes.slice(0, 80),
       recentIds: this.recentIds(60),
+      /** Track id → how many times it was skipped. */
+      skipCounts,
+      /** Artist → skipped plays among the recent history. */
+      skippedArtists,
     };
   }
 }

package/lib/state.js

@@ -25,6 +25,14 @@ export const MODES = ['list', 'single', 'shuffle'];
 /** A pending seek is delivered once and then cleared. */
 const SEEK_EPSILON_MS = 1_000;
 
+/**
+ * A manual "next" before this much of a track has played is a skip: the
+ * listener rejected the track rather than finished with it. The window is 30 s,
+ * or a quarter of the track when that is longer.
+ */
+const SKIP_WINDOW_MS = 30_000;
+const SKIP_WINDOW_FRACTION = 0.25;
+
 export class Player {
   /**
    * @param {object} [options]
@@ -69,6 +77,11 @@ export class Player {
      * @type {(() => Promise<void>) | undefined}
      */
     this.onLowQueue = undefined;
+    /**
+     * Called with a track the listener moved past early, for the taste record.
+     * @type {((track: object) => void) | undefined}
+     */
+    this.onSkip = undefined;
   }
 
   /** Subscribe to state changes. @returns {() => void} unsubscribe */
@@ -152,6 +165,21 @@ export class Player {
     return { added: added.length, snapshot: this.snapshot() };
   }
 
+  /**
+   * Remove one queue position and report what was removed.
+   *
+   * The report matters: taking a track out of the queue is a judgement about the
+   * track, not just about the list, and the caller cannot read it off the queue
+   * afterwards — the row whose index it was asking about is the one that is
+   * gone. `snapshot` is the state after the removal.
+   *
+   * @returns {{track: object|null, wasCurrent: boolean, snapshot: object}}
+   */
+  removeAt(index) {
+    const track = this.queue[index] ?? null;
+    return { track, wasCurrent: index >= 0 && index === this.index, snapshot: this.remove(index) };
+  }
+
   /** Remove one queue position. */
   remove(index) {
     if (index < 0 || index >= this.queue.length) return this.snapshot();
@@ -205,15 +233,42 @@ export class Player {
    */
   move(step, { auto = false } = {}) {
     if (this.queue.length === 0) return this.snapshot();
+    const left = this.current();
+    const skipped = !auto && step > 0 && this.#heardBriefly();
     this.index = this.#nextIndex(step);
     this.pendingSeek = 0;
     this.playing = true;
     this.reported = { ...this.reported, position: 0, duration: 0, error: null, at: Date.now() };
     this.bump({ transport: true });
+    if (skipped && this.current() !== left) this.#notifySkip(left);
     if (auto) this.#maybeExtend();
     return this.snapshot();
   }
 
+  /**
+   * Whether the current track was heard, but only briefly.
+   *
+   * Only a reported position counts: a track the panel never started (paused,
+   * blocked by autoplay, still loading) was not listened to, so moving past it
+   * says nothing about it.
+   */
+  #heardBriefly() {
+    const current = this.current();
+    if (!current || this.reported.trackId !== current.id) return false;
+    const position = Number(this.reported.position) || 0;
+    if (position <= 0) return false;
+    const duration = Number(this.reported.duration) || Number(current.duration) || 0;
+    return position < Math.max(SKIP_WINDOW_MS, duration * SKIP_WINDOW_FRACTION);
+  }
+
+  #notifySkip(track) {
+    try {
+      this.onSkip?.(track);
+    } catch (error) {
+      this.logger?.warn?.(`[music] skip listener failed: ${error.message}`);
+    }
+  }
+
   /** Jump to an explicit queue position. */
   jump(index) {
     if (index < 0 || index >= this.queue.length) return this.snapshot();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doitian/dsh-music",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "NetEase Cloud Music (music.163.com) player and AI DJ for DeepSeek Harness: a sidebar page with in-app playback, QR sign-in, and agent tools that curate the queue.",
   "keywords": [
     "dsh",
@@ -39,6 +39,8 @@
     "lib/session.js",
     "lib/state.js",
     "lib/dj.js",
+    "lib/cache.js",
+    "lib/likes.js",
     "lib/router.js",
     "lib/panel.html",
     "lib/vendor/qrcode.js",
@@ -53,8 +55,8 @@
     "access": "public"
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/netease.js && node --check lib/session.js && node --check lib/state.js && node --check lib/dj.js && node --check lib/router.js",
-    "test": "node test/netease.test.mjs && node test/dj.test.mjs && node test/client.test.mjs",
+    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/netease.js && node --check lib/session.js && node --check lib/state.js && node --check lib/dj.js && node --check lib/cache.js && node --check lib/likes.js && node --check lib/router.js",
+    "test": "node test/netease.test.mjs && node test/cache.test.mjs && node test/likes.test.mjs && node test/dj.test.mjs && node test/client.test.mjs",
     "probe:headers": "node scripts/probe-headers.mjs",
     "test:live": "node test/host.test.mjs",
     "test:all": "npm test && npm run test:live"