refactor(modules): make registrars own buttons

Author: afonsojramos

BEST_PRACTICES.md

@@ -67,6 +67,13 @@ picking a register key. It gives you ordering (`order`) and native anchoring
 (`near: { anchor: "playbar:lyrics" }`) so your control sits where the user
 would expect rather than wherever insertion order happened to put it.
 
+Every first-party button must still be owned by a registrar. A stateful button
+may use `registrar.register("playbarButton", <MyButton />)` instead of
+`placeButton`, but it must not instantiate the legacy `Spicetify.Playbar.Button`
+or `Spicetify.Topbar.Button` APIs and manually manage registration. Those
+compatibility surfaces exist for v2 extensions; the registrar is what
+guarantees v3 unload cleanup.
+
 ---
 
 ## Degrade, never destroy

docs/authoring-guide.md

@@ -100,6 +100,10 @@ Options:
 It returns a handle with `remove()`; the button is also removed automatically
 when the module unloads.
 
+`onClick` receives the native React mouse event. Use `event.currentTarget` when
+an overlay needs to be positioned from the button's bounds; this avoids keeping
+a manually registered legacy button solely to obtain its DOM element.
+
 **Native anchoring.** `near` sits the button next to one of the client's own
 buttons instead of in the module-button group:
 

docs/module-standard.md

