@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/integrations/spotify/service.mjs

@@ -1,4 +1,8 @@
 import { createSpotifyWebApiClient } from "./web-api-client.mjs";
+import { readSpotifyLibrarySnapshot } from "./library-snapshot.mjs";
+import { execFile } from "node:child_process";
+import { hostname } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
 
 export const SPOTIFY_SERVICE_LIMITS = Object.freeze({
   deviceIdLengthMax: 256,
@@ -13,6 +17,13 @@ export const SPOTIFY_SERVICE_LIMITS = Object.freeze({
   libraryTracksMax: 20,
   recentlyPlayedDefault: 20,
   recentlyPlayedMax: 50,
+  deviceNameLengthMax: 128,
+  searchQueryLengthMax: 256,
+  searchResultsDefault: 5,
+  searchResultsMax: 10,
+  playbackReadinessSnapshotsMax: 4,
+  playbackReadinessTimeoutMs: 5_000,
+  playbackReadinessPollMs: 250,
 });
 
 const repeatStates = new Set(["off", "track", "context"]);
@@ -21,16 +32,29 @@ const trackUriPattern = /^spotify:track:[A-Za-z0-9]{1,128}$/u;
 const contextUriPattern = /^spotify:(?:album|artist|playlist):[A-Za-z0-9]{1,128}$/u;
 
 export class SpotifyServiceError extends Error {
-  constructor(code, message) {
+  constructor(code, message, { outcomeUnknown = false, actionNotDispatched = false } = {}) {
     super(message);
     this.name = "SpotifyServiceError";
     this.code = code;
     this.provider = "spotify";
+    this.outcomeUnknown = outcomeUnknown;
+    // These errors are raised by local argument validators before client dispatch.
+    if (!outcomeUnknown && (actionNotDispatched || /^(?:invalid_|conflicting_)/u.test(code))) this.actionNotDispatched = true;
   }
 }
 
-function fail(code, message) {
-  throw new SpotifyServiceError(code, message);
+function fail(code, message, options) {
+  throw new SpotifyServiceError(code, message, options);
+}
+
+function failBeforeDispatch(code, message) {
+  fail(code, message, { actionNotDispatched: true });
+}
+
+function failDeviceSelection(code, message, devices) {
+  const error = new SpotifyServiceError(code, message, { actionNotDispatched: true });
+  error.availableDevices = devices.slice(0, 20).map(({ name, type, is_active, is_restricted }) => ({ name, type, is_active, is_restricted }));
+  throw error;
 }
 
 function isPlainObject(value) {
@@ -186,8 +210,8 @@ function editablePlaylistReason(playlist, ownerId) {
     return "invalid";
   }
   if (playlist.owner_id !== ownerId) return "not_owned";
-  if (playlist.is_public === true) return "public";
-  if (playlist.collaborative === true) return "collaborative";
+  if (playlist.is_public !== false) return "public";
+  if (playlist.collaborative !== false) return "collaborative";
   if (playlist.tracks_total > SPOTIFY_SERVICE_LIMITS.playlistEditTracksMax) {
     return "over_track_limit";
   }
@@ -298,6 +322,37 @@ function recentLimit(value) {
   return value;
 }
 
+function searchQuery(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    fail("invalid_search_query", "The Spotify search query must not be empty.");
+  }
+  const query = value.trim();
+  if (
+    Array.from(query).length > SPOTIFY_SERVICE_LIMITS.searchQueryLengthMax
+  ) {
+    fail(
+      "invalid_search_query",
+      `The Spotify search query must be at most ${SPOTIFY_SERVICE_LIMITS.searchQueryLengthMax} characters.`,
+    );
+  }
+  return query;
+}
+
+function searchLimit(value) {
+  if (value === undefined) return SPOTIFY_SERVICE_LIMITS.searchResultsDefault;
+  if (
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > SPOTIFY_SERVICE_LIMITS.searchResultsMax
+  ) {
+    fail(
+      "invalid_search_limit",
+      `Spotify search limit must be an integer from 1 to ${SPOTIFY_SERVICE_LIMITS.searchResultsMax}.`,
+    );
+  }
+  return value;
+}
+
 function actionReceipt(action) {
   return {
     provider: "spotify",
@@ -308,11 +363,325 @@ function actionReceipt(action) {
   };
 }
 
-async function queueDeviceId(client, requestedDeviceId) {
+const DEVICE_QUERY_FILLER = new Set([
+  "a",
+  "an",
+  "the",
+  "my",
+  "your",
+  "on",
+  "onto",
+  "to",
+  "from",
+  "over",
+  "spotify",
+  "device",
+  "devices",
+  "playback",
+  "play",
+  "playing",
+  "switch",
+  "transfer",
+  "move",
+  "moving",
+  "it",
+  "this",
+  "that",
+  "please",
+  "rn",
+  "now",
+  "there",
+  "here",
+  // Spanish filler around a device name.
+  "en", "el", "la", "mi", "al", "pon", "ponla", "ponlo", "reproduce", "dispositivo", "ahora", "aquí", "allí",
+  // Portuguese filler.
+  "no", "na", "meu", "minha", "toca", "coloca", "agora",
+]);
+
+const DEVICE_TYPE_ALIASES = new Map([
+  ["phone", "smartphone"],
+  ["smartphone", "smartphone"],
+  ["tablet", "tablet"],
+  ["computer", "computer"],
+  ["desktop", "computer"],
+  ["laptop", "computer"],
+  ["电脑", "computer"],
+  ["计算机", "computer"],
+  ["手机", "smartphone"],
+  ["音箱", "speaker"],
+  ["音响", "speaker"],
+  ["ordenador", "computer"],
+  ["computadora", "computer"],
+  ["portátil", "computer"],
+  ["móvil", "smartphone"],
+  ["celular", "smartphone"],
+  ["teléfono", "smartphone"],
+  ["altavoz", "speaker"],
+  ["bocina", "speaker"],
+  ["parlante", "speaker"],
+  ["tele", "tv"],
+  ["televisión", "tv"],
+  ["coche", "automobile"],
+  ["carro", "automobile"],
+  ["computador", "computer"],
+  ["notebook", "computer"],
+  ["telefone", "smartphone"],
+  ["パソコン", "computer"],
+  ["スマホ", "smartphone"],
+  ["携帯", "smartphone"],
+  ["スピーカー", "speaker"],
+  ["テレビ", "tv"],
+  ["speaker", "speaker"],
+  ["tv", "tv"],
+  ["television", "tv"],
+  ["car", "automobile"],
+  ["automobile", "automobile"],
+]);
+
+function clipText(value, maximum) {
+  const chars = Array.from(value);
+  if (chars.length <= maximum) return value;
+  return `${chars.slice(0, maximum).join("")}...`;
+}
+
+function normalizeDeviceLabel(value) {
+  return value
+    .toLocaleLowerCase("en-US")
+    .replace(/[\u2018\u2019\u201a\u201b\u2032\u02bc']/gu, "")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .replace(/ +/gu, " ");
+}
+
+function deviceTokens(value) {
+  return value.split(" ").filter(Boolean);
+}
+
+function deviceQuery(value) {
+  if (typeof value !== "string") {
+    fail("invalid_device_query", "The Spotify device name is invalid.");
+  }
+  const trimmed = value.trim();
+  if (
+    !trimmed ||
+    Array.from(trimmed).length > SPOTIFY_SERVICE_LIMITS.deviceNameLengthMax
+  ) {
+    fail("invalid_device_query", "The Spotify device name is invalid.");
+  }
+  const normalized = normalizeDeviceLabel(trimmed);
+  if (!normalized) {
+    fail("invalid_device_query", "The Spotify device name is invalid.");
+  }
+  return { display: trimmed, normalized };
+}
+
+function meaningfulTokens(normalized) {
+  const tokens = deviceTokens(normalized).filter(
+    (token) => !DEVICE_QUERY_FILLER.has(token),
+  );
+  return tokens.length > 0 ? tokens : deviceTokens(normalized);
+}
+
+function tokenIsSpecific(token) {
+  return token.length >= 3 || /[^\u0000-\u007f]/u.test(token);
+}
+
+function tokenMatches(nameToken, queryToken) {
+  if (nameToken === queryToken) return true;
+  if (queryToken.length < 3 || DEVICE_TYPE_ALIASES.has(queryToken)) return false;
+  return nameToken.startsWith(queryToken);
+}
+
+function nameMatchScore(device, queryNormalized, tokens) {
+  const name = normalizeDeviceLabel(device.name ?? "");
+  if (!name) return 0;
+  if (name === queryNormalized) return 3;
+  const nameTokens = deviceTokens(name);
+  const matched =
+    tokens.length > 0 &&
+    tokens.every(
+      (token) =>
+        tokenIsSpecific(token) &&
+        nameTokens.some((nameToken) => tokenMatches(nameToken, token)),
+    );
+  if (matched) return 2;
+  // Windows is a common listener label for a device Spotify names "PC".
+  // This is a name alias only, never an inference that every Computer is Windows.
+  return tokens.includes("windows") && tokens.every(token => ["windows", "pc"].includes(token)) && nameTokens.includes("pc") ? 1 : 0;
+}
+
+function sharedTypeAlias(tokens) {
+  let type = null;
+  if (tokens.length === 0) return null;
+  for (const token of tokens) {
+    const alias = DEVICE_TYPE_ALIASES.get(token);
+    if (!alias || (type && alias !== type)) return null;
+    type = alias;
+  }
+  return type;
+}
+
+function deviceListLabel(device) {
+  const details = [];
+  if (device.type && device.type !== "unknown") details.push(device.type);
+  if (device.is_active === true) details.push("active");
+  if (device.is_restricted === true) details.push("restricted");
+  const name = clipText(device.name, 48);
+  return details.length > 0 ? `${name} (${details.join(", ")})` : name;
+}
+
+function fitDeviceMessage(lead, devices, tail) {
+  const labels = [];
+  for (const device of devices) {
+    const candidate = `${lead}${[...labels, deviceListLabel(device)].join("; ")}${tail}`;
+    if (Array.from(candidate).length > 220 && labels.length > 0) break;
+    labels.push(deviceListLabel(device));
+  }
+  const hidden = devices.length - labels.length;
+  const hiddenNote = hidden > 0 ? ` +${hidden} more` : "";
+  const message = `${lead}${labels.join("; ")}${hiddenNote}${tail}`;
+  return Array.from(message).length > 240
+    ? Array.from(message).slice(0, 240).join("")
+    : message;
+}
+
+// Spotify names a desktop device after its computer, so "Audiofool's MacBook Pro" and the
+// host name "Audiofools-MacBook-Pro.local" are one machine once case and punctuation go.
+const deviceNameKey = name => typeof name === "string"
+  ? name.normalize("NFKC").toLocaleLowerCase("en-US").replace(/\.local$/u, "").replace(/[^\p{L}\p{N}]+/gu, "") : "";
+
+let computerName;
+// The name Spotify gives this computer: the Mac's Computer Name, or else the host name.
+// It stays on this machine; it only picks between devices Spotify already listed.
+export function thisComputerName() {
+  computerName ??= new Promise(resolve => {
+    if (process.platform !== "darwin") return resolve(hostname());
+    execFile("/usr/sbin/scutil", ["--get", "ComputerName"], { timeout: 1_000 },
+      (error, stdout) => resolve(error ? hostname() : String(stdout).trim()));
+  });
+  return computerName;
+}
+
+// With nothing active, the obvious device is the only one, or the machine running Moondog:
+// the only computer, or the one named like this computer. Anything else stays an explicit choice.
+export function preferredIdleDevice(devices, { thisComputer } = {}) {
+  const usable = devices.filter(device => device.is_restricted !== true);
+  if (usable.length === 1) return usable[0];
+  const computers = usable.filter(device => device.type?.toLocaleLowerCase("en-US") === "computer");
+  if (computers.length === 1) return computers[0];
+  const here = deviceNameKey(thisComputer);
+  const matches = here ? computers.filter(device => deviceNameKey(device.name) === here) : [];
+  return matches.length === 1 ? matches[0] : null;
+}
+
+// Spotify answered and refused the request itself. Sign-in, permission and rate limits
+// are left out: sending something else would not get past them.
+function definiteRefusal(error) {
+  return Number.isInteger(error?.status) && error.status >= 400 && error.status < 500 &&
+    ![401, 403, 429].includes(error.status) && error.outcomeUnknown === false && error.reason !== "NO_ACTIVE_DEVICE";
+}
+
+function refusedMove(error, target, player) {
+  if (error?.outcomeUnknown || error?.name === "AbortError") return error;
+  const stayed = player?.device?.name ? clipText(player.device.name, 80) : null;
+  const refused = new SpotifyServiceError("spotify_device_refused",
+    `Spotify would not move playback to ${clipText(target.name, 80)}, either as a transfer or as a song started there. ` +
+    `${stayed ? `Playback stays on ${stayed}${player.is_playing === false ? ", paused" : ""}. ` : ""}` +
+    "The Spotify app on that device usually needs to be open and played once before it accepts remote control.");
+  refused.status = error?.status;
+  refused.playbackStayedOn = stayed;
+  return refused;
+}
+
+function listedDevices(result) {
+  return (Array.isArray(result?.devices) ? result.devices : []).filter(
+    (device) =>
+      typeof device?.id === "string" &&
+      device.id.length > 0 &&
+      typeof device?.name === "string" &&
+      device.name.trim().length > 0,
+  );
+}
+
+function requireTransferDevice(chosen, display) {
+  if (chosen.length === 1 && chosen[0].is_restricted === true) {
+    failBeforeDispatch(
+      "spotify_device_restricted",
+      `Spotify does not allow Web API control on ${clipText(chosen[0].name, 80)}. Pick another device.`,
+    );
+  }
+  const controllable = chosen.filter((device) => device.is_restricted !== true);
+  if (controllable.length === 1 && chosen.length === 1) return controllable[0];
+  if (controllable.length === 0) {
+    failBeforeDispatch(
+      "spotify_device_restricted",
+      fitDeviceMessage(
+        "Spotify will not take playback on the matching devices: ",
+        chosen,
+        ".",
+      ),
+    );
+  }
+  failDeviceSelection(
+    "spotify_device_ambiguous",
+    fitDeviceMessage(
+      `Several Spotify devices match "${display}": `,
+      chosen,
+      ". Say which one.",
+    ),
+    chosen,
+  );
+}
+
+async function resolveNamedDevice(client, deviceName, { signal } = {}) {
+  const query = deviceQuery(deviceName);
+  const devices = listedDevices(await client.getDevices({ signal }));
+  signal?.throwIfAborted();
+  if (devices.length === 0) {
+    failBeforeDispatch(
+      "spotify_device_not_found",
+      "No Spotify devices are visible. Open Spotify on that device and try again.",
+    );
+  }
+  const tokens = meaningfulTokens(query.normalized);
+  let bestScore = 0;
+  let named = [];
+  for (const device of devices) {
+    const score = nameMatchScore(device, query.normalized, tokens);
+    if (score === 0 || score < bestScore) continue;
+    if (score > bestScore) {
+      bestScore = score;
+      named = [device];
+    } else {
+      named.push(device);
+    }
+  }
+  const type = named.length === 0 ? sharedTypeAlias(tokens) : null;
+  const chosen = named.length > 0
+    ? named
+    : devices.filter(
+        (device) => (device.type ?? "").toLocaleLowerCase("en-US") === type,
+      );
+  if (chosen.length === 0) {
+    failDeviceSelection(
+      "spotify_device_no_match",
+      fitDeviceMessage(
+        `No Spotify device matches "${clipText(query.display, 40)}". Visible now: `,
+        devices,
+        ".",
+      ),
+      devices,
+    );
+  }
+  const display = clipText(query.display, 40);
+  return requireTransferDevice(chosen, display);
+}
+
+async function queueDeviceId(client, requestedDeviceId, { signal } = {}) {
   const explicit = optionalDeviceId(requestedDeviceId);
   if (explicit) return explicit;
 
-  const result = await client.getDevices();
+  const result = await client.getDevices({ signal });
   const devices = Array.isArray(result?.devices) ? result.devices : [];
   const controllable = devices.filter(
     (device) =>
@@ -324,12 +693,12 @@ async function queueDeviceId(client, requestedDeviceId) {
   if (active) return active.id;
   if (controllable.length === 1) return controllable[0].id;
   if (devices.length > 0 && controllable.length === 0) {
-    fail(
+    failBeforeDispatch(
       "spotify_device_restricted",
       "Spotify's available devices do not accept Web API controls. Open Spotify on another device and try again.",
     );
   }
-  fail(
+  failBeforeDispatch(
     "spotify_active_device_required",
     "No active Spotify device is available. Open Spotify on one device and start playback, then try again.",
   );
@@ -340,25 +709,229 @@ export function createSpotifyService(options = {}) {
   if (!client || typeof client !== "object") {
     throw new TypeError("A Spotify Web API client is required.");
   }
+  const readinessTimeout = options.playbackReadinessTimeoutMs ?? SPOTIFY_SERVICE_LIMITS.playbackReadinessTimeoutMs;
+  if (!Number.isInteger(readinessTimeout) || readinessTimeout < 1 || readinessTimeout > 5_000) throw new TypeError("Invalid Spotify playback preparation timeout.");
+  const readinessSleep = options.playbackReadinessSleep ?? ((ms, { signal }) => delay(ms, undefined, { signal }));
+  // Tests name the computer, or pass null for none; otherwise the system names it, once.
+  const thisComputer = async () => (options.thisComputerName !== undefined ? options.thisComputerName : thisComputerName());
+
+  async function preparedResume(input, { signal, preferredDeviceId, allowDeviceSwitch = input.deviceId !== undefined, allowTransfer = true, excludedDeviceNames = [], onDeviceSelected, beforeDispatch, trackFallback = false } = {}) {
+    const effects = [];
+    const deadline = Date.now() + readinessTimeout;
+    let snapshots = 0, readRecoveries = 0, playAttempts = 0, writeStarted = false, phase = "read";
+    let recovered = false, fellBack = false, selected;
+    const stop = (code, message) => failBeforeDispatch(code, message);
+    // Reads and delays are bounded even if an injected transport ignores abort.
+    // Dispatched writes retain the client's separate settlement deadline.
+    const boundedRead = async operation => {
+      signal?.throwIfAborted();
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) stop("spotify_device_not_ready", "Spotify device readiness timed out. Open Spotify on the selected device, then request playback again.");
+      const controller = new AbortController();
+      const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+      let timer, abort;
+      try {
+        return await Promise.race([Promise.resolve().then(() => operation(combined)), new Promise((_, reject) => {
+          abort = () => reject(combined.reason);
+          combined.addEventListener("abort", abort, { once: true });
+          timer = setTimeout(() => controller.abort(new SpotifyServiceError("spotify_device_not_ready", "Spotify device readiness timed out. Open Spotify on the selected device, then request playback again.")), remaining);
+        })]);
+      } finally { clearTimeout(timer); combined.removeEventListener("abort", abort); controller.abort(); }
+    };
+    const snapshot = async (wait = false) => {
+      phase = "read";
+      if (snapshots >= SPOTIFY_SERVICE_LIMITS.playbackReadinessSnapshotsMax) stop("spotify_device_not_ready", "Spotify has not made the selected device ready. Open Spotify on it, then request playback again.");
+      if (wait) await boundedRead(readSignal => readinessSleep(SPOTIFY_SERVICE_LIMITS.playbackReadinessPollMs, { signal: readSignal }));
+      snapshots++;
+      let listing, player;
+      try {
+        [listing, player] = await boundedRead(readSignal => Promise.all([
+          client.getDevices({ signal: readSignal }), client.getCurrentPlayback({ signal: readSignal }),
+        ]));
+      } catch (error) {
+        // A transient read failure is safe to recover. Keep the same snapshot
+        // count and deadline; this never grants another playback/transfer write.
+        if (error?.code === "spotify_network_error" && readRecoveries++ === 0 && !signal?.aborted) return snapshot(true);
+        throw error;
+      }
+      signal?.throwIfAborted();
+      if (!Array.isArray(listing?.devices) || !["available", "inactive"].includes(player?.state)) stop("spotify_device_state_unconfirmed", "Spotify did not return a usable device and playback state. Check Spotify before requesting playback again.");
+      const devices = listedDevices(listing);
+      if (new Set(devices.map(device => device.id)).size !== devices.length) stop("spotify_device_state_unconfirmed", "Spotify returned conflicting device entries. Check Spotify's device selector before trying again.");
+      const active = new Set(devices.filter(device => device.is_active === true).map(device => device.id));
+      if (player.device?.is_active === true) active.add(player.device.id);
+      if (active.size > 1) stop("spotify_device_state_unconfirmed", "Spotify device and playback snapshots disagree. Check the active device before trying again.");
+      return { devices, player, active: [...active][0], truncated: listing.truncated === true };
+    };
+    const find = (state, id) => {
+      const device = state.devices.find(entry => entry.id === id);
+      if (!device) stop("spotify_device_not_found", "The selected Spotify device is not visible. Open Spotify on that device and request playback again; no other device was substituted.");
+      if (device.is_restricted !== false) stop("spotify_device_restricted", "The selected device does not confirm Web API control. Choose another available Spotify device.");
+      if (excludedDeviceNames.some(name => {
+        const query = deviceQuery(name), tokens = meaningfulTokens(query.normalized);
+        return nameMatchScore(device, query.normalized, tokens) > 0 || sharedTypeAlias(tokens) === device.type?.toLocaleLowerCase("en-US");
+      })) stop("spotify_device_selection_not_authorized", "The listener excluded the selected device. Specify another available Spotify device before playing.");
+      return device;
+    };
+    const check = state => {
+      selected = find(state, selected.id);
+      if (state.player.device?.id === selected.id && state.player.device.is_restricted === true) stop("spotify_device_restricted", "Spotify playback state restricts control of this device. Choose another available device.");
+      if (state.active && state.active !== selected.id && !allowDeviceSwitch) stop("spotify_device_changed", "Another Spotify device became active. Choose the intended device explicitly; playback was not moved automatically.");
+      // These flags describe controls for the current playback context. Starting
+      // a requested URI/context is not resuming the old item, and another device
+      // must not inherit the old device's contextual resume restriction.
+      if (!input.uris && !input.contextUri && state.player.device?.id === selected.id &&
+          state.player.is_playing !== true && state.player.disallowed_actions?.includes("resuming")) stop("spotify_playback_restricted", "Spotify currently disallows resuming this playback context. Choose a song to start or check the selected device.");
+    };
+    const prepare = async (state, afterRejection = false) => {
+      check(state);
+      if (selected.is_active === true && state.active === selected.id) return state;
+      // play:false preserves the previous state. It is safe preparation only
+      // with affirmative evidence of paused playback, never from a 204/unknown
+      // response or a currently playing session (which could play the old song).
+      const paused = state.player.state === "available" && state.player.is_playing === false;
+      if (!allowTransfer || !paused || state.truncated || state.player.disallowed_actions?.includes("transferring_playback")) {
+        if (afterRejection) stop("spotify_device_not_ready", "Spotify rejected playback because the selected device is not ready. Open Spotify on that device, then request the same song again.");
+        return state; // One exact-target play can work without a separate transfer.
+      }
+      if (!effects.length) {
+        signal?.throwIfAborted(); phase = "transfer";
+        await client.transfer({ deviceId: selected.id, play: false }, { signal, beforeDispatch: () => { signal?.throwIfAborted(); beforeDispatch?.(); writeStarted = true; } });
+        writeStarted = true;
+        effects.push({ ...actionReceipt("playback.transfer"), device: { name: selected.name, type: selected.type ?? "unknown" } });
+      }
+      while (true) {
+        state = await snapshot(true); check(state);
+        if (selected.is_active === true && state.active === selected.id) return state;
+      }
+    };
+    try {
+      let state = await snapshot();
+      const id = input.deviceId ?? state.active ?? preferredDeviceId ??
+        (state.truncated ? null : preferredIdleDevice(state.devices, { thisComputer: await thisComputer() })?.id);
+      if (id) selected = find(state, id);
+      else {
+        if (state.truncated || state.devices.length !== 1) stop(state.devices.length ? "spotify_device_ambiguous" : "spotify_device_not_found",
+          state.devices.length ? "Several Spotify devices may be available. Choose the intended device by name before playing." : "No Spotify Connect device is visible. Open Spotify on the intended device and request playback again.");
+        selected = find(state, state.devices[0].id);
+      }
+      onDeviceSelected?.(selected.id);
+      input = { ...input, deviceId: selected.id }; // Frozen before any write.
+      // A plain resume on the device that is already playing has nothing to do.
+      if (!input.uris && !input.contextUri && input.positionMs === undefined && state.active === selected.id && state.player.is_playing === true) {
+        return { ...actionReceipt("playback.resume"), already: true, device: { name: selected.name, type: selected.type ?? "unknown" } };
+      }
+      state = await prepare(state);
+      for (;;) {
+        signal?.throwIfAborted(); phase = "resume";
+        try { await client.resume(input, { signal, beforeDispatch: () => { signal?.throwIfAborted(); beforeDispatch?.(); writeStarted = true; playAttempts++; } }); break; }
+        catch (error) {
+          // A song started inside its album can meet an album Spotify will not start
+          // there. A definite refusal played nothing, so send the song alone once.
+          if (trackFallback && !fellBack && input.contextUri && input.offsetUri && definiteRefusal(error) && !signal?.aborted) {
+            fellBack = true;
+            const { contextUri: _contextUri, offsetUri, ...rest } = input;
+            input = { ...rest, uris: [offsetUri] };
+            continue;
+          }
+          // A definite NO_ACTIVE_DEVICE rejection is the other recoverable
+          // play response. No queue/skip/transfer or uncertain write is replayed.
+          if (playAttempts !== 1 || error?.status !== 404 || error.reason !== "NO_ACTIVE_DEVICE" || error.outcomeUnknown !== false || signal?.aborted) throw error;
+          recovered = true;
+          state = await snapshot(true);
+          await prepare(state, true);
+        }
+      }
+      return { ...actionReceipt("playback.resume"), device: { name: selected.name, type: selected.type ?? "unknown" },
+        ...(effects.length ? { preparation_effects: effects } : {}), ...(recovered ? { recovered_no_active_device: true } : {}) };
+    } catch (error) {
+      // Retain accepted preparation even if a later read, cancellation, or play
+      // fails. A preparation failure must not claim that the song was dispatched.
+      error.playbackPreparation = effects;
+      error.playbackAction = phase === "transfer" ? "playback.transfer" : "playback.resume";
+      error.playbackNotDispatched = playAttempts === 0;
+      error.playbackPreparationStopped = true;
+      error.playbackReadFailure = phase === "read";
+      error.playbackRecoveryAttempted = recovered;
+      if (phase === "read") error.outcomeUnknown = false;
+      if (!writeStarted) error.actionNotDispatched = true;
+      else delete error.actionNotDispatched;
+      throw error;
+    }
+  }
 
   return Object.freeze({
-    account() {
-      return client.getAccount();
+    account(options) {
+      return client.getAccount(options);
+    },
+
+    currentPlayer(options) {
+      return client.getCurrentPlayback(options);
+    },
+
+    devices(options) {
+      return client.getDevices(options);
     },
 
-    currentPlayer() {
-      return client.getCurrentPlayback();
+    async resolveDevice(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      if (input.deviceId !== undefined && input.deviceName !== undefined) fail("conflicting_device_target", "Choose one device target.");
+      let device;
+      if (input.deviceName !== undefined) device = await resolveNamedDevice(client, input.deviceName, { signal });
+      else {
+        const id = optionalDeviceId(input.deviceId);
+        const devices = listedDevices(await client.getDevices({ signal }));
+        signal?.throwIfAborted();
+        const matching = devices.filter((item) => id ? item.id === id : item.is_active === true);
+        if (matching.length === 0) failBeforeDispatch("spotify_device_not_found", "That Spotify device is no longer available. List devices again or open Spotify on it.");
+        device = requireTransferDevice(matching, "selected device");
+      }
+      if (input.forVolume && device.supports_volume === false) failBeforeDispatch("spotify_volume_unsupported", "Spotify cannot change this device's volume through the Web API. Use its hardware or Spotify app volume control.");
+      return device;
     },
 
-    devices() {
-      return client.getDevices();
+    queue(options) {
+      return client.getQueue(options);
     },
 
-    queue() {
-      return client.getQueue();
+    // The playlist the active device plays from: its name, size and first songs. Spotify's own
+    // editorial and generated playlists answer most apps with not found, and some playlists keep
+    // their songs from apps; the songs are then null.
+    async playingPlaylist({ uri } = {}, { signal } = {}) {
+      const playlistId = requiredPlaylistId(String(uri ?? "").replace(/^spotify:playlist:/u, ""));
+      const playlist = await client.getPlaylist({ playlistId }, { signal });
+      if (!playlist) fail("spotify_playlist_unavailable", "Spotify did not describe this playlist.");
+      const page = await client.getPlaylistItems({ playlistId, limit: SPOTIFY_SERVICE_LIMITS.playlistItemsPageMax, offset: 0 }, { signal })
+        .catch((error) => (signal?.aborted ? Promise.reject(error) : null));
+      return { name: playlist.name, uri: playlist.uri, tracks_total: playlist.tracks_total ?? null,
+        tracks: page ? page.items.map((entry) => entry.item).filter(Boolean) : null };
     },
 
-    async recentActivity(value) {
+    // One device decision for a whole queue request. An idle device cannot take a
+    // queue entry, so the caller starts the first song there and queues the rest.
+    async queueTarget(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value ?? {});
+      // A named device needs no lookup: an idle one answers NO_ACTIVE_DEVICE and the caller starts playback there.
+      const explicit = optionalDeviceId(input.deviceId);
+      if (explicit) return { deviceId: explicit, active: null };
+      const [listing, player] = await Promise.all([client.getDevices({ signal }), client.getCurrentPlayback({ signal })]);
+      signal?.throwIfAborted();
+      const devices = listedDevices(listing);
+      const describe = device => ({ deviceId: device.id, device: { name: device.name, type: device.type ?? "unknown" } });
+      const active = devices.find(device => device.is_active === true && device.is_restricted !== true) ??
+        (player?.device?.is_active === true ? devices.find(device => device.id === player.device.id && device.is_restricted !== true) : undefined);
+      if (active) return { ...describe(active), active: true };
+      const idle = preferredIdleDevice(devices, { thisComputer: await thisComputer() });
+      if (idle) return { ...describe(idle), active: false };
+      failBeforeDispatch(devices.length ? "spotify_device_ambiguous" : "spotify_device_not_found", devices.length
+        ? `Nothing is playing, and several Spotify devices are available (${devices.map(device => device.name).slice(0, 5).join(", ")}). Say which one to use.`
+        : "No Spotify device is open. Open Spotify on this computer or your phone, then ask again.");
+    },
+
+    async recentActivity(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const after = recentCursor(input.after, "after");
       const before = recentCursor(input.before, "before");
@@ -372,16 +945,97 @@ export function createSpotifyService(options = {}) {
         limit: recentLimit(input.limit),
         ...(after !== undefined ? { after } : {}),
         ...(before !== undefined ? { before } : {}),
-      });
+      }, { signal });
+    },
+
+    // A bounded read of the whole library for a profile import, never an action.
+    async librarySnapshot({ signal, onProgress } = {}) {
+      signal?.throwIfAborted();
+      return readSpotifyLibrarySnapshot(client, { signal, onProgress });
+    },
+
+    async topItems(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      const type = input.type ?? "tracks";
+      const timeRange = input.timeRange ?? "medium_term";
+      if (!["artists", "tracks"].includes(type) || !["short_term", "medium_term", "long_term"].includes(timeRange)) {
+        fail("invalid_top_items", "Spotify top items require artists or tracks and short_term, medium_term, or long_term.");
+      }
+      const limit = searchLimit(input.limit);
+      const result = await client.getTopItems({ type, timeRange, limit }, { signal });
+      signal?.throwIfAborted();
+      const items = Array.isArray(result?.items) ? result.items : [];
+      return { provider: "spotify", type, time_range: timeRange,
+        evidence_basis: "spotify_calculated_affinity", items: items.slice(0, limit),
+        truncated: result?.truncated === true || items.length > limit };
+    },
+
+    async libraryBrowse(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      const type = input.type ?? "tracks";
+      const limit = input.limit ?? 10;
+      if (!["tracks", "albums", "shows", "playlists", "artists"].includes(type) || !Number.isInteger(limit) || limit < 1 || limit > 20) {
+        fail("invalid_library_page", "Browse saved tracks, albums, shows, playlists, or followed artists with a limit from 1 to 20.");
+      }
+      if (type === "artists") {
+        if (input.offset !== undefined || input.after !== undefined && (typeof input.after !== "string" || !/^[A-Za-z0-9]{1,128}$/u.test(input.after))) fail("invalid_artist_cursor", "Use the returned after cursor for followed artists, not offset.");
+        return client.getFollowedArtists({ limit, after: input.after }, { signal });
+      }
+      if (input.after !== undefined) fail("invalid_library_cursor", "Use offset for this library type.");
+      return client.getSavedItems({ type, limit, offset: playlistPageOffset(input.offset) }, { signal });
+    },
+
+    async searchTracks(value, { signal } = {}) {
+      const input = inputObject(value);
+      const type = input.type ?? "track";
+      if (!["track", "album", "artist", "playlist", "show", "episode"].includes(type)) fail("invalid_search_type", "Choose track, album, artist, playlist, show, or episode.");
+      const offset = input.offset ?? 0;
+      if (!Number.isInteger(offset) || offset < 0 || offset > 1000) fail("invalid_search_offset", "Search offset must be from 0 to 1000.");
+      if (type !== "track" || offset !== 0) return client.searchItems({ query: searchQuery(input.query), type, limit: searchLimit(input.limit), offset }, { signal });
+      return client.searchTracks({
+        query: searchQuery(input.query),
+        limit: searchLimit(input.limit),
+      }, { signal });
     },
 
-    async editablePlaylists(value) {
+    async catalogChildren(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      if (!["album", "show"].includes(input.type) || typeof input.id !== "string" || !/^[A-Za-z0-9]{1,128}$/u.test(input.id)) fail("invalid_catalog_parent", "Choose a returned album or show reference.");
+      const limit = input.limit ?? 10;
+      if (!Number.isInteger(limit) || limit < 1 || limit > 20) fail("invalid_catalog_limit", "Read from 1 to 20 album tracks or episodes per page.");
+      return client.getCatalogChildren({ type: input.type, id: input.id, limit, offset: playlistPageOffset(input.offset) }, { signal });
+    },
+
+    async saveItems(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const uris = inputObject(value).uris;
+      if (!Array.isArray(uris) || uris.length < 1 || uris.length > 12 || uris.some((uri) => typeof uri !== "string" || !/^spotify:(?:track|album|episode|show|playlist):[A-Za-z0-9]{1,128}$/u.test(uri))) fail("invalid_library_items", "Choose from 1 to 12 returned Spotify items.");
+      const unique = [...new Set(uris)];
+      await client.saveTracks({ uris: unique }, { signal });
+      return { ...actionReceipt("library.save"), item_count: unique.length };
+    },
+
+    async removeSavedItem(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const uri = inputObject(value).uri;
+      if (typeof uri !== "string" || !/^spotify:(?:track|album|episode|show):[A-Za-z0-9]{1,128}$/u.test(uri)) fail("invalid_library_item", "Choose one returned saved item.");
+      await client.removeLibraryItems({ uris: [uri] }, { signal });
+      return { ...actionReceipt("library.remove"), item_count: 1 };
+    },
+
+    async editablePlaylists(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const limit = playlistPageLimit(input.limit);
       const offset = playlistPageOffset(input.offset);
-      const account = await client.getAccount();
+      const account = await client.getAccount({ signal });
+      signal?.throwIfAborted();
       const ownerId = accountId(account);
-      const page = await client.getCurrentUserPlaylists({ limit, offset });
+      const page = await client.getCurrentUserPlaylists({ limit, offset }, { signal });
+      signal?.throwIfAborted();
       const excluded = {
         public: 0,
         not_owned: 0,
@@ -390,6 +1044,10 @@ export function createSpotifyService(options = {}) {
         invalid: 0,
       };
       const playlists = [];
+      const names = new Map();
+      for (const item of page?.items ?? []) {
+        if (typeof item?.name === "string") names.set(item.name, (names.get(item.name) ?? 0) + 1);
+      }
       for (const playlist of Array.isArray(page?.items) ? page.items : []) {
         const reason = editablePlaylistReason(playlist, ownerId);
         if (reason) {
@@ -408,24 +1066,54 @@ export function createSpotifyService(options = {}) {
       return {
         provider: "spotify",
         playlists,
+        name_selection_complete: page?.complete_for_name_selection === true,
+        ambiguous_names: [...names].filter(([, count]) => count > 1).map(([name]) => name),
         excluded,
         has_more: hasMore,
         next_offset: hasMore ? pageOffset + pageLimit : null,
       };
     },
 
-    async playlistSnapshot(value) {
+    async playlistRemovalTarget(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const playlistId = requiredPlaylistId(input.playlistId);
-      const account = await client.getAccount();
+      const account = await client.getAccount({ signal });
+      signal?.throwIfAborted();
+      const playlist = await client.getPlaylist({ playlistId }, { signal });
+      signal?.throwIfAborted();
+      if (playlist?.id !== playlistId || playlist.owner_id !== accountId(account) || playlist.is_public !== false || playlist.collaborative !== false ||
+          typeof playlist.name !== "string" || !playlist.name || playlist.uri !== `spotify:playlist:${playlistId}`) {
+        fail("playlist_not_removable", "Remove only a verified owned private, non-collaborative playlist from your library.");
+      }
+      return { playlistId, name: playlist.name, snapshotId: requiredSnapshotId(playlist.snapshot_id) };
+    },
+
+    async removePlaylistFromLibrary(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      const current = await this.playlistRemovalTarget(input, { signal });
+      if (current.name !== input.expectedName || current.snapshotId !== input.expectedSnapshotId) fail("playlist_snapshot_changed", "The playlist changed since confirmation was prepared. Review it again.");
+      signal?.throwIfAborted();
+      await client.removeLibraryItems({ uris: [`spotify:playlist:${current.playlistId}`] }, { signal });
+      return { ...actionReceipt("playlist.unfollow"), playlist: { name: current.name, is_public: false } };
+    },
+
+    async playlistSnapshot(value, { signal } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      const playlistId = requiredPlaylistId(input.playlistId);
+      const account = await client.getAccount({ signal });
+      signal?.throwIfAborted();
       const ownerId = accountId(account);
       const before = requireEditablePlaylist(
-        await client.getPlaylist({ playlistId }),
+        await client.getPlaylist({ playlistId }, { signal }),
         ownerId,
       );
       const tracks = [];
       let offset = 0;
       while (offset < before.tracks_total) {
+        signal?.throwIfAborted();
         const page = await client.getPlaylistItems({
           playlistId,
           limit: Math.min(
@@ -433,7 +1121,7 @@ export function createSpotifyService(options = {}) {
             before.tracks_total - offset,
           ),
           offset,
-        });
+        }, { signal });
         if (
           !isPlainObject(page) ||
           page.total !== before.tracks_total ||
@@ -457,11 +1145,15 @@ export function createSpotifyService(options = {}) {
           );
         }
       }
+      signal?.throwIfAborted();
       const after = requireEditablePlaylist(
-        await client.getPlaylist({ playlistId }),
+        await client.getPlaylist({ playlistId }, { signal }),
         ownerId,
       );
+      signal?.throwIfAborted();
       if (
+        before.id !== playlistId || after.id !== playlistId ||
+        after.name !== before.name ||
         after.snapshot_id !== before.snapshot_id ||
         after.tracks_total !== before.tracks_total ||
         tracks.length !== before.tracks_total
@@ -483,15 +1175,51 @@ export function createSpotifyService(options = {}) {
       };
     },
 
-    async replacePlaylistItems(value) {
+    async quickEditPlaylist(value, { signal, beforeWrite } = {}) {
+      signal?.throwIfAborted();
+      const input = inputObject(value);
+      const playlistId = requiredPlaylistId(input.playlistId);
+      const expectedSnapshotId = requiredSnapshotId(input.expectedSnapshotId);
+      if (!["rename", "remove_track"].includes(input.action)) fail("invalid_playlist_edit", "Unsupported quick playlist edit.");
+      const current = await this.playlistSnapshot({ playlistId }, { signal });
+      if (current.playlist.snapshot_id !== expectedSnapshotId || current.playlist.name !== input.expectedName ||
+          current.items.length !== input.expectedTrackCount) {
+        fail("playlist_snapshot_changed", "The playlist changed after inspection. Inspect it again before editing.");
+      }
+      let name = current.playlist.name;
+      let count = current.items.length;
+      if (input.action === "rename") {
+        name = cleanPlaylistText(input.name, 100, "invalid_playlist_name", "name");
+        if (name !== input.name || name === current.playlist.name) fail("invalid_playlist_name", "The exact new playlist name must be valid and different.");
+        beforeWrite?.();
+        signal?.throwIfAborted();
+        await client.renamePlaylist({ playlistId, name }, { signal, beforeDispatch: beforeWrite });
+      } else {
+        const uri = requiredItemUri(input.uri);
+        if (!trackUriPattern.test(uri) || current.items.filter((item) => item.uri === uri).length !== 1) {
+          fail("playlist_removal_ambiguous", "Single-track removal requires exactly one occurrence. Preview the exact final order for duplicates or bulk edits.");
+        }
+        beforeWrite?.();
+        signal?.throwIfAborted();
+        await client.removePlaylistItem({ playlistId, uri, snapshotId: expectedSnapshotId }, { signal, beforeDispatch: beforeWrite });
+        count -= 1;
+      }
+      return { ...actionReceipt(input.action === "rename" ? "playlist.rename" : "playlist.remove_track"),
+        playlist: { name, track_count: count, is_public: false }, previous_track_count: current.items.length,
+        ...(input.action === "remove_track" ? { track_count: 1 } : {}) };
+    },
+
+    async replacePlaylistItems(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const playlistId = requiredPlaylistId(input.playlistId);
       const expectedSnapshotId = requiredSnapshotId(input.expectedSnapshotId);
       const uris = requiredPlaylistEditTrackUris(input.uris);
-      const account = await client.getAccount();
+      const account = await client.getAccount({ signal });
+      signal?.throwIfAborted();
       const ownerId = accountId(account);
       const playlist = requireEditablePlaylist(
-        await client.getPlaylist({ playlistId }),
+        await client.getPlaylist({ playlistId }, { signal }),
         ownerId,
       );
       if (playlist.snapshot_id !== expectedSnapshotId) {
@@ -500,7 +1228,8 @@ export function createSpotifyService(options = {}) {
           "The Spotify playlist changed after preview. Inspect it again before editing.",
         );
       }
-      await client.replacePlaylistItems({ playlistId, uris });
+      signal?.throwIfAborted();
+      await client.replacePlaylistItems({ playlistId, uris }, { signal });
       return {
         ...actionReceipt("playlist.edit"),
         playlist: {
@@ -512,7 +1241,8 @@ export function createSpotifyService(options = {}) {
       };
     },
 
-    async resume(value) {
+    async resume(value, { signal, ...preparation } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const contextUri = optionalContextUri(input.contextUri);
       const uris = optionalUris(input.uris);
@@ -528,36 +1258,51 @@ export function createSpotifyService(options = {}) {
       if (offsetPosition !== undefined && offsetUri !== undefined) {
         fail("conflicting_offset", "Choose one Spotify playback offset.");
       }
-      await client.resume({
+      // Spotify starts partway only into an album or a playlist, not an artist.
+      if ((offsetPosition !== undefined || offsetUri !== undefined) && contextUri && !/^spotify:(?:album|playlist):/u.test(contextUri)) {
+        fail("invalid_spotify_offset", "Spotify can start partway only into an album or a playlist.");
+      }
+      return preparedResume({
         deviceId: optionalDeviceId(input.deviceId),
         contextUri,
         uris,
         offsetPosition,
         offsetUri,
         positionMs: optionalPosition(input.positionMs, "invalid_position"),
-      });
-      return actionReceipt("playback.resume");
+      }, { signal, ...preparation });
     },
 
-    async pause(value) {
+    async pause(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
-      await client.pause({ deviceId: optionalDeviceId(input.deviceId) });
+      try {
+        await client.pause({ deviceId: optionalDeviceId(input.deviceId) }, { signal });
+      } catch (error) {
+        // Spotify refuses to pause a player that is already paused; that is the requested state.
+        if (error?.status !== 403 || error.outcomeUnknown) throw error;
+        const player = await Promise.resolve().then(() => client.getCurrentPlayback({ signal })).catch(() => null);
+        if (player?.state === "available" && player.is_playing === false) return { ...actionReceipt("playback.pause"), already: true };
+        throw error;
+      }
       return actionReceipt("playback.pause");
     },
 
-    async next(value) {
+    async next(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
-      await client.next({ deviceId: optionalDeviceId(input.deviceId) });
+      await client.next({ deviceId: optionalDeviceId(input.deviceId) }, { signal });
       return actionReceipt("playback.next");
     },
 
-    async previous(value) {
+    async previous(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
-      await client.previous({ deviceId: optionalDeviceId(input.deviceId) });
+      await client.previous({ deviceId: optionalDeviceId(input.deviceId) }, { signal });
       return actionReceipt("playback.previous");
     },
 
-    async setVolume(value) {
+    async setVolume(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       if (!Number.isInteger(input.percent) || input.percent < 0 || input.percent > 100) {
         fail("invalid_volume", "Spotify volume must be an integer from 0 to 100.");
@@ -565,11 +1310,12 @@ export function createSpotifyService(options = {}) {
       await client.setVolume({
         percent: input.percent,
         deviceId: optionalDeviceId(input.deviceId),
-      });
+      }, { signal });
       return actionReceipt("playback.volume.set");
     },
 
-    async seek(value) {
+    async seek(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       if (input.positionMs === undefined) {
         fail("invalid_position", "The Spotify playback position is invalid.");
@@ -577,11 +1323,12 @@ export function createSpotifyService(options = {}) {
       await client.seek({
         positionMs: optionalPosition(input.positionMs, "invalid_position"),
         deviceId: optionalDeviceId(input.deviceId),
-      });
+      }, { signal });
       return actionReceipt("playback.seek");
     },
 
-    async setShuffle(value) {
+    async setShuffle(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       if (typeof input.state !== "boolean") {
         fail("invalid_shuffle_state", "Spotify shuffle state must be a boolean.");
@@ -589,11 +1336,12 @@ export function createSpotifyService(options = {}) {
       await client.setShuffle({
         state: input.state,
         deviceId: optionalDeviceId(input.deviceId),
-      });
+      }, { signal });
       return actionReceipt("playback.shuffle.set");
     },
 
-    async setRepeat(value) {
+    async setRepeat(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       if (!repeatStates.has(input.state)) {
         fail("invalid_repeat_state", "Spotify repeat state is invalid.");
@@ -601,33 +1349,75 @@ export function createSpotifyService(options = {}) {
       await client.setRepeat({
         state: input.state,
         deviceId: optionalDeviceId(input.deviceId),
-      });
+      }, { signal });
       return actionReceipt("playback.repeat.set");
     },
 
-    async transfer(value) {
+    async transfer(value, { signal, onDeviceSelected } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
-      const deviceId = optionalDeviceId(input.deviceId);
-      if (!deviceId) {
-        fail("invalid_device_id", "A Spotify device identifier is required.");
-      }
       if (input.play !== undefined && typeof input.play !== "boolean") {
         fail("invalid_play_state", "Spotify transfer play state must be a boolean.");
       }
-      await client.transfer({ deviceId, play: input.play ?? false });
-      return actionReceipt("playback.transfer");
+      const deviceId =
+        input.deviceId === undefined ? undefined : optionalDeviceId(input.deviceId);
+      const hasName = input.deviceName !== undefined;
+      if (deviceId && hasName) {
+        fail(
+          "conflicting_device_target",
+          "Pass either a Spotify device ID or a device name.",
+        );
+      }
+      if (!deviceId && !hasName) {
+        fail("invalid_device_id", "A Spotify device identifier is required.");
+      }
+      // Reads before the move are best effort: a failed read never blocks the move itself.
+      const tryRead = (read) => Promise.resolve().then(read).catch(() => null);
+      const device = deviceId
+        ? listedDevices(await tryRead(() => client.getDevices({ signal }))).find((entry) => entry.id === deviceId) ?? { id: deviceId, name: "the selected device" }
+        : await resolveNamedDevice(client, input.deviceName, { signal });
+      onDeviceSelected?.(device.id);
+      signal?.throwIfAborted();
+      const display = { name: device.name, type: device.type || "unknown" };
+      const player = await tryRead(() => client.getCurrentPlayback({ signal }));
+      signal?.throwIfAborted();
+      const playing = player?.state === "available" && player.is_playing === true;
+      const play = input.play ?? playing;
+      if (player?.device?.id === device.id && player.device.is_active !== false && (!play || playing)) {
+        return { ...actionReceipt("playback.transfer"), already: true, device: display };
+      }
+      try {
+        await client.transfer({ deviceId: device.id, play }, { signal });
+        return { ...actionReceipt("playback.transfer"), device: display };
+      } catch (error) {
+        // Spotify sometimes refuses a transfer that it accepts as a play request aimed at
+        // the device. Start the same song there, at the same moment, once.
+        const item = player?.item?.uri;
+        if (![403, 404, 502].includes(error?.status) || error.outcomeUnknown || !item || signal?.aborted) throw refusedMove(error, display, player);
+        try {
+          await client.resume({ deviceId: device.id, uris: [item], ...(Number.isInteger(player.progress_ms) ? { positionMs: player.progress_ms } : {}) }, { signal });
+        } catch (fallback) {
+          throw refusedMove(fallback, display, player);
+        }
+        if (!play) await client.pause({ deviceId: device.id }, { signal }).catch(() => {});
+        return { ...actionReceipt("playback.transfer"), device: display, method: "play_on_device" };
+      }
     },
 
-    async addToQueue(value) {
+    async addToQueue(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
-      await client.addToQueue({
-        uri: requiredItemUri(input.uri),
-        deviceId: await queueDeviceId(client, input.deviceId),
-      });
+      const uri = requiredItemUri(input.uri);
+      const deviceId = await queueDeviceId(client, input.deviceId, { signal });
+      signal?.throwIfAborted();
+      // Let a dispatched write settle so cancellation can report accepted effects.
+      // Never dispatch the next write after the prompt has been cancelled.
+      await client.addToQueue({ uri, deviceId }, { signal });
       return actionReceipt("playback.queue.add");
     },
 
-    async createPlaylistWithTracks(value) {
+    async createPlaylistWithTracks(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const name = cleanPlaylistText(
         input.name,
@@ -652,16 +1442,28 @@ export function createSpotifyService(options = {}) {
       const playlist = await client.createPlaylist({
         name,
         ...(description ? { description } : {}),
-      });
+      }, { signal });
       if (!playlist?.id) {
         fail(
           "playlist_creation_failed",
           "Spotify did not return the created playlist.",
+          { outcomeUnknown: true },
         );
       }
       try {
-        await client.addPlaylistTracks({ playlistId: playlist.id, uris });
-      } catch {
+        signal?.throwIfAborted();
+        await client.addPlaylistTracks({ playlistId: playlist.id, uris }, { signal });
+      } catch (error) {
+        const rejected = error?.outcomeUnknown === false ||
+          (Number.isInteger(error?.status) && error.status >= 400 && error.status < 500) ||
+          (error?.name === "AbortError" && signal?.aborted);
+        if (error?.outcomeUnknown === true || !rejected) {
+          fail(
+            "playlist_created_tracks_unknown",
+            "Spotify created the private playlist, but did not confirm whether its tracks were added. Check the playlist before trying again.",
+            { outcomeUnknown: true },
+          );
+        }
         fail(
           "playlist_created_without_tracks",
           "Spotify created the private playlist but did not accept its tracks. Check the empty playlist before trying again.",
@@ -679,28 +1481,30 @@ export function createSpotifyService(options = {}) {
       };
     },
 
-    async saveTracks(value) {
+    async saveTracks(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const uris = requiredTrackUris(
         input.uris,
         "invalid_library_tracks",
         SPOTIFY_SERVICE_LIMITS.libraryTracksMax,
       );
-      await client.saveTracks({ uris });
+      await client.saveTracks({ uris }, { signal });
       return {
         ...actionReceipt("library.save"),
         track_count: uris.length,
       };
     },
 
-    async checkSavedTracks(value) {
+    async checkSavedTracks(value, { signal } = {}) {
+      signal?.throwIfAborted();
       const input = inputObject(value);
       const uris = requiredTrackUris(
         input.uris,
         "invalid_library_tracks",
         SPOTIFY_SERVICE_LIMITS.libraryTracksMax,
       );
-      const saved = await client.checkSavedTracks({ uris });
+      const saved = await client.checkSavedTracks({ uris }, { signal });
       return {
         provider: "spotify",
         checked: uris.map((uri, index) => ({