// NAME: Enhanced Pins
// AUTHOR: yusufaf
// x-release-please-start-version
// VERSION: 1.3.0
// x-release-please-end-version
// DESCRIPTION: Unlimited pins in their own sidebar section, with sorting, icons, and backup
(function () {
'use strict';
// Marketplace and the Extensions folder can both load this file; only the first copy runs.
if (window.__enhancedPinsActive) {
console.info('[Enhanced Pins] Another copy is already running; skipping this one.');
return;
}
window.__enhancedPinsActive = true;
//#region Type Definitions
/**
* @typedef {Object} PinnedItem
* @property {string} uri - Spotify URI (e.g. "spotify:playlist:37i9...")
* @property {string} type - Entity type from Spicetify.URI.Type
* @property {string} name - Display name (cached at pin-time)
* @property {string|null} imageUrl - Artwork URL (cached at pin-time)
* @property {string} owner - Owner/artist name for subtitle
* @property {number} pinnedAt - Timestamp when pinned
*/
//#endregion
//#region Constants
/** LocalStorage key for pin data */
const EP_PINS_KEY = 'enhanced-pins-data';
/** Container element ID */
const EP_CONTAINER_ID = 'enhanced-pins-container';
/** Style element ID */
const EP_STYLE_ID = 'ep-main-styles';
/** Sidebar nav bar selector */
const SEL_NAV_BAR = '#Desktop_LeftSidebar_Id, .Root__nav-bar';
/** Library root: Spicetify-mapped class first, unmapped fallback for clients without a CSS map */
const LIBRARY_ROOTS = ['.main-yourLibraryX-libraryRootlist', '#Desktop_LeftSidebar_Id .YourLibraryX'];
const SEL_LIBRARY = LIBRARY_ROOTS.join(', ');
/** Scroll content root inside the library (unmapped DOM) */
const SEL_LIBRARY_SCROLL_CONTENT = '[data-overlayscrollbars-viewport] > div';
/** Library sort/view combobox; its aria-label encodes the view mode */
const SEL_VIEW_COMBOBOX = [
'.main-yourLibraryX-libraryRootlist [role="combobox"]',
'.main-yourLibraryX-libraryFilter [role="combobox"]',
'#Desktop_LeftSidebar_Id [role="combobox"][aria-controls="sort-and-view-picker"]',
].join(', ');
/** URI types that can be pinned */
const PINNABLE_TYPES = new Set([
'playlist',
'playlist-v2',
'album',
'show',
'collection'
]);
/** Map URI type to Spotify navigation path */
const TYPE_PATH_MAP = {
'playlist': '/playlist/',
'playlist-v2': '/playlist/',
'album': '/album/',
'show': '/show/',
'collection': '/collection/'
};
/** Map URI type to human-readable label */
const TYPE_LABEL_MAP = {
'playlist': 'Playlist',
'playlist-v2': 'Playlist',
'album': 'Album',
'show': 'Podcast',
'collection': 'Playlist'
};
/**
* Maps sidebar filter chip labels (lowercase) to a predicate deciding whether
* a pin belongs under that chip. Plain Set-of-types isn't enough because
* pseudo-playlists (URI type `collection`) split across chips depending on
* category: Local Files and Liked Songs are Playlists-only, but Your
* Episodes shows under both Playlists and Podcasts in Spotify's own UI.
* Real audiobooks and podcasts both use URI type `show` with no further
* signal on the URI, so the Audiobooks and Podcasts chips are unavoidably
* conflated here — a pre-existing limitation, not introduced by this map.
*/
const FILTER_TYPE_MAP = {
'playlists': pin => pin.type === 'playlist' || pin.type === 'playlist-v2' || pin.type === 'collection',
'albums': pin => pin.type === 'album',
'podcasts': pin => pin.type === 'show' || getPseudoCategory(pin) === 'your-episodes',
'podcasts & shows': pin => pin.type === 'show' || getPseudoCategory(pin) === 'your-episodes',
'audiobooks': pin => pin.type === 'show',
};
/**
* Spotify's auto-generated library entries. URI type `collection`, identified
* by category (e.g. "spotify:collection:local-files") rather than a base62 id,
* so they need their own name/label lookup instead of the normal metadata fetch.
*/
const PSEUDO_COLLECTIONS = {
'tracks': { localeKey: 'sidebar.liked_songs', name: 'Liked Songs', label: 'Playlist', icon: 'heart' },
'your-episodes': { localeKey: 'sidebar.your_episodes', name: 'Your Episodes', label: 'Podcast', icon: 'bookmark' },
'local-files': { localeKey: 'local-files', name: 'Local Files', label: 'Local Files', icon: 'folder' },
};
/** Spotify's native pin icon SVG path */
const PIN_SVG_PATH = 'M8.822.797a2.72 2.72 0 0 1 3.847 0l2.534 2.533a2.72 2.72 0 0 1 0 3.848l-3.678 3.678-1.337 4.988-4.486-4.486L1.28 15.78a.75.75 0 0 1-1.06-1.06l4.422-4.422L.156 5.812l4.987-1.337z';
/** Spotify play icon (24x24 viewBox) */
const PLAY_SVG_PATH = 'm7.05 3.606 13.49 7.788a.7.7 0 0 1 0 1.212L7.05 20.394A.7.7 0 0 1 6 19.788V4.212a.7.7 0 0 1 1.05-.606';
/** Spotify pause icon (24x24 viewBox) */
const PAUSE_SVG_PATH = 'M5.7 3a.7.7 0 0 0-.7.7v16.6a.7.7 0 0 0 .7.7h2.6a.7.7 0 0 0 .7-.7V3.7a.7.7 0 0 0-.7-.7zm10 0a.7.7 0 0 0-.7.7v16.6a.7.7 0 0 0 .7.7h2.6a.7.7 0 0 0 .7-.7V3.7a.7.7 0 0 0-.7-.7z';
/** Spotify speaker/volume icon paths (16x16 viewBox, two paths) */
const SPEAKER_SVG_PATH_1 = 'M10.016 1.125A.75.75 0 0 0 8.99.85l-6.925 4a3.64 3.64 0 0 0 0 6.299l6.925 4a.75.75 0 0 0 1.125-.65v-13a.75.75 0 0 0-.1-.375zM11.5 5.56a2.75 2.75 0 0 1 0 4.88z';
const SPEAKER_SVG_PATH_2 = 'M16 8a5.75 5.75 0 0 1-4.5 5.614v-1.55a4.252 4.252 0 0 0 0-8.127v-1.55A5.75 5.75 0 0 1 16 8';
/** Bootstrap Icons bookmark-fill / folder-fill paths (16x16 viewBox), used as artwork placeholders for pseudo-playlist pins */
const BOOKMARK_SVG_PATH = 'M2 2a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v13.5a.5.5 0 0 1-.777.416L8 13.101l-5.223 2.815A.5.5 0 0 1 2 15.5z';
const FOLDER_SVG_PATH = 'M9.828 3h3.982a2 2 0 0 1 1.992 2.181l-.638 7A2 2 0 0 1 13.174 14H2.825a2 2 0 0 1-1.991-1.819l-.637-7a2 2 0 0 1 .342-1.31L.5 3a2 2 0 0 1 2-2h3.672a2 2 0 0 1 1.414.586l.828.828A2 2 0 0 0 9.828 3M2.19 3h5.396l-.707-.707A1 1 0 0 0 6.172 2H2.5a1 1 0 0 0-1 .981z';
/** Gear/settings icon SVG path (16x16 viewBox, Bootstrap Icons gear-fill) */
const GEAR_SVG_PATH = 'M9.405 1.05c-.413-1.4-2.397-1.4-2.81 0l-.1.34a1.464 1.464 0 0 1-2.105.872l-.31-.17c-1.283-.698-2.686.705-1.987 1.987l.169.311c.446.82.023 1.841-.872 2.105l-.34.1c-1.4.413-1.4 2.397 0 2.81l.34.1a1.464 1.464 0 0 1 .872 2.105l-.17.31c-.698 1.283.705 2.686 1.987 1.987l.311-.169a1.464 1.464 0 0 1 2.105.872l.1.34c.413 1.4 2.397 1.4 2.81 0l.1-.34a1.464 1.464 0 0 1 2.105-.872l.31.17c1.283.698 2.686-.705 1.987-1.987l-.169-.311a1.464 1.464 0 0 1 .872-2.105l.34-.1c1.4-.413 1.4-2.397 0-2.81l-.34-.1a1.464 1.464 0 0 1-.872-2.105l.17-.31c.698-1.283-.705-2.686-1.987-1.987l-.311.169a1.464 1.464 0 0 1-2.105-.872zM8 10.93a2.929 2.929 0 1 1 0-5.858 2.929 2.929 0 0 1 0 5.858z';
/**
* Selectable pin marker icons. Each entry's `body` is trusted inner-SVG markup
* (authored here, never user input) rendered inside a 16x16 viewBox.
* The first entry (`pushpin`) is the historical default and reuses PIN_SVG_PATH.
* Goofy faces (emoji-*) are included; further personalization is via emoji input.
* SVG paths sourced from Bootstrap Icons (MIT), same source as GEAR_SVG_PATH.
* @type {{key: string, label: string, body: string}[]}
*/
const EP_ICON_PRESETS = [
{ key: 'pushpin', label: 'Pushpin', body: `` },
{ key: 'star', label: 'Star', body: '' },
{ key: 'heart', label: 'Heart', body: '' },
{ key: 'lightning', label: 'Lightning', body: '' },
{ key: 'fire', label: 'Fire', body: '' },
{ key: 'gem', label: 'Gem', body: '' },
{ key: 'smile', label: 'Smiley', body: '' },
{ key: 'sunglasses', label: 'Cool', body: '' },
];
/** Default icon used by pins without a per-pin override */
const EP_DEFAULT_ICON = { kind: 'preset', value: 'pushpin' };
/**
* Returns the preset entry for a key, falling back to the pushpin default for
* unknown keys (e.g. presets removed across versions, corrupt storage).
* @param {string} key
* @returns {{key: string, label: string, body: string}}
*/
function getPresetIcon(key) {
return EP_ICON_PRESETS.find(p => p.key === key) || EP_ICON_PRESETS[0];
}
/**
* Maps a PSEUDO_COLLECTIONS `icon` key to inner-SVG markup, for the pin's
* artwork placeholder. Reuses the existing "heart" pin-icon preset rather
* than duplicating its path.
*/
const PSEUDO_COLLECTION_ICON_BODY = {
heart: getPresetIcon('heart').body,
bookmark: ``,
folder: ``,
};
/**
* Normalizes a user-entered emoji string: trims and caps codepoint length so a
* single glyph (incl. ZWJ sequences like the black cat) survives but long text
* cannot be injected as an "icon".
* @param {string} str
* @returns {string}
*/
function normalizeEmoji(str) {
return Array.from((str || '').trim()).slice(0, 8).join('');
}
/** LocalStorage key for EP config */
const EP_CONFIG_KEY = 'enhanced-pins-config';
/** Current export schema version */
const EP_EXPORT_SCHEMA_VERSION = 1;
/** Read by the shared footer. release-please keeps `version` in sync with the VERSION banner. */
const EXT = {
name: 'Enhanced Pins',
slug: 'enhanced-pins',
// x-release-please-start-version
version: '1.3.0',
// x-release-please-end-version
footerPrefix: 'ep-settings',
};
// @shared footer.js start — edit shared/footer.js, then run pnpm sync
/**
* Settings footer shared by every extension: version, Docs, More extensions and a
* report-an-issue link. Reads the file's EXT config; class names are built from
* EXT.footerPrefix (`${footerPrefix}-footer`, `-footer-links`, `-version`, `-github-link`, `-github-icon`).
*/
const SHARED_HUB_URL = 'https://spicetify.yusufaf.dev/';
/** GitHub mark icon path (16x16 viewBox, Bootstrap Icons github, MIT) */
const SHARED_GITHUB_ICON_PATH = 'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z';
/** @param {{ name: string, slug: string, version: string, footerPrefix: string }} ext */
function sharedFooterHtml(ext) {
const p = ext.footerPrefix;
const issueUrl = `https://github.com/yusufaf/spicetify-extensions/issues/new?template=${ext.slug}.yml`;
return `
`;
}
/**
* CSS for sharedFooterHtml, to append to the extension's own stylesheet.
* `sticky` pins the footer to the bottom of Spicetify's PopupModal while the content scrolls.
* @param {{ footerPrefix: string }} ext
* @param {{ sticky?: boolean }} [options]
*/
function sharedFooterCss(ext, { sticky = false } = {}) {
const p = ext.footerPrefix;
const stickyRules = sticky
? `
position: sticky;
bottom: 0;
padding: 10px 0 2px;
/* Matches Spicetify's popup container, so the sticky footer blends in under any theme */
background: var(--spice-player, var(--background-elevated-base, #121212));`
: '';
return `
.${p}-footer {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
border-top: 1px solid rgba(255, 255, 255, 0.1);${stickyRules}
}
.${p}-version {
color: var(--spice-subtext, #b3b3b3);
font-size: 0.75rem;
}
.${p}-footer-links {
display: inline-flex;
align-items: center;
gap: 12px;
flex-shrink: 0;
white-space: nowrap;
}
.${p}-footer a[href] {
display: inline-flex;
align-items: center;
color: var(--spice-subtext, #b3b3b3);
font-size: 0.75rem;
text-decoration: none;
}
.${p}-footer a[href]:hover {
color: var(--spice-text, #fff);
text-decoration: underline;
}
.${p}-footer a[href]:focus-visible {
outline: 2px solid var(--spice-text, #fff);
outline-offset: 2px;
border-radius: 2px;
}
.${p}-github-icon {
width: 16px;
height: 16px;
fill: currentColor;
}
`;
}
// @shared footer.js end
/** Default keyboard shortcut bindings. Format: "Modifier+...+Code" using KeyboardEvent.code for layout independence */
const EP_DEFAULT_SHORTCUTS = {
toggleExpand: 'Alt+KeyE',
openSettings: 'Alt+KeyS',
focusFirstPin: 'Alt+Digit1'
};
/** Human-readable labels for shortcut actions (used in settings UI) */
const EP_SHORTCUT_LABELS = {
toggleExpand: 'Toggle show more / show less',
openSettings: 'Open Enhanced Pins settings',
focusFirstPin: 'Focus first pinned item'
};
/** Default configuration */
const EP_DEFAULT_CONFIG = {
hideFromLibrary: true,
confirmUnpin: false,
sortMode: 'custom',
maxVisiblePins: 0,
shortcutsEnabled: false,
shortcuts: { ...EP_DEFAULT_SHORTCUTS },
defaultIcon: { ...EP_DEFAULT_ICON },
titleVisible: true,
titleText: 'Enhanced Pins',
titleFontSize: 11,
titleColor: '#b3b3b3'
};
/** View mode constants */
const VIEW_LIST = 'list';
const VIEW_COMPACT = 'compact';
const VIEW_GRID = 'grid';
const VIEW_COMPACT_GRID = 'compact-grid';
//#endregion
//#region State
/** @type {PinnedItem[]} Cached pin list */
let currentPins = [];
/** @type {HTMLStyleElement|null} Dynamic style element for hiding duplicates */
let hideStyleElement = null;
/** @type {string} Cached sidebar view mode */
let cachedViewMode = VIEW_LIST;
/** @type {boolean} Whether the user has expanded a truncated pin list */
let expandedView = false;
//#endregion
//#region Storage
/**
* Loads pins from LocalStorage
* @returns {PinnedItem[]}
*/
function loadPins() {
try {
const stored = Spicetify.LocalStorage.get(EP_PINS_KEY);
return stored ? JSON.parse(stored) : [];
} catch {
return [];
}
}
/**
* Saves pins to LocalStorage and updates cache
* @param {PinnedItem[]} pins
*/
function savePins(pins) {
Spicetify.LocalStorage.set(EP_PINS_KEY, JSON.stringify(pins));
currentPins = pins;
}
/**
* Loads extension config from LocalStorage
* @returns {Object}
*/
function loadConfig() {
try {
const stored = Spicetify.LocalStorage.get(EP_CONFIG_KEY);
if (stored) return { ...EP_DEFAULT_CONFIG, ...JSON.parse(stored) };
return { ...EP_DEFAULT_CONFIG };
} catch {
return { ...EP_DEFAULT_CONFIG };
}
}
/**
* Saves extension config to LocalStorage
* @param {Object} config
*/
function saveConfig(config) {
Spicetify.LocalStorage.set(EP_CONFIG_KEY, JSON.stringify(config));
}
/**
* Returns a sorted copy of pins based on the given sort mode.
* Does not mutate the original array (preserves storage order for 'custom' drag-and-drop).
* @param {PinnedItem[]} pins
* @param {string} mode - 'custom' | 'alphabetical' | 'type' | 'recent'
* @returns {PinnedItem[]}
*/
function sortPins(pins, mode) {
if (mode === 'custom' || !mode) return pins;
const sorted = [...pins];
switch (mode) {
case 'alphabetical':
sorted.sort((a, b) => a.name.localeCompare(b.name));
break;
case 'type': {
const typeOrder = { playlist: 0, 'playlist-v2': 0, album: 1, show: 2, collection: 3 };
sorted.sort((a, b) => {
const diff = (typeOrder[a.type] ?? 99) - (typeOrder[b.type] ?? 99);
return diff !== 0 ? diff : a.name.localeCompare(b.name);
});
break;
}
case 'recent':
sorted.sort((a, b) => (b.pinnedAt || 0) - (a.pinnedAt || 0));
break;
}
return sorted;
}
/**
* Builds a JSON-serializable snapshot of pins + config.
* @returns {Object}
*/
function exportConfig() {
return {
schemaVersion: EP_EXPORT_SCHEMA_VERSION,
exportedAt: new Date().toISOString(),
pins: loadPins(),
config: loadConfig(),
extensions: {}
};
}
/**
* Validates an imported payload. Returns { ok, error, data } where data is the
* normalized payload (pins + merged config) on success.
* @param {unknown} raw
* @returns {{ok: true, data: {pins: PinnedItem[], config: Object}} | {ok: false, error: string}}
*/
function validateImport(raw) {
if (!raw || typeof raw !== 'object') return { ok: false, error: 'Not a JSON object' };
if (raw.schemaVersion !== EP_EXPORT_SCHEMA_VERSION) {
return { ok: false, error: `Unsupported schema version: ${raw.schemaVersion}` };
}
if (!Array.isArray(raw.pins)) return { ok: false, error: 'Missing pins array' };
for (const p of raw.pins) {
if (!p || typeof p.uri !== 'string' || typeof p.type !== 'string' || typeof p.name !== 'string') {
return { ok: false, error: 'Invalid pin entry' };
}
}
if (raw.config && typeof raw.config !== 'object') return { ok: false, error: 'Invalid config' };
const mergedConfig = { ...EP_DEFAULT_CONFIG, ...(raw.config || {}) };
if (raw.config?.shortcuts && typeof raw.config.shortcuts === 'object') {
mergedConfig.shortcuts = { ...EP_DEFAULT_SHORTCUTS, ...raw.config.shortcuts };
}
return { ok: true, data: { pins: raw.pins, config: mergedConfig } };
}
/**
* Applies a validated import payload to storage, replacing current pins/config.
* @param {{pins: PinnedItem[], config: Object}} data
*/
function importConfig(data) {
savePins(data.pins);
saveConfig(data.config);
}
//#endregion
//#region Metadata
/**
* Fetches metadata for a Spotify URI using multiple fallback strategies
* @param {string} uri - Spotify URI
* @returns {Promise<{name: string, imageUrl: string|null, owner: string}>}
*/
async function fetchItemMetadata(uri) {
const uriObj = Spicetify.URI.fromString(uri);
const id = uriObj.id || uriObj._base62Id;
const type = uriObj.type;
const fallback = { name: 'Unknown', imageUrl: null, owner: '' };
// Playlists
if (type === 'playlist' || type === 'playlist-v2') {
try {
if (Spicetify.Platform?.PlaylistAPI?.getMetadata) {
const meta = await Spicetify.Platform.PlaylistAPI.getMetadata(uri);
if (meta?.name) return {
name: meta.name,
imageUrl: meta.images?.[0]?.url || null,
owner: meta.owner?.name || ''
};
}
} catch (e) {
console.warn('[Enhanced Pins] PlaylistAPI fallback', e);
}
try {
const res = await Spicetify.CosmosAsync.get(`sp://core-playlist/v1/playlist/${uri}`);
if (res?.playlist?.name) return {
name: res.playlist.name,
imageUrl: res.playlist.image?.[0]?.url || null,
owner: res.playlist.ownerName || ''
};
} catch (e) {
console.warn('[Enhanced Pins] CosmosAsync playlist fallback', e);
}
}
// Albums
if (type === 'album') {
try {
const res = await Spicetify.CosmosAsync.get(`wg://album/v1/album-app/album/${id}/desktop`);
if (res?.name) return {
name: res.name,
imageUrl: res.cover?.uri || null,
owner: res.artists?.[0]?.name || ''
};
} catch (e) {
console.warn('[Enhanced Pins] CosmosAsync album fallback', e);
}
try {
if (Spicetify.GraphQL?.Request && Spicetify.GraphQL?.Definitions?.getAlbum) {
const res = await Spicetify.GraphQL.Request(
Spicetify.GraphQL.Definitions.getAlbum,
{ uri, locale: Spicetify.Locale?.getLocale?.() || 'en', limit: 1, offset: 0 }
);
if (res?.data?.albumUnion?.name) return {
name: res.data.albumUnion.name,
imageUrl: res.data.albumUnion.coverArt?.sources?.[0]?.url || null,
owner: res.data.albumUnion.artists?.items?.[0]?.profile?.name || ''
};
}
} catch (e) {
console.warn('[Enhanced Pins] GraphQL album fallback', e);
}
}
// Shows (Podcasts)
if (type === 'show') {
try {
const res = await Spicetify.CosmosAsync.get(`sp://core-show/v1/shows/${id}?responseFormat=protobufJson`);
const name = res?.header?.showName || res?.name;
if (name) return {
name,
imageUrl: res.header?.coverImage?.url || null,
owner: res.header?.publisherName || ''
};
} catch (e) {
console.warn('[Enhanced Pins] CosmosAsync show fallback', e);
}
}
// Auto-generated library entries (Liked Songs, Your Episodes, Local Files) -
// identified by category rather than a base62 id, so no API lookup applies.
if (type === 'collection') {
const entry = PSEUDO_COLLECTIONS[uriObj.category];
if (entry) {
const localized = Spicetify.Locale?.get?.(entry.localeKey);
const name = (localized && localized !== entry.localeKey) ? localized : entry.name;
return { name, imageUrl: null, owner: '' };
}
}
return fallback;
}
/**
* Refreshes metadata for any pins missing imageUrl or owner (e.g. pinned before these fields existed)
*/
async function refreshStaleMetadata() {
const pins = loadPins();
let updated = false;
for (const pin of pins) {
if (!pin.imageUrl || !pin.owner || pin.name === 'Unknown') {
try {
const metadata = await fetchItemMetadata(pin.uri);
if (metadata.name !== 'Unknown') pin.name = metadata.name;
if (metadata.imageUrl) pin.imageUrl = metadata.imageUrl;
if (metadata.owner) pin.owner = metadata.owner;
updated = true;
} catch (e) {
console.warn(`[Enhanced Pins] Failed to refresh metadata for ${pin.uri}`, e);
}
}
}
if (updated) {
savePins(pins);
renderPins();
}
}
//#endregion
//#region Context Menu
/**
* Checks if a URI is a pinnable entity type
* @param {string} uriString
* @returns {boolean}
*/
function isPinnable(uriString) {
try {
const uriObj = Spicetify.URI.fromString(uriString);
return PINNABLE_TYPES.has(uriObj.type);
} catch {
return false;
}
}
/**
* Checks if a URI is already enhanced-pinned
* @param {string} uri
* @returns {boolean}
*/
function isAlreadyPinned(uri) {
return currentPins.some(p => p.uri === uri);
}
/**
* Unpins an item, optionally showing a confirmation dialog based on config.
* Shared by both native and custom context menu unpin actions.
* @param {string} uri
*/
function performUnpin(uri) {
const pins = loadPins();
const item = pins.find(p => p.uri === uri);
if (!item) return;
const doUnpin = () => {
let current = loadPins();
current = current.filter(p => p.uri !== uri);
savePins(current);
renderPins();
Spicetify.showNotification(`Unpinned: ${item.name || 'item'}`);
};
const config = loadConfig();
if (config.confirmUnpin) {
const content = document.createElement('div');
content.innerHTML = `
Are you sure you want to unpin ${escapeHtml(item.name)}?
`;
content.querySelector('.ep-delete-cancel').addEventListener('click', () => Spicetify.PopupModal.hide());
content.querySelector('.ep-edit-save').addEventListener('click', () => {
doUnpin();
Spicetify.PopupModal.hide();
});
Spicetify.PopupModal.display({ title: 'Confirm unpin', content, isLarge: false });
} else {
doUnpin();
}
}
/**
* Registers context menu items for pin/unpin
*/
function registerContextMenuItems() {
const pinItem = new Spicetify.ContextMenu.Item(
'Enhanced Pin',
async (uris) => {
const uri = uris[0];
const pins = loadPins();
if (pins.some(p => p.uri === uri)) {
Spicetify.showNotification('Already pinned', true);
return;
}
const uriObj = Spicetify.URI.fromString(uri);
const metadata = await fetchItemMetadata(uri);
pins.push({
uri,
type: uriObj.type,
name: metadata.name,
imageUrl: metadata.imageUrl,
owner: metadata.owner,
pinnedAt: Date.now()
});
savePins(pins);
renderPins();
Spicetify.showNotification(`Pinned: ${metadata.name}`);
},
(uris) => {
if (uris.length !== 1) return false;
if (!isPinnable(uris[0])) return false;
return !isAlreadyPinned(uris[0]);
},
'plus2px'
);
const unpinItem = new Spicetify.ContextMenu.Item(
'Enhanced Unpin',
(uris) => { performUnpin(uris[0]); },
(uris) => {
if (uris.length !== 1) return false;
if (!isPinnable(uris[0])) return false;
return isAlreadyPinned(uris[0]);
},
'minus'
);
pinItem.register();
unpinItem.register();
}
//#endregion
//#region Settings
/**
* Registers an "Enhanced Pins" entry in the Spotify profile menu so settings
* remain reachable even when the library sidebar (and its gear icon) is hidden.
*/
function registerMenuItem() {
if (!Spicetify?.Menu?.Item) return;
const item = new Spicetify.Menu.Item('Enhanced Pins', false, showSettingsModal);
item.register();
}
/**
* Shows the Enhanced Pins settings modal
*/
function showSettingsModal() {
const config = loadConfig();
const content = document.createElement('div');
content.className = 'ep-settings-modal';
content.innerHTML = `
Sorting
Pin Icon
Default marker shown next to each pin. Override per-pin from a pin's right-click menu.
Keyboard Shortcuts
${Object.keys(EP_DEFAULT_SHORTCUTS).map(action => `
${EP_SHORTCUT_LABELS[action]}
`).join('')}
${sharedFooterHtml(EXT)}
`;
const checkboxes = content.querySelectorAll('input[type="checkbox"]');
checkboxes.forEach(checkbox => {
checkbox.addEventListener('change', (e) => {
const newConfig = loadConfig();
newConfig[e.target.name] = e.target.checked;
saveConfig(newConfig);
if (e.target.name === 'hideFromLibrary') {
updateHideStyles();
}
if (e.target.name === 'shortcutsEnabled') {
const panel = content.querySelector('.ep-shortcut-bindings');
if (panel) panel.style.display = e.target.checked ? 'flex' : 'none';
}
if (e.target.name === 'titleVisible') {
renderPins();
}
});
});
content.querySelectorAll('input[type="text"][name]').forEach(input => {
input.addEventListener('change', (e) => {
const newConfig = loadConfig();
newConfig[e.target.name] = e.target.value.slice(0, 60);
saveConfig(newConfig);
renderPins();
});
});
content.querySelectorAll('input[type="color"]').forEach(input => {
input.addEventListener('input', () => {
document.documentElement.style.setProperty('--ep-title-color', input.value);
});
input.addEventListener('change', (e) => {
const newConfig = loadConfig();
newConfig[e.target.name] = e.target.value;
saveConfig(newConfig);
applyTitleVars(newConfig);
});
});
content.querySelector('[data-action="reset-title"]')?.addEventListener('click', () => {
const newConfig = loadConfig();
newConfig.titleVisible = EP_DEFAULT_CONFIG.titleVisible;
newConfig.titleText = EP_DEFAULT_CONFIG.titleText;
newConfig.titleFontSize = EP_DEFAULT_CONFIG.titleFontSize;
newConfig.titleColor = EP_DEFAULT_CONFIG.titleColor;
saveConfig(newConfig);
content.querySelector('input[name="titleVisible"]').checked = newConfig.titleVisible;
content.querySelector('input[name="titleText"]').value = newConfig.titleText;
content.querySelector('input[name="titleFontSize"]').value = newConfig.titleFontSize;
content.querySelector('input[name="titleColor"]').value = newConfig.titleColor;
applyTitleVars(newConfig);
renderPins();
});
content.querySelectorAll('.ep-shortcut-record').forEach(btn => {
btn.addEventListener('click', () => {
const originalText = btn.textContent;
btn.textContent = 'Press keys…';
btn.disabled = true;
const onKey = (ev) => {
ev.preventDefault();
ev.stopPropagation();
if (ev.key === 'Escape') {
btn.textContent = originalText;
btn.disabled = false;
window.removeEventListener('keydown', onKey, true);
return;
}
if (['Control', 'Alt', 'Shift', 'Meta'].includes(ev.key)) return;
if (!ev.ctrlKey && !ev.altKey && !ev.metaKey && !ev.shiftKey) return;
const parts = [];
if (ev.ctrlKey) parts.push('Ctrl');
if (ev.altKey) parts.push('Alt');
if (ev.shiftKey) parts.push('Shift');
if (ev.metaKey) parts.push('Meta');
parts.push(ev.code);
const binding = parts.join('+');
const newConfig = loadConfig();
newConfig.shortcuts = { ...newConfig.shortcuts, [btn.dataset.actionKey]: binding };
saveConfig(newConfig);
btn.textContent = binding;
btn.disabled = false;
window.removeEventListener('keydown', onKey, true);
};
window.addEventListener('keydown', onKey, true);
});
});
content.querySelectorAll('.ep-shortcut-clear').forEach(btn => {
btn.addEventListener('click', () => {
const newConfig = loadConfig();
newConfig.shortcuts = { ...newConfig.shortcuts, [btn.dataset.actionKey]: '' };
saveConfig(newConfig);
const recordBtn = content.querySelector(`.ep-shortcut-record[data-action-key="${btn.dataset.actionKey}"]`);
if (recordBtn) recordBtn.textContent = '(none)';
});
});
const exportBtn = content.querySelector('[data-action="export"]');
if (exportBtn) {
exportBtn.addEventListener('click', () => {
const payload = exportConfig();
const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
a.download = `enhanced-pins-${stamp}.json`;
document.body.appendChild(a);
a.click();
a.remove();
URL.revokeObjectURL(url);
Spicetify.showNotification('Exported enhanced pins configuration');
});
}
const importBtn = content.querySelector('[data-action="import"]');
const importFile = content.querySelector('.ep-import-file');
if (importBtn && importFile) {
importBtn.addEventListener('click', () => importFile.click());
importFile.addEventListener('change', async (e) => {
const file = e.target.files?.[0];
if (!file) return;
try {
const text = await file.text();
const raw = JSON.parse(text);
const result = validateImport(raw);
if (!result.ok) {
Spicetify.showNotification(`Import failed: ${result.error}`, true);
return;
}
if (!window.confirm(`Import ${result.data.pins.length} pins? This replaces your current pins and settings.`)) {
importFile.value = '';
return;
}
importConfig(result.data);
Spicetify.showNotification('Import complete. Reloading…');
setTimeout(() => location.reload(), 500);
} catch (err) {
Spicetify.showNotification(`Import failed: ${err.message}`, true);
} finally {
importFile.value = '';
}
});
}
content.querySelectorAll('select').forEach(select => {
select.addEventListener('change', (e) => {
const newConfig = loadConfig();
newConfig[e.target.name] = e.target.value;
saveConfig(newConfig);
renderPins();
});
});
content.querySelectorAll('input[type="number"]').forEach(input => {
input.addEventListener('change', (e) => {
const newConfig = loadConfig();
newConfig[e.target.name] = Math.max(0, parseInt(e.target.value) || 0);
saveConfig(newConfig);
if (e.target.name === 'titleFontSize') {
applyTitleVars(newConfig);
} else {
expandedView = false;
renderPins();
}
});
});
const iconMount = content.querySelector('.ep-default-icon-mount');
if (iconMount) {
const defaultPicker = buildIconPicker(config.defaultIcon || EP_DEFAULT_ICON, {
allowDefault: false,
onChange: (icon) => {
const newConfig = loadConfig();
newConfig.defaultIcon = icon || { ...EP_DEFAULT_ICON };
saveConfig(newConfig);
renderPins();
}
});
iconMount.appendChild(defaultPicker.el);
}
Spicetify.PopupModal.display({
title: 'Enhanced Pins Settings',
content: content,
isLarge: true
});
}
//#endregion
//#region Sidebar DOM
/**
* Escapes HTML entities to prevent XSS
* @param {string} str
* @returns {string}
*/
function escapeHtml(str) {
const div = document.createElement('div');
div.textContent = str;
return div.innerHTML;
}
/**
* Human-readable type label for a pin's subtitle/radio menu, e.g. "Playlist".
* Pseudo-playlists (Liked Songs, Your Episodes, Local Files) override the
* generic "collection" label with their own.
* @param {PinnedItem} pin
* @returns {string}
*/
function getTypeLabel(pin, pseudoEntry) {
if (pin.type === 'collection') {
const entry = pseudoEntry !== undefined ? pseudoEntry : getPseudoCollectionEntry(pin);
if (entry) return entry.label;
}
return TYPE_LABEL_MAP[pin.type] || 'Playlist';
}
/**
* Returns a collection-type pin's URI category (e.g. "local-files"), or null
* for non-pseudo-playlist pins.
* @param {PinnedItem} pin
* @returns {string|null}
*/
function getPseudoCategory(pin) {
if (pin.type !== 'collection') return null;
try {
return Spicetify.URI.fromString(pin.uri).category || null;
} catch {
return null;
}
}
/**
* Looks up a pin's PSEUDO_COLLECTIONS entry, if it is one.
* @param {PinnedItem} pin
* @returns {{localeKey: string, name: string, label: string, icon: string}|null}
*/
function getPseudoCollectionEntry(pin) {
const category = getPseudoCategory(pin);
return category ? (PSEUDO_COLLECTIONS[category] || null) : null;
}
/**
* Renders the artwork placeholder for a pin. Pseudo-playlists (no image URL)
* get a distinguishing glyph instead of a blank tile.
* @param {PinnedItem} pin
* @param {{icon: string}|null} [pseudoEntry] - precomputed getPseudoCollectionEntry(pin), to avoid re-parsing the URI
* @returns {string}
*/
function renderArtPlaceholderHTML(pin, pseudoEntry) {
const entry = pseudoEntry !== undefined ? pseudoEntry : getPseudoCollectionEntry(pin);
const body = entry && PSEUDO_COLLECTION_ICON_BODY[entry.icon];
if (body) {
return `
`;
}
return '';
}
/**
* Writes title font-size/color as CSS custom properties so live edits (e.g. dragging
* the color picker) repaint instantly without rebuilding the pins list.
* @param {Object} config
*/
function applyTitleVars(config) {
const root = document.documentElement;
root.style.setProperty('--ep-title-color', config.titleColor || EP_DEFAULT_CONFIG.titleColor);
root.style.setProperty('--ep-title-font-size', `${config.titleFontSize || EP_DEFAULT_CONFIG.titleFontSize}px`);
}
/**
* Resolves the effective icon descriptor for a pin: its own override, else the
* global default, else the built-in pushpin.
* @param {PinnedItem} pin
* @param {Object} config
* @returns {{kind: string, value: string}}
*/
function resolvePinIcon(pin, config) {
const icon = pin?.icon || config?.defaultIcon || EP_DEFAULT_ICON;
if (icon && (icon.kind === 'preset' || icon.kind === 'emoji') && icon.value) return icon;
return EP_DEFAULT_ICON;
}
/**
* Renders an icon descriptor as the subtitle marker HTML. Presets use trusted
* inline SVG; emoji values are escaped.
* @param {{kind: string, value: string}} icon
* @returns {string}
*/
function renderPinIconHTML(icon) {
if (icon.kind === 'emoji') {
return `${escapeHtml(icon.value)}`;
}
const preset = getPresetIcon(icon.value);
return ``;
}
/**
* Builds a reusable icon picker UI: a grid of preset buttons, an optional
* "Default" tile, and an emoji input. Selection state lives in the returned
* `getValue`/`setValue` accessors so callers decide when to commit.
* @param {{kind: string, value: string}|null} current - current icon, or null for "default"
* @param {{allowDefault?: boolean, onChange?: (icon: {kind:string,value:string}|null) => void}} [opts]
* @returns {{el: HTMLElement, getValue: () => ({kind:string,value:string}|null)}}
*/
function buildIconPicker(current, opts = {}) {
const { allowDefault = false, onChange } = opts;
let selected = current ? { ...current } : null;
const el = document.createElement('div');
el.className = 'ep-icon-picker';
const grid = document.createElement('div');
grid.className = 'ep-icon-grid';
/** @type {HTMLButtonElement[]} */
const tiles = [];
const refreshSelected = () => {
tiles.forEach(t => {
const isSel =
(t.dataset.kind === 'default' && selected === null) ||
(t.dataset.kind === 'preset' && selected?.kind === 'preset' && selected.value === t.dataset.value) ||
(t.dataset.kind === 'emoji' && selected?.kind === 'emoji');
t.classList.toggle('ep-icon-selected', isSel);
});
};
const choose = (value) => {
selected = value;
refreshSelected();
onChange?.(selected);
};
if (allowDefault) {
const def = document.createElement('button');
def.type = 'button';
def.className = 'ep-icon-option';
def.dataset.kind = 'default';
def.title = 'Use global default';
def.innerHTML = 'Default';
def.addEventListener('click', () => choose(null));
grid.appendChild(def);
tiles.push(def);
}
EP_ICON_PRESETS.forEach(preset => {
const btn = document.createElement('button');
btn.type = 'button';
btn.className = 'ep-icon-option';
btn.dataset.kind = 'preset';
btn.dataset.value = preset.key;
btn.title = preset.label;
btn.innerHTML = ``;
btn.addEventListener('click', () => choose({ kind: 'preset', value: preset.key }));
grid.appendChild(btn);
tiles.push(btn);
});
el.appendChild(grid);
const emojiRow = document.createElement('div');
emojiRow.className = 'ep-icon-emoji-row';
emojiRow.innerHTML = `
Or use an emoji
`;
const emojiInput = emojiRow.querySelector('.ep-icon-emoji-input');
if (selected?.kind === 'emoji') emojiInput.value = selected.value;
const emojiTile = document.createElement('button');
emojiTile.type = 'button';
emojiTile.dataset.kind = 'emoji';
emojiTile.style.display = 'none';
tiles.push(emojiTile); // tracked only for selected-state highlighting
emojiInput.addEventListener('input', () => {
const val = normalizeEmoji(emojiInput.value);
if (val) choose({ kind: 'emoji', value: val });
});
el.appendChild(emojiRow);
refreshSelected();
return { el, getValue: () => selected };
}
/**
* Opens a modal to set a per-pin icon override. Saving with "Default" selected
* removes the override so the pin follows the global default.
* @param {PinnedItem} pin
*/
function showIconPickerModal(pin) {
const picker = buildIconPicker(pin.icon || null, { allowDefault: true });
const content = document.createElement('div');
content.className = 'ep-icon-modal';
content.appendChild(picker.el);
const actions = document.createElement('div');
actions.className = 'ep-icon-actions';
actions.innerHTML = `
`;
actions.querySelector('.ep-delete-cancel').addEventListener('click', () => Spicetify.PopupModal.hide());
actions.querySelector('.ep-edit-save').addEventListener('click', () => {
const value = picker.getValue();
const pins = loadPins();
const target = pins.find(p => p.uri === pin.uri);
if (target) {
if (value) target.icon = value;
else delete target.icon;
savePins(pins);
renderPins();
}
Spicetify.PopupModal.hide();
});
content.appendChild(actions);
Spicetify.PopupModal.display({ title: `Icon for ${pin.name}`, content, isLarge: false });
}
/**
* Resolves the in-app route for a URI. Prefers Spicetify's own URI-to-path
* resolver (handles id-less URIs like "spotify:collection:local-files"),
* falling back to the id-based path map for older Spicetify versions.
* @param {string} uri
* @returns {string}
*/
function pinPath(uri) {
const uriObj = Spicetify.URI.fromString(uri);
const path = uriObj.toURLPath?.(true);
if (path) return path;
const id = uriObj.id || uriObj._base62Id;
return (TYPE_PATH_MAP[uriObj.type] || '/playlist/') + id;
}
/**
* Navigates to a pinned item's page
* @param {PinnedItem} pin
*/
function navigateToPin(pin) {
Spicetify.Platform.History.push(pinPath(pin.uri));
}
/**
* Starts playback of a pinned item (used on double-click)
* @param {PinnedItem} pin
*/
function playPin(pin) {
try {
if (Spicetify.Platform?.PlayerAPI?.play) {
Spicetify.Platform.PlayerAPI.play({ uri: pin.uri }, {});
} else if (Spicetify.Player?.playUri) {
Spicetify.Player.playUri(pin.uri);
} else {
navigateToPin(pin);
}
} catch (e) {
console.warn('[Enhanced Pins] Playback fallback to navigation', e);
navigateToPin(pin);
}
}
/**
* Checks if a URI is the current playback context
* @param {string} uri
* @returns {boolean}
*/
function isCurrentlyPlaying(uri) {
return Spicetify.Player?.data?.context?.uri === uri;
}
/**
* @returns {boolean} True if player is paused
*/
function isPlayerPaused() {
return Spicetify.Player?.data?.isPaused ?? true;
}
/**
* Toggles play/pause for a pin. If it's the current context, toggle pause.
* Otherwise start playing this context.
* @param {PinnedItem} pin
*/
function togglePlayback(pin) {
if (isCurrentlyPlaying(pin.uri)) {
if (isPlayerPaused()) {
Spicetify.Player.play();
} else {
Spicetify.Player.pause();
}
} else {
playPin(pin);
}
}
/**
* Updates playing state classes and icons on all enhanced pin items
*/
function updatePlayingStates() {
const items = document.querySelectorAll('.ep-item');
items.forEach(item => {
const uri = item.getAttribute('data-uri');
const playing = isCurrentlyPlaying(uri);
const paused = isPlayerPaused();
item.classList.toggle('ep-playing', playing && !paused);
item.classList.toggle('ep-paused', playing && paused);
const overlayPath = item.querySelector('.ep-art-overlay path');
if (overlayPath) {
if (playing && !paused) {
overlayPath.setAttribute('d', PAUSE_SVG_PATH);
} else {
overlayPath.setAttribute('d', PLAY_SVG_PATH);
}
}
const title = item.querySelector('.ep-item-title');
if (title) {
title.classList.toggle('ep-title-active', playing);
}
});
}
/**
* Finds where to inject the enhanced pins section in the sidebar.
* Targets inside the library rootlist, between the filter area and the virtualized grid.
* @returns {{ parent: HTMLElement, reference: Node|null }|null}
*/
function findInjectionPoint() {
const rootlist = getLibraryRoot();
if (!rootlist) return null;
// Strategy 1: After the filter bar inside libraryRootlist
const filter = rootlist.querySelector('.main-yourLibraryX-libraryFilter');
if (filter && filter.parentElement) {
return { parent: filter.parentElement, reference: filter.nextElementSibling };
}
// Strategy 2: Before the wrapper holding the treegrid/grid. Stop at the scroll
// content root so pins scroll with the library instead of becoming a flex
// sibling of the scroll host (which squashes the native list).
const gridEl = rootlist.querySelector('[role="treegrid"], [role="grid"]');
if (gridEl) {
let wrapper = gridEl;
while (
wrapper.parentElement &&
wrapper.parentElement !== rootlist &&
!wrapper.parentElement.matches(SEL_LIBRARY_SCROLL_CONTENT)
) {
wrapper = wrapper.parentElement;
}
return { parent: wrapper.parentElement, reference: wrapper };
}
// Strategy 3: No grid rendered; append to the scroll content so pins still show
const scrollContent = rootlist.querySelector(SEL_LIBRARY_SCROLL_CONTENT);
if (scrollContent) {
return { parent: scrollContent, reference: null };
}
// No safe spot (e.g. library not mounted yet): skip injection rather than
// appending to the sidebar root; the sidebar observer retries on the next mutation.
return null;
}
/**
* Returns the library root element, honoring LIBRARY_ROOTS priority order
* (a comma-joined querySelector would return whichever comes first in the DOM).
* @returns {HTMLElement|null}
*/
function getLibraryRoot() {
for (const sel of LIBRARY_ROOTS) {
const el = document.querySelector(sel);
if (el) return el;
}
return null;
}
/**
* Detects the current sidebar library view mode.
* Primary: reads the combobox aria-label (e.g. "Custom order, Default grid view").
* Fallback: compares positions of native library items.
* @returns {string} VIEW_LIST, VIEW_COMPACT, VIEW_GRID, or VIEW_COMPACT_GRID
*/
function detectViewMode() {
// Strategy 1: Parse the view mode from the sort/view combobox aria-label
const combobox = document.querySelector(SEL_VIEW_COMBOBOX);
if (combobox) {
const label = (combobox.getAttribute('aria-label') || '').toLowerCase();
if (label.includes('compact') && label.includes('grid')) {
cachedViewMode = VIEW_COMPACT_GRID;
return cachedViewMode;
}
if (label.includes('grid')) {
cachedViewMode = VIEW_GRID;
return cachedViewMode;
}
if (label.includes('compact')) {
cachedViewMode = VIEW_COMPACT;
return cachedViewMode;
}
if (label.includes('list')) {
cachedViewMode = VIEW_LIST;
return cachedViewMode;
}
}
// Strategy 2: Position-based fallback using native library items
const rootlist = getLibraryRoot();
if (!rootlist) return cachedViewMode;
// Skip virtualization spacer rows (no title element) and our own items
const allItems = rootlist.querySelectorAll('[role="row"]');
const items = [...allItems].filter(el =>
el.children.length &&
el.querySelector('[id^="listrow-title-"]') &&
!el.closest('#' + EP_CONTAINER_ID)
);
if (items.length < 2) return cachedViewMode;
const r0 = items[0].getBoundingClientRect();
const r1 = items[1].getBoundingClientRect();
if (r0.height === 0 || r1.height === 0) return cachedViewMode;
// Grid: items on the same row
if (Math.abs(r0.top - r1.top) < 10) {
let cols = 1;
for (let i = 1; i < Math.min(items.length, 6); i++) {
if (Math.abs(items[i].getBoundingClientRect().top - r0.top) < 10) cols++;
else break;
}
cachedViewMode = cols >= 3 ? VIEW_COMPACT_GRID : VIEW_GRID;
return cachedViewMode;
}
// Compact list: native items have no artwork images
if (!items[0].querySelector('img')) {
cachedViewMode = VIEW_COMPACT;
return cachedViewMode;
}
cachedViewMode = VIEW_LIST;
return cachedViewMode;
}
/**
* Detects the active entity type filter from sidebar filter chips.
* When the user selects a filter like "Audiobooks" or "Playlists", only
* enhanced pins matching that chip should be shown.
* @returns {{key: string, matches: (pin: PinnedItem) => boolean}|null} the active chip's
* label (as a stable cache key) and its match predicate, or null if no type filter active
*/
function getActiveTypeFilter() {
// Filter chips are Encore LegacyChip components inside the sidebar nav bar,
// within a listbox[aria-label="Filter options"].
// When a type filter is active, Spotify re-renders the chip bar:
// - All non-matching type chips are removed
// - Only the active type chip + sub-filter chips (e.g. "Unplayed") remain
// - An X/clear button appears
// Detection: if exactly 1 type-matching chip is present (normally 4+), it's the active filter.
const navBar = document.querySelector(SEL_NAV_BAR);
if (!navBar) return null;
const chips = navBar.querySelectorAll('[data-encore-id="chip"]');
if (chips.length === 0) return null;
// Strategy 1: Check for explicitly active chips via aria-checked
for (const chip of chips) {
if (chip.getAttribute('aria-checked') === 'true') {
const label = (chip.getAttribute('aria-label') || '').toLowerCase();
if (FILTER_TYPE_MAP[label]) return { key: label, matches: FILTER_TYPE_MAP[label] };
}
}
// Strategy 2: Count type-matching chips. When unfiltered, multiple type chips
// are visible (Playlists, Podcasts, Audiobooks, Albums, etc.). When a type
// filter is active, only that single type chip remains.
const typeChips = [];
for (const chip of chips) {
const label = (chip.getAttribute('aria-label') || '').toLowerCase();
if (FILTER_TYPE_MAP[label]) typeChips.push(label);
}
if (typeChips.length === 1) {
return { key: typeChips[0], matches: FILTER_TYPE_MAP[typeChips[0]] };
}
return null;
}
/** @type {string|null} URI of the pin targeted by the context menu */
let ctxMenuTargetUri = null;
/**
* Converts a Spotify URI to an open.spotify.com URL
* @param {string} uri
* @returns {string}
*/
function uriToUrl(uri) {
try {
const uriObj = Spicetify.URI.fromString(uri);
const url = uriObj.toURL?.();
if (url) return url;
const type = uriObj.type === 'playlist-v2' ? 'playlist' : uriObj.type;
const id = uriObj.id || uriObj._base62Id;
return `https://open.spotify.com/${type}/${id}`;
} catch {
return uri;
}
}
/**
* Creates the reusable custom context menu element on document.body
*/
function createContextMenu() {
if (document.getElementById('ep-context-menu')) return;
const menu = document.createElement('div');
menu.id = 'ep-context-menu';
menu.className = 'ep-context-menu';
menu.style.display = 'none';
menu.setAttribute('role', 'menu');
menu.innerHTML = `
`;
document.body.appendChild(menu);
}
/**
* Shows the custom context menu at cursor position for a given pin.
* Async to check playlist ownership and visibility state for dynamic items.
* @param {MouseEvent} e
* @param {PinnedItem} pin
*/
async function showContextMenu(e, pin) {
const menu = document.getElementById('ep-context-menu');
if (!menu) return;
ctxMenuTargetUri = pin.uri;
// Update Play/Pause label
const playLabel = menu.querySelector('[data-action="play"] .ep-ctx-label');
if (playLabel) {
playLabel.textContent = (isCurrentlyPlaying(pin.uri) && !isPlayerPaused()) ? 'Pause' : 'Play';
}
// Update radio label based on type
const radioLabel = menu.querySelector('[data-action="radio"] .ep-ctx-label');
if (radioLabel) {
radioLabel.textContent = `Go to ${getTypeLabel(pin)} Radio`;
}
// Show "Move to top/bottom" only in custom sort mode
const ctxConfig = loadConfig();
const isCustomSort = ctxConfig.sortMode === 'custom';
menu.querySelectorAll('[data-action="pin-to-top"], [data-action="pin-to-bottom"]').forEach(btn => {
const li = btn.closest('li');
if (li) li.style.display = isCustomSort ? '' : 'none';
});
// Hide owner-only items by default (shown after async ownership check)
menu.querySelectorAll('.ep-ctx-owner').forEach(el => { el.style.display = 'none'; });
// Pseudo-playlists (Liked Songs, Your Episodes, Local Files) have no radio
// station, no offline download, and can't be native-pinned or (for Local
// Files specifically) linked to a public page.
const isPseudoCollection = pin.type === 'collection';
menu.querySelectorAll('.ep-ctx-real-entity').forEach(el => { el.style.display = isPseudoCollection ? 'none' : ''; });
const copyLinkLi = menu.querySelector('[data-action="copy-link"]')?.closest('li');
if (copyLinkLi) {
const uriObj = Spicetify.URI.fromString(pin.uri);
copyLinkLi.style.display = (isPseudoCollection && uriObj.category === 'local-files') ? 'none' : '';
}
// Show and measure for viewport clamping
menu.style.display = 'block';
const rect = menu.getBoundingClientRect();
let x = e.clientX;
let y = e.clientY;
if (x + rect.width > window.innerWidth) x = window.innerWidth - rect.width - 4;
if (y + rect.height > window.innerHeight) y = window.innerHeight - rect.height - 4;
if (x < 0) x = 4;
if (y < 0) y = 4;
menu.style.left = x + 'px';
menu.style.top = y + 'px';
const firstBtn = menu.querySelector('[data-action]');
if (firstBtn) firstBtn.focus();
// Async: check ownership for playlist-specific actions
const isPlaylist = pin.type === 'playlist' || pin.type === 'playlist-v2';
if (isPlaylist) {
try {
const meta = await Spicetify.Platform.PlaylistAPI.getMetadata(pin.uri);
const username = Spicetify.Platform.username;
const isOwner = meta?.owner?.uri === `spotify:user:${username}`;
// Only update if this menu is still open for the same pin
if (ctxMenuTargetUri === pin.uri && isOwner) {
menu.querySelectorAll('.ep-ctx-owner').forEach(el => { el.style.display = ''; });
// Update visibility label
const visLabel = menu.querySelector('[data-action="visibility"] .ep-ctx-label');
if (visLabel) {
visLabel.textContent = meta?.isPublished ? 'Make private' : 'Make public';
}
// Re-measure and re-clamp after showing more items
const newRect = menu.getBoundingClientRect();
if (parseInt(menu.style.top) + newRect.height > window.innerHeight) {
menu.style.top = Math.max(4, window.innerHeight - newRect.height - 4) + 'px';
}
}
} catch {}
}
}
/**
* Hides the custom context menu and clears target state
*/
function hideContextMenu() {
const menu = document.getElementById('ep-context-menu');
if (menu) menu.style.display = 'none';
ctxMenuTargetUri = null;
}
/**
* Sets up delegated click handler on the context menu for all actions
*/
function setupContextMenuActions() {
const menu = document.getElementById('ep-context-menu');
if (!menu) return;
menu.addEventListener('click', async (e) => {
const btn = e.target.closest('[data-action]');
if (!btn || !ctxMenuTargetUri) return;
const action = btn.dataset.action;
const pin = currentPins.find(p => p.uri === ctxMenuTargetUri);
if (!pin && action !== 'settings') return;
switch (action) {
case 'play':
togglePlayback(pin);
break;
case 'shuffle':
try {
Spicetify.Player.setShuffle(true);
playPin(pin);
} catch (err) {
Spicetify.showNotification('Failed to start shuffle', true);
}
break;
case 'queue':
try {
Spicetify.Platform.PlayerAPI.addToQueue([{ uri: pin.uri }]);
Spicetify.showNotification(`Added to queue: ${pin.name}`);
} catch (err) {
console.warn('[Enhanced Pins] Add to queue failed', err);
Spicetify.showNotification('Failed to add to queue', true);
}
break;
case 'jam':
try {
if (Spicetify.Platform.SocialConnectAPI?.createSession) {
await Spicetify.Platform.SocialConnectAPI.createSession();
Spicetify.showNotification('Jam session started');
} else {
Spicetify.showNotification('Jam is not available', true);
}
} catch {
Spicetify.showNotification('Failed to start Jam', true);
}
break;
case 'radio': {
const uriObj = Spicetify.URI.fromString(pin.uri);
const id = uriObj.id || uriObj._base62Id;
const type = uriObj.type === 'playlist-v2' ? 'playlist' : uriObj.type;
Spicetify.Platform.History.push(`/station/${type}/${id}`);
break;
}
case 'download':
try {
if (Spicetify.Platform.OfflineAPI?.addDownload) {
await Spicetify.Platform.OfflineAPI.addDownload(pin.uri);
Spicetify.showNotification(`Downloading: ${pin.name}`);
} else {
Spicetify.showNotification('Download is not available', true);
}
} catch {
Spicetify.showNotification('Failed to start download', true);
}
break;
case 'edit': {
hideContextMenu();
try {
const meta = await Spicetify.Platform.PlaylistAPI.getMetadata(pin.uri);
const uriObj2 = Spicetify.URI.fromString(pin.uri);
const playlistId = uriObj2.id || uriObj2._base62Id;
const currentImage = meta?.images?.[0]?.url || pin.imageUrl || '';
let newImageBase64 = null;
const content = document.createElement('div');
content.className = 'ep-edit-modal';
content.innerHTML = `
By proceeding, you agree to give Spotify access to the image you choose to upload. Please make sure you have the right to upload the image.
`;
// Image picker
const imgWrapper = content.querySelector('.ep-edit-image-wrapper');
const fileInput = content.querySelector('.ep-edit-file-input');
imgWrapper.addEventListener('click', () => fileInput.click());
fileInput.addEventListener('change', (evt) => {
const file = evt.target.files[0];
if (!file) return;
const reader = new FileReader();
reader.onload = (re) => {
const img = new Image();
img.onload = () => {
const canvas = document.createElement('canvas');
const size = 512;
canvas.width = size;
canvas.height = size;
const ctx = canvas.getContext('2d');
const minDim = Math.min(img.width, img.height);
const sx = (img.width - minDim) / 2;
const sy = (img.height - minDim) / 2;
ctx.drawImage(img, sx, sy, minDim, minDim, 0, 0, size, size);
const dataUrl = canvas.toDataURL('image/jpeg', 0.9);
newImageBase64 = dataUrl.split(',')[1];
let preview = content.querySelector('.ep-edit-img-preview');
if (preview.tagName !== 'IMG') {
const newImg = document.createElement('img');
newImg.className = 'ep-edit-img-preview';
newImg.alt = '';
preview.replaceWith(newImg);
preview = newImg;
}
preview.src = dataUrl;
};
img.src = re.target.result;
};
reader.readAsDataURL(file);
});
content.querySelector('.ep-edit-save').addEventListener('click', async () => {
const name = content.querySelector('input[type="text"]').value.trim();
const desc = content.querySelector('textarea').value;
if (!name) { Spicetify.showNotification('Name cannot be empty', true); return; }
try {
await Spicetify.Platform.PlaylistAPI.updateDetails(pin.uri, { name, description: desc });
if (newImageBase64) {
let imageUploaded = false;
try {
const token = Spicetify.Platform?.Session?.accessToken;
if (token) {
const res = await fetch(`https://api.spotify.com/v1/playlists/${playlistId}/images`, {
method: 'PUT',
headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'image/jpeg' },
body: newImageBase64
});
imageUploaded = res.ok || res.status === 202;
}
} catch (imgErr) {
console.warn('[Enhanced Pins] Image upload failed', imgErr);
}
if (!imageUploaded) {
Spicetify.showNotification('Name saved but image upload failed', true);
}
}
const allPins = loadPins();
const p = allPins.find(pp => pp.uri === pin.uri);
if (p) {
p.name = name;
if (newImageBase64) {
try {
const newMeta = await Spicetify.Platform.PlaylistAPI.getMetadata(pin.uri);
if (newMeta?.images?.[0]?.url) p.imageUrl = newMeta.images[0].url;
} catch {}
}
savePins(allPins);
renderPins();
}
Spicetify.PopupModal.hide();
Spicetify.showNotification('Playlist updated');
} catch {
Spicetify.showNotification('Failed to update playlist', true);
}
});
Spicetify.PopupModal.display({ title: 'Edit details', content, isLarge: false });
} catch {
Spicetify.showNotification('Failed to load playlist details', true);
}
return; // Already hid context menu above
}
case 'delete': {
hideContextMenu();
const content = document.createElement('div');
content.innerHTML = `
Are you sure you want to delete ${escapeHtml(pin.name)}? This cannot be undone.
`;
content.querySelector('.ep-delete-cancel').addEventListener('click', () => Spicetify.PopupModal.hide());
content.querySelector('.ep-delete-confirm').addEventListener('click', async () => {
try {
await Spicetify.Platform.RootlistAPI.remove([{ uri: pin.uri }]);
let pins = loadPins();
pins = pins.filter(p => p.uri !== pin.uri);
savePins(pins);
renderPins();
Spicetify.PopupModal.hide();
Spicetify.showNotification(`Deleted: ${pin.name}`);
} catch {
Spicetify.showNotification('Failed to delete playlist', true);
}
});
Spicetify.PopupModal.display({ title: 'Delete playlist', content, isLarge: false });
return;
}
case 'visibility': {
const label = btn.querySelector('.ep-ctx-label')?.textContent;
const makingPrivate = label === 'Make private';
try {
await Spicetify.Platform.PlaylistPermissionsAPI.setBasePermission(
pin.uri,
makingPrivate ? 'BLOCKED' : 'VIEWER'
);
Spicetify.showNotification(makingPrivate ? 'Playlist is now private' : 'Playlist is now public');
} catch {
Spicetify.showNotification('Failed to change visibility', true);
}
break;
}
case 'native-pin':
try {
await Spicetify.Platform.LibraryAPI.pin(pin.uri);
Spicetify.showNotification('Pinned to sidebar');
} catch {
Spicetify.showNotification('Failed to pin', true);
}
break;
case 'copy-link':
navigator.clipboard.writeText(uriToUrl(pin.uri)).then(() => {
Spicetify.showNotification('Link copied to clipboard');
}).catch(() => {
Spicetify.showNotification('Failed to copy link', true);
});
break;
case 'copy-uri':
navigator.clipboard.writeText(pin.uri).then(() => {
Spicetify.showNotification('URI copied to clipboard');
}).catch(() => {
Spicetify.showNotification('Failed to copy URI', true);
});
break;
case 'unpin':
performUnpin(pin.uri);
break;
case 'change-icon':
hideContextMenu();
showIconPickerModal(pin);
return;
case 'pin-to-top':
movePinToEdge(pin.uri, 'top');
break;
case 'pin-to-bottom':
movePinToEdge(pin.uri, 'bottom');
break;
case 'settings':
showSettingsModal();
break;
}
hideContextMenu();
});
}
/**
* Sets up dismissal handlers: click-outside, Escape, scroll, and keyboard nav
*/
function setupContextMenuDismissal() {
document.addEventListener('mousedown', (e) => {
const menu = document.getElementById('ep-context-menu');
if (menu && menu.style.display !== 'none' && !menu.contains(e.target)) {
hideContextMenu();
}
}, true);
document.addEventListener('keydown', (e) => {
const menu = document.getElementById('ep-context-menu');
if (!menu || menu.style.display === 'none') return;
if (e.key === 'Escape') hideContextMenu();
}, true);
window.addEventListener('scroll', () => {
const menu = document.getElementById('ep-context-menu');
if (menu && menu.style.display !== 'none') hideContextMenu();
}, { capture: true });
// Keyboard navigation within menu
const menu = document.getElementById('ep-context-menu');
if (menu) {
menu.addEventListener('keydown', (e) => {
if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;
e.preventDefault();
const buttons = [...menu.querySelectorAll('[data-action]')];
const idx = buttons.indexOf(document.activeElement);
if (e.key === 'ArrowDown') {
buttons[idx < buttons.length - 1 ? idx + 1 : 0].focus();
} else {
buttons[idx > 0 ? idx - 1 : buttons.length - 1].focus();
}
});
}
}
/**
* Renders the enhanced pins section in the sidebar using vanilla DOM.
* Each item gets click (navigate), dblclick (play), and contextmenu (custom menu) handlers.
*/
function renderPins() {
const pins = loadPins();
currentPins = pins;
const config = loadConfig();
applyTitleVars(config);
const existing = document.getElementById(EP_CONTAINER_ID);
if (existing) existing.remove();
if (pins.length === 0) {
updateHideStyles();
return;
}
// Resolve before building any DOM: when the library isn't mounted, skip the
// rebuild entirely (the sidebar observer retries) but keep hide rules current.
const injection = findInjectionPoint();
if (!injection) {
updateHideStyles();
return;
}
// Filter pins based on active sidebar entity type filter
const activeFilter = getActiveTypeFilter();
const filteredPins = activeFilter
? pins.filter(pin => activeFilter.matches(pin))
: pins;
// Sort and truncate
const sortedPins = sortPins(filteredPins, config.sortMode);
const maxVisible = config.maxVisiblePins;
let displayPins = sortedPins;
let hasMore = false;
if (maxVisible > 0 && !expandedView && sortedPins.length > maxVisible) {
displayPins = sortedPins.slice(0, maxVisible);
hasMore = true;
}
const viewMode = detectViewMode();
const container = document.createElement('div');
container.id = EP_CONTAINER_ID;
container.className = `ep-view-${viewMode}`;
container.dataset.viewMode = viewMode;
container.dataset.filterKey = activeFilter ? activeFilter.key : '';
const section = document.createElement('div');
section.className = 'ep-section';
section.setAttribute('role', 'list');
section.setAttribute('aria-label', 'Enhanced Pins');
// Section header
const header = document.createElement('div');
header.className = 'ep-section-header';
header.innerHTML = `
${escapeHtml(config.titleText || 'Enhanced Pins')} (${pins.length})
`;
const gearBtn = header.querySelector('.ep-settings-gear');
// Defensive event handling: newer Spotify versions attach drag/pointer handlers
// on the libraryRootlist ancestors that can swallow click events on injected
// buttons. Stop propagation at the earliest phase so the click reaches us.
const swallow = (e) => { e.stopPropagation(); };
gearBtn.addEventListener('pointerdown', swallow);
gearBtn.addEventListener('mousedown', swallow);
gearBtn.addEventListener('dragstart', (e) => { e.preventDefault(); e.stopPropagation(); });
gearBtn.addEventListener('click', (e) => {
e.preventDefault();
e.stopPropagation();
showSettingsModal();
});
section.appendChild(header);
// If no pins match the active filter, show header only (settings gear remains accessible)
if (filteredPins.length === 0) {
container.appendChild(section);
injection.parent.insertBefore(container, injection.reference);
updateHideStyles();
return;
}
// Items wrapper for layout control
const itemsWrapper = document.createElement('div');
itemsWrapper.className = 'ep-items';
// Pin items
const clickTimers = {};
displayPins.forEach(pin => {
const pseudoEntry = getPseudoCollectionEntry(pin);
const typeLabel = getTypeLabel(pin, pseudoEntry);
const subtitle = pin.owner ? `${typeLabel} \u2022 ${pin.owner}` : typeLabel;
const item = document.createElement('div');
item.className = 'ep-item';
item.setAttribute('data-uri', pin.uri);
item.setAttribute('role', 'listitem');
item.setAttribute('title', pin.name);
item.tabIndex = 0;
item.innerHTML = `
${pin.imageUrl
? `
})
`
: renderArtPlaceholderHTML(pin, pseudoEntry)}
${escapeHtml(pin.name)}
${renderPinIconHTML(resolvePinIcon(pin, config))}
${escapeHtml(subtitle)}
${escapeHtml(pin.owner || typeLabel)}
`;
item.addEventListener('click', (e) => {
if (e.target.closest('.ep-art-overlay')) return;
if (clickTimers[pin.uri]) return;
clickTimers[pin.uri] = setTimeout(() => {
delete clickTimers[pin.uri];
navigateToPin(pin);
}, 300);
});
item.addEventListener('dblclick', (e) => {
e.preventDefault();
if (clickTimers[pin.uri]) {
clearTimeout(clickTimers[pin.uri]);
delete clickTimers[pin.uri];
}
playPin(pin);
});
item.addEventListener('keydown', (e) => {
if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); navigateToPin(pin); }
});
item.querySelector('.ep-art-overlay').addEventListener('click', (e) => {
e.stopPropagation();
togglePlayback(pin);
});
item.addEventListener('contextmenu', (e) => {
e.preventDefault();
e.stopPropagation();
showContextMenu(e, pin);
});
// Drag source for reordering (only in custom sort mode)
if (config.sortMode === 'custom') {
item.setAttribute('draggable', 'true');
item.addEventListener('dragstart', handleDragStart);
item.addEventListener('dragend', handleDragEnd);
}
// Drop target for pin reorder (element-level; external drops handled at document level)
if (config.sortMode === 'custom') {
item.addEventListener('dragover', handleDragOver);
item.addEventListener('drop', handleDrop);
item.addEventListener('dragleave', handleDragLeave);
}
itemsWrapper.appendChild(item);
});
// "N more" / "Show less" toggle for max visible pins
if (hasMore) {
const moreLink = document.createElement('button');
moreLink.className = 'ep-show-more';
moreLink.textContent = `${sortedPins.length - maxVisible} more`;
moreLink.addEventListener('click', () => { expandedView = true; renderPins(); });
itemsWrapper.appendChild(moreLink);
} else if (maxVisible > 0 && expandedView && sortedPins.length > maxVisible) {
const lessLink = document.createElement('button');
lessLink.className = 'ep-show-more';
lessLink.textContent = 'Show less';
lessLink.addEventListener('click', () => { expandedView = false; renderPins(); });
itemsWrapper.appendChild(lessLink);
}
section.appendChild(itemsWrapper);
container.appendChild(section);
injection.parent.insertBefore(container, injection.reference);
updateHideStyles();
updatePlayingStates();
}
/**
* Updates a dynamic