@@ -168,6 +168,10 @@ for you on unload.
 For top-bar and playbar buttons, prefer `registrar.placeButton(location, options)`
 over the raw button registers above: it adds ordering and native anchoring in one
 call. See the [authoring guide](./authoring-guide.md#4-buttons-use-placebutton).
+Use the raw registrar entry only when a React component owns changing state or
+needs a more specialized lifecycle. First-party modules must not use the legacy
+`Spicetify.Playbar.Button` or `Spicetify.Topbar.Button` constructors; stdlib
+retains them solely as a migration bridge for third-party v2 extensions.
 
 Themes are a special case: a **css-only module** (a `color.ini` plus `user.css`
 as the css entry). The loader parses `[Section]`s into switchable schemes and

modules/loopy-loop/metadata.json

@@ -1,7 +1,7 @@
 {
 	"name": "loopy-loop",
 	"kind": "extension",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"authors": ["spicetify"],
 	"description": "A-B repeat and section-skip markers on the playback bar; loops and skips persist per song.",
 	"entries": {
@@ -10,7 +10,7 @@
 	},
 	"hasMixins": false,
 	"dependencies": {
-		"stdlib": "^1.5.0"
+		"stdlib": "^1.5.2"
 	},
 	"preview": "https://raw.githubusercontent.com/spicetify/modules/main/previews/loopy-loop.png"
 }

modules/loopy-loop/mod.tsx

@@ -5,21 +5,16 @@
  * Ported to the v3 module standard from the classic "Loopy loop" extension by
  * khanhas. Right click on the progress bar to set song start/end markers and
  * section skips; all points persist per song across sessions. The client's
- * v2-compatible Player events, LocalStorage, Playbar.Button and showNotification
- * helpers still work in v3, so the logic is kept near-verbatim; only the injected
- * <style> tag moved into index.scss and all teardown routes through ctx.defer.
+ * v2-compatible Player events, LocalStorage and showNotification helpers still
+ * work in v3, so the logic is kept near-verbatim. The playbar control mounts
+ * through the registrar and all teardown routes through the module lifecycle.
  */
 
-import { client, type ModuleRuntimeContext } from "/modules/stdlib/mod.ts";
+import { client, createRegistrar, type ModuleRuntimeContext } from "/modules/stdlib/mod.ts";
 import { findActiveZone, moveEnd, moveStart, moveZoneEdge, parseStoredState, restartThresholds } from "./logic.ts";
 
 import type { SkipZone } from "./logic.ts";
 
-interface PlaybarButtonHandle {
-	element: HTMLElement;
-	deregister(): void;
-}
-
 export default async function (ctx: ModuleRuntimeContext) {
 	let disposed = false;
 	const timers = new Set<number>();
@@ -595,17 +590,19 @@ export default async function (ctx: ModuleRuntimeContext) {
 	tryLoadInitialState(10);
 
 	// Toolbar button
-	let toolbarBtn: PlaybarButtonHandle | null = null;
-	try {
-		const markerIcon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" height="16" width="16"><rect x="1" y="7" width="14" height="2" rx="1"/><rect x="3" y="3" width="2" height="10" rx="1"/><rect x="11" y="3" width="2" height="10" rx="1"/><rect x="6" y="5" width="1.5" height="6" rx="0.75"/><rect x="8.5" y="5" width="1.5" height="6" rx="0.75"/></svg>`;
-		toolbarBtn = new client.playbar.Button("Loopy Loop", markerIcon, (self) => {
+	const registrar = createRegistrar(ctx);
+	const markerIcon = `<rect x="1" y="7" width="14" height="2" rx="1"/><rect x="3" y="3" width="2" height="10" rx="1"/><rect x="11" y="3" width="2" height="10" rx="1"/><rect x="6" y="5" width="1.5" height="6" rx="0.75"/><rect x="8.5" y="5" width="1.5" height="6" rx="0.75"/>`;
+	registrar.placeButton("playbar", {
+		label: "Loopy Loop",
+		icon: markerIcon,
+		onClick: (event) => {
+			event.stopPropagation();
 			mouseOnBarPercent = client.player.getProgressPercent();
 			setupActiveMarker(null, -1);
-			const rect = self.element.getBoundingClientRect();
+			const rect = event.currentTarget.getBoundingClientRect();
 			openContextMenu(rect.left, rect.top);
-		});
-		toolbarBtn.element.addEventListener("click", (e: MouseEvent) => e.stopPropagation());
-	} catch (_) {}
+		},
+	});
 
 	// ----- teardown -----
 	cleanups.push(() => {
@@ -614,7 +611,6 @@ export default async function (ctx: ModuleRuntimeContext) {
 		window.removeEventListener("click", onWindowClick);
 		document.removeEventListener("contextmenu", onContextMenu, true);
 		cancelMoveHide();
-		toolbarBtn?.deregister?.();
 		startMark.remove();
 		endMark.remove();
 		contextMenu.remove();

modules/lyrics-plus/metadata.json

@@ -1,7 +1,7 @@
 {
 	"name": "lyrics-plus",
 	"kind": "app",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"authors": ["spicetify"],
 	"description": "Full-featured lyrics: synced, karaoke, unsynced and translated, from Musixmatch, Spotify, LRCLIB, Netease and Genius.",
 	"entries": {
@@ -10,7 +10,7 @@
 	},
 	"hasMixins": false,
 	"dependencies": {
-		"stdlib": "^1.0.0"
+		"stdlib": "^1.5.2"
 	},
 	"preview": "https://raw.githubusercontent.com/spicetify/modules/main/previews/lyrics-plus.png"
 }

modules/lyrics-plus/mod.tsx

@@ -18,6 +18,7 @@
 import { createRegistrar } from "/modules/stdlib/mod.ts";
 import type { ModuleRuntimeContext } from "/modules/stdlib/mod.ts";
 import { NavLink } from "/modules/stdlib/src/registers/navlink.tsx";
+import { PlaybarButton } from "/modules/stdlib/src/registers/playbarButton.tsx";
 
 import {
 	APP_NAME,
@@ -37,6 +38,8 @@ import { createProviders } from "./providers/index.ts";
 import { AdjustmentsMenu, TranslationMenu } from "./options-menu.tsx";
 import { TopBarContent } from "./tab-bar.tsx";
 import { openConfig } from "./settings.tsx";
+import { lyricsReplacementReady, mountLyricsPlaybarStyleWhenReady, watchLyricsHistory } from "./playbar-lifecycle.ts";
+import type { LyricsHistory } from "./playbar-lifecycle.ts";
 import {
 	emptyLine,
 	GeniusPage,
@@ -1537,71 +1540,45 @@ class LyricsContainer extends react.Component {
 }
 
 // ============================================================================
-// PlaybarButton.js (adapted) — classic IIFE turned into a ctx-scoped function
+// PlaybarButton.js (adapted) — v3 registrar-owned React control
 // ============================================================================
 
-function initPlaybarButton(ctx: ModuleRuntimeContext) {
-	if (!Spicetify.Platform?.History) {
-		const retry = window.setTimeout(() => initPlaybarButton(ctx), 300);
-		ctx.defer(() => window.clearTimeout(retry));
-		return;
-	}
+const PLAYBAR_ICON = `<path d="M13.426 2.574a2.831 2.831 0 0 0-4.797 1.55l3.247 3.247a2.831 2.831 0 0 0 1.55-4.797zM10.5 8.118l-2.619-2.62A63303.13 63303.13 0 0 0 4.74 9.075L2.065 12.12a1.287 1.287 0 0 0 1.816 1.816l3.06-2.688 3.56-3.129zM7.12 4.094a4.331 4.331 0 1 1 4.786 4.786l-3.974 3.493-3.06 2.689a2.787 2.787 0 0 1-3.933-3.933l2.676-3.045 3.505-3.99z"></path>`;
 
-	const button = new Spicetify.Playbar.Button(
-		"Lyrics Plus",
-		`<svg role="img" height="16" width="16" aria-hidden="true" viewBox="0 0 16 16" data-encore-id="icon" fill="currentColor"><path d="M13.426 2.574a2.831 2.831 0 0 0-4.797 1.55l3.247 3.247a2.831 2.831 0 0 0 1.55-4.797zM10.5 8.118l-2.619-2.62A63303.13 63303.13 0 0 0 4.74 9.075L2.065 12.12a1.287 1.287 0 0 0 1.816 1.816l3.06-2.688 3.56-3.129zM7.12 4.094a4.331 4.331 0 1 1 4.786 4.786l-3.974 3.493-3.06 2.689a2.787 2.787 0 0 1-3.933-3.933l2.676-3.045 3.505-3.99z"></path></svg>`,
-		() =>
-			Spicetify.Platform.History.location.pathname !== "/lyrics-plus"
-				? Spicetify.Platform.History.push("/lyrics-plus")
-				: Spicetify.Platform.History.goBack(),
-		false,
-		Spicetify.Platform.History.location.pathname === "/lyrics-plus",
-		false,
+function LyricsPlusPlaybarButton() {
+	const [history, setHistory] = react.useState<LyricsHistory | null>(null);
+	const [visible, setVisible] = react.useState(
+		Spicetify.LocalStorage.get("lyrics-plus:visual:playbar-button") === "true",
 	);
+	const [active, setActive] = react.useState(false);
 
-	const style = document.createElement("style");
-	style.innerHTML = `
-		.main-nowPlayingBar-lyricsButton[data-testid="lyrics-button"] {
-			display: none !important;
-		}
-		li[data-id="/lyrics-plus"] {
-			display: none;
-		}
-	`;
-	style.classList.add("lyrics-plus:visual:playbar-button");
-
-	let registered = false;
-	const setPlaybarButton = () => {
-		if (registered) return;
-		document.head.appendChild(style);
-		button.register();
-		registered = true;
-	};
-	const removePlaybarButton = () => {
-		if (!registered) return;
-		style.remove();
-		button.deregister();
-		registered = false;
-	};
-
-	if (Spicetify.LocalStorage.get("lyrics-plus:visual:playbar-button") === "true") setPlaybarButton();
-
-	const onToggle = (event: any) => {
-		if (event.detail?.name === "playbar-button") {
-			if (event.detail.value) setPlaybarButton();
-			else removePlaybarButton();
-		}
-	};
-	window.addEventListener("lyrics-plus", onToggle);
-
-	const unlisten = Spicetify.Platform.History.listen((location: any) => {
-		button.active = location.pathname === "/lyrics-plus";
-	});
+	react.useEffect(
+		() =>
+			watchLyricsHistory(
+				() => Spicetify.Platform?.History,
+				setHistory,
+				(pathname) => setActive(pathname === ROUTE),
+			),
+		[],
+	);
 
-	ctx.defer(() => {
-		removePlaybarButton();
-		window.removeEventListener("lyrics-plus", onToggle);
-		if (typeof unlisten === "function") unlisten();
+	react.useEffect(() => {
+		const onToggle = (event: any) => {
+			if (event.detail?.name === "playbar-button") setVisible(Boolean(event.detail.value));
+		};
+		window.addEventListener("lyrics-plus", onToggle);
+		return () => window.removeEventListener("lyrics-plus", onToggle);
+	}, []);
+
+	const ready = lyricsReplacementReady(visible, history);
+	react.useEffect(() => mountLyricsPlaybarStyleWhenReady(document, ROUTE, visible, history), [visible, history]);
+
+	if (!ready) return null;
+	return react.createElement(PlaybarButton, {
+		label: "Lyrics Plus",
+		icon: PLAYBAR_ICON,
+		isActive: active,
+		onClick: () => (history.location.pathname !== ROUTE ? history.push(ROUTE) : history.goBack()),
 	});
 }
 
@@ -1616,5 +1593,5 @@ export default function (ctx: ModuleRuntimeContext) {
 		react.createElement(NavLink, { localizedApp: "Lyrics", appRoutePath: ROUTE, icon: ICON, activeIcon: ICON }),
 	);
 	registrar.registerRoute(ROUTE, react.createElement(LyricsContainer));
-	initPlaybarButton(ctx);
+	registrar.register("playbarButton", react.createElement(LyricsPlusPlaybarButton));
 }

modules/lyrics-plus/playbar-lifecycle.test.mts

@@ -0,0 +1,102 @@
+/*
+ * Copyright (C) 2026 spicetify
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import "../stdlib/lib/test-setup.mts";
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+	lyricsReplacementReady,
+	mountLyricsPlaybarStyle,
+	mountLyricsPlaybarStyleWhenReady,
+	watchLyricsHistory,
+	type LyricsHistory,
+} from "./playbar-lifecycle.ts";
+
+describe("watchLyricsHistory", () => {
+	it("waits for late History, follows locations, and removes its listener", () => {
+		let history: LyricsHistory | undefined;
+		let retry: (() => void) | undefined;
+		let unlistened = false;
+		let listener: ((location: { pathname: string }) => void) | undefined;
+		const paths: string[] = [];
+		const ready: LyricsHistory[] = [];
+		const cancelCalls: unknown[] = [];
+
+		const dispose = watchLyricsHistory(
+			() => history,
+			(value) => ready.push(value),
+			(pathname) => paths.push(pathname),
+			(callback) => {
+				retry = callback;
+				return 1 as unknown as ReturnType<typeof setTimeout>;
+			},
+			(timer) => cancelCalls.push(timer),
+		);
+		assert.equal(ready.length, 0);
+
+		history = {
+			location: { pathname: "/" },
+			listen(callback) {
+				listener = callback;
+				return () => {
+					unlistened = true;
+				};
+			},
+			push() {},
+			goBack() {},
+		};
+		retry?.();
+		listener?.({ pathname: "/lyrics-plus" });
+
+		assert.deepEqual(ready, [history]);
+		assert.deepEqual(paths, ["/", "/lyrics-plus"]);
+		dispose();
+		assert.equal(unlistened, true);
+		assert.deepEqual(cancelCalls, [1]);
+	});
+
+	it("stops polling after the bounded attempt budget", () => {
+		const retries: Array<() => void> = [];
+		watchLyricsHistory(
+			() => undefined,
+			() => assert.fail("History never becomes ready"),
+			() => assert.fail("no location can arrive"),
+			(callback) => {
+				retries.push(callback);
+				return retries.length as unknown as ReturnType<typeof setTimeout>;
+			},
+			() => {},
+			3,
+		);
+		for (const retry of retries) retry();
+		assert.equal(retries.length, 2);
+	});
+});
+
+describe("mountLyricsPlaybarStyle", () => {
+	it("stays absent until the replacement button can render", () => {
+		assert.equal(lyricsReplacementReady(true, null), false);
+		mountLyricsPlaybarStyleWhenReady(document, "/lyrics-plus", true, null);
+		assert.equal(document.querySelector("style.lyrics-plus\\:visual\\:playbar-button"), null);
+	});
+
+	it("conditionally adopts and cleans up the replacement style once ready", () => {
+		const history = { location: { pathname: "/" }, listen() {}, push() {}, goBack() {} };
+		const dispose = mountLyricsPlaybarStyleWhenReady(document, "/lyrics-plus", true, history);
+		assert.ok(document.querySelector("style.lyrics-plus\\:visual\\:playbar-button"));
+		if (typeof dispose === "function") dispose();
+		assert.equal(document.querySelector("style.lyrics-plus\\:visual\\:playbar-button"), null);
+	});
+
+	it("removes the adopted style during cleanup", () => {
+		const dispose = mountLyricsPlaybarStyle(document, "/lyrics-plus");
+		const style = document.querySelector("style.lyrics-plus\\:visual\\:playbar-button");
+		assert.ok(style?.textContent?.includes('li[data-id="/lyrics-plus"]'));
+		dispose();
+		assert.equal(document.contains(style), false);
+	});
+});