@spicetify/kit 0.1.0

package/vendor/stdlib/src/registers/mount.ts

@@ -0,0 +1,307 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// v3 registers mount without source transforms: instead of patching xpui to
+// call __renderX(), a registry renders into a DOM anchor. The exposed React
+// forwards to the client's own instance, so client components, stdlib
+// chrome, and module components all share one hook dispatcher.
+
+import { React, ReactDOM } from "../expose/React.ts";
+import { warn } from "../logger.ts";
+import { byOrder } from "./order.ts";
+import type { Registry } from "./registry.ts";
+
+export interface AnchorSpec {
+	className: string;
+	registry: Registry<any>;
+	setRefresh: (cb: (() => void) | undefined) => void;
+	// Position for the anchor; null means the client has not rendered the
+	// slot yet and the mount should wait for it.
+	findSlot: () => { parent: Element; before?: Node | null } | null;
+	// Custom rendering over the registry items (e.g. route matching);
+	// defaults to rendering every item.
+	renderItems?: (items: any[]) => unknown;
+	// The anchor host's display. Defaults to "contents" so the host is
+	// layout-transparent and its items participate directly in the client
+	// slot's layout. Set to a box value (e.g. "flex") when the items need
+	// their own layout context instead of inheriting the slot's — so the
+	// anchor counts as a single item in the slot and spaces its own children.
+	hostDisplay?: string;
+}
+
+// One broken registered node must not take down the others — and a crash
+// must be visible, never a silent blank (a session's worth of “Spotify looks
+// broken” reports traced back to exactly that). The fallback uses host
+// elements only: when the crash IS a broken component surface, any component
+// rendered here would die the same way. Route-overlay items get a full card;
+// bar and menu items get a compact marker that keeps their layout.
+export const createItemBoundary = (R: any, label: string) => {
+	const isPage = label.includes("route");
+	const describe = (error: unknown) => {
+		// Never throws: this runs inside getDerivedStateFromError, and a throw
+		// here unmounts the whole anchor root — the exact blank this boundary
+		// exists to prevent. Exotic errors (null-prototype throws, throwing
+		// toString/getters) get the fixed string instead.
+		try {
+			const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+			return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+		} catch {
+			return "(unprintable error)";
+		}
+	};
+	return class ItemBoundary extends R.Component {
+		state = { failed: false, message: "" };
+		static getDerivedStateFromError(error: unknown) {
+			return { failed: true, message: describe(error) };
+		}
+		componentDidCatch(error: unknown) {
+			console.error(`[stdlib] registered ${label} item crashed:`, error);
+		}
+		render() {
+			const { failed, message } = this.state as { failed: boolean; message: string };
+			if (!failed) return (this.props as { children?: unknown }).children;
+			if (!isPage) {
+				return R.createElement(
+					"span",
+					{
+						title: `A Spicetify module item crashed here: ${message}`,
+						style: { opacity: 0.6, padding: "0 4px", cursor: "help" },
+					},
+					"⚠",
+				);
+			}
+			return R.createElement(
+				"div",
+				{
+					style: {
+						maxWidth: "560px",
+						margin: "48px auto",
+						padding: "24px",
+						borderRadius: "8px",
+						background: "var(--spice-card, #282828)",
+						color: "var(--spice-text, #fff)",
+						fontSize: "14px",
+						lineHeight: 1.5,
+					},
+				},
+				R.createElement("h2", { style: { margin: "0 0 8px", fontSize: "18px" } }, "This module page crashed"),
+				R.createElement(
+					"p",
+					{ style: { margin: "0 0 12px", opacity: 0.8 } },
+					"The rest of the client keeps working. Reloading usually recovers it; if it keeps crashing, disable the module from the Spicetify Manager.",
+				),
+				R.createElement(
+					"code",
+					{
+						style: {
+							display: "block",
+							padding: "8px",
+							background: "rgba(0,0,0,.3)",
+							borderRadius: "4px",
+							marginBottom: "16px",
+							userSelect: "text",
+						},
+					},
+					message,
+				),
+				R.createElement(
+					"button",
+					{
+						onClick: () => location.reload(),
+						style: {
+							padding: "8px 16px",
+							borderRadius: "500px",
+							border: "none",
+							cursor: "pointer",
+							background: "var(--spice-button, #1ed760)",
+							color: "var(--spice-main, #121212)",
+							fontWeight: 700,
+						},
+					},
+					"Reload Spotify",
+				),
+			);
+		}
+	};
+};
+
+// The top bar doubles as the window drag region; like the client's own
+// buttons, anchor children must opt out or physical clicks drag the window
+// instead of reaching them (synthetic and CDP clicks bypass this, so only
+// real mice notice).
+const ensureAnchorStyle = () => {
+	if (document.getElementById("spicetify-anchor-style")) return;
+	const style = document.createElement("style");
+	style.id = "spicetify-anchor-style";
+	style.textContent = "[data-spicetify-anchor] > * { -webkit-app-region: no-drag; app-region: no-drag; }";
+	document.head.appendChild(style);
+};
+
+// One shared observer serves every anchor: the client mutates the DOM
+// constantly, and per-anchor subtree observers multiply that cost. Each
+// tick is one isConnected check per pending or placed anchor.
+type WatchedAnchor = { host: HTMLElement; place: () => boolean; started: boolean; start: () => void };
+const watched: WatchedAnchor[] = [];
+let bodyObserver: MutationObserver | undefined;
+const watchAnchor = (anchor: WatchedAnchor) => {
+	watched.push(anchor);
+	bodyObserver ??= (() => {
+		const observer = new MutationObserver(() => {
+			for (const a of watched) {
+				if (a.host.isConnected) continue;
+				if (a.place() && !a.started) {
+					a.started = true;
+					a.start();
+				}
+			}
+		});
+		observer.observe(document.body, { childList: true, subtree: true });
+		return observer;
+	})();
+};
+
+export function mountRegistryAnchor(spec: AnchorSpec): void {
+	// Transform experiments render through the injected __renderX() calls;
+	// an anchor would double-render.
+	if ((globalThis as never as Record<string, unknown>).__SPICETIFY_APPLY_TRANSFORMS__) return;
+	if (typeof document === "undefined") return;
+
+	void CHUNKS.xpui.promise.then(() => {
+		const R = React as any;
+		const createRoot = (ReactDOM as any).createRoot;
+		if (typeof createRoot !== "function") {
+			warn("[stdlib] cannot mount register anchor (no createRoot):", spec.className);
+			return;
+		}
+
+		const host = document.createElement("span");
+		host.className = spec.className;
+		host.style.display = spec.hostDisplay ?? "contents";
+		host.dataset.spicetifyAnchor = "";
+		ensureAnchorStyle();
+
+		const place = () => {
+			const slot = spec.findSlot();
+			if (!slot) return false;
+			slot.parent.insertBefore(host, slot.before ?? null);
+			return true;
+		};
+
+		const start = () => {
+			const root = createRoot(host);
+			const ItemBoundary = createItemBoundary(R, spec.className);
+			const Wrapper = () => {
+				const [, refresh] = R.useReducer((n: number) => n + 1, 0);
+				R.useEffect(() => {
+					spec.setRefresh(refresh);
+					return () => spec.setRefresh(undefined);
+				}, []);
+				if (spec.renderItems) {
+					return R.createElement(ItemBoundary, null, spec.renderItems(spec.registry.all()));
+				}
+				return R.createElement(
+					R.Fragment,
+					null,
+					...byOrder(spec.registry.all()).map((item: unknown, i: number) =>
+						R.createElement(ItemBoundary, { key: i }, item),
+					),
+				);
+			};
+			root.render(R.createElement(Wrapper));
+		};
+
+		const anchor: WatchedAnchor = { host, place, started: false, start };
+		if (place()) {
+			anchor.started = true;
+			start();
+		}
+		// The shared observer both waits for a not-yet-rendered slot and
+		// re-places the host whenever client reconciliation drops it; the
+		// root stays attached to the node, so rendering survives.
+		watchAnchor(anchor);
+	});
+}
+
+// Mount a single element next to a specific client element (rather than into a
+// fixed slot). Used by placeButton's `near` anchoring: the host is inserted
+// before/after the resolved target and re-placed on client re-renders. If the
+// target never appears within giveUpMs, onGiveUp() runs so the caller can fall
+// back to ordinary placement — the button is never silently lost.
+export interface AdjacentSpec {
+	className: string;
+	element: React.ReactNode;
+	findTarget: () => Element | null;
+	side: "before" | "after";
+	giveUpMs: number;
+	onGiveUp: () => void;
+}
+
+export function mountAdjacent(spec: AdjacentSpec): { remove: () => void } {
+	let removed = false;
+	let root: { render?: (node: unknown) => void; unmount?: () => void } | undefined;
+	const host = document.createElement("span");
+	host.className = spec.className;
+	host.style.display = "contents";
+	host.dataset.spicetifyAnchor = "";
+
+	const place = (): boolean => {
+		const target = spec.findTarget();
+		if (!target?.parentElement) return false;
+		const before = spec.side === "before" ? target : target.nextSibling;
+		target.parentElement.insertBefore(host, before);
+		return true;
+	};
+
+	const remove = () => {
+		removed = true;
+		root?.unmount?.();
+		host.remove();
+	};
+
+	// Transform experiments render through injected __renderX() calls, and there
+	// is no DOM off the client; in both cases fall back to ordinary placement.
+	if (
+		(globalThis as never as Record<string, unknown>).__SPICETIFY_APPLY_TRANSFORMS__ ||
+		typeof document === "undefined"
+	) {
+		spec.onGiveUp();
+		return { remove: () => {} };
+	}
+
+	void CHUNKS.xpui.promise.then(() => {
+		if (removed) return;
+		const R = React as any;
+		const createRoot = (ReactDOM as any).createRoot;
+		if (typeof createRoot !== "function") {
+			spec.onGiveUp();
+			return;
+		}
+		const start = () => {
+			ensureAnchorStyle();
+			root = createRoot(host);
+			const ItemBoundary = createItemBoundary(R, spec.className);
+			root!.render?.(R.createElement(ItemBoundary, null, spec.element));
+		};
+
+		const deadline = Date.now() + spec.giveUpMs;
+		const attempt = () => {
+			if (removed) return;
+			if (place()) {
+				start();
+				// Reuse the shared observer for re-placement only (already started).
+				watchAnchor({ host, place, started: true, start: () => {} });
+				return;
+			}
+			if (Date.now() > deadline) {
+				spec.onGiveUp();
+				return;
+			}
+			setTimeout(attempt, 150);
+		};
+		attempt();
+	});
+
+	return { remove };
+}

package/vendor/stdlib/src/registers/nativeAnchors.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// Semantic names for the client's own buttons, owned and maintained here so
+// modules never hard-code fragile selectors. A module anchors to a stable
+// name (e.g. "playbar:queue"); stdlib maps it to the current client's
+// selectors. When Spotify moves a button, only this map changes — modules keep
+// working, and placeButton falls back to order-placement if a name can't be
+// resolved (so a stale map degrades, it never hides the button).
+//
+// Only locale-independent selectors are offered. The playbar controls carry
+// stable data-testid attributes; the top-bar actions only expose localized
+// aria-labels, so no top-bar anchors are published here.
+
+export type NativeAnchor =
+	| "playbar:lyrics"
+	| "playbar:queue"
+	| "playbar:mute"
+	| "playbar:miniplayer"
+	| "playbar:fullscreen";
+
+// Candidate selectors per anchor, newest first; the first match in the DOM
+// wins. Add older-client fallbacks to the array rather than branching.
+export const NATIVE_ANCHOR_SELECTORS: Record<NativeAnchor, string[]> = {
+	"playbar:lyrics": ['[data-testid="lyrics-button"]'],
+	"playbar:queue": ['[data-testid="control-button-queue"]'],
+	"playbar:mute": ['[data-testid="volume-bar-toggle-mute-button"]'],
+	"playbar:miniplayer": ['[data-testid="pip-toggle-button"]'],
+	"playbar:fullscreen": ['[data-testid="fullscreen-mode-button"]'],
+};
+
+export const isNativeAnchor = (name: string): name is NativeAnchor => Object.hasOwn(NATIVE_ANCHOR_SELECTORS, name);
+
+// Resolve an anchor name to the live client element, or null if none of its
+// selectors match (unknown name, or the client no longer renders it).
+export const resolveNativeAnchor = (
+	name: NativeAnchor,
+	root: Pick<Document, "querySelector"> = document,
+): Element | null => {
+	const selectors = NATIVE_ANCHOR_SELECTORS[name];
+	if (!selectors) return null;
+	for (const selector of selectors) {
+		const el = root.querySelector(selector);
+		if (el) return el;
+	}
+	return null;
+};

package/vendor/stdlib/src/registers/navlink.tsx

@@ -0,0 +1,165 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { React } from "../expose/React.ts";
+import { createIconComponent } from "../createIconComponent.tsx";
+import { transformer } from "../../mixin.ts";
+import { Platform } from "../expose/Platform.ts";
+import { warn } from "../logger.ts";
+import { classnames } from "../webpack/ClassNames.ts";
+import { ScrollableContainer, Tooltip } from "../webpack/ReactComponents.ts";
+import { UI } from "../webpack/ComponentLibrary.ts";
+import { mountRegistryAnchor } from "./mount.ts";
+import { Registry } from "./registry.ts";
+
+const registry = new (class extends Registry<React.ReactNode> {
+	override add(value: React.ReactNode): this {
+		refresh?.();
+		return super.add(value);
+	}
+
+	override delete(value: React.ReactNode): boolean {
+		refresh?.();
+		return super.delete(value);
+	}
+})();
+export default registry;
+
+let refresh: React.DispatchWithoutAction | undefined;
+
+declare global {
+	var __renderNavLinks: () => React.ReactNode;
+}
+
+globalThis.__renderNavLinks = () =>
+	React.createElement(() => {
+		[, refresh] = React.useReducer((n) => n + 1, 0);
+
+		if (!ScrollableContainer) {
+			return;
+		}
+
+		return (
+			<ScrollableContainer className="custom-navlinks-scrollable_container" onlyHorizontalWheel>
+				{registry.all()}
+			</ScrollableContainer>
+		);
+	});
+transformer(
+	(emit) => (str) => {
+		emit();
+
+		str = str.replace(
+			/{(?=[^{}]*(?:{[^{}]*(?:{[^{}]*(?:{[^{}]*}[^{}]*)*}[^{}]*)*}[^{}]*)*(?<=[,{])"data-testid":"global-nav-bar")([^{}]*(?:{[^{}]*(?:{[^{}]*(?:{[^{}]*}[^{}]*)*}[^{}]*)*}[^{}]*)*(?<=[,{]))children:([^{}]*(?:{[^{}]*(?:{[^{}]*(?:{[^{}]*}[^{}]*)*}[^{}]*)*}[^{}]*)*)(,[^{}]*(?:{[^{}]*(?:{[^{}]*(?:{[^{}]*}[^{}]*)*}[^{}]*)*}[^{}]*)*|)}/,
+			"{$1children:(function(children){const p=children[0].props;p.children=[p.children,__renderNavLinks()].flat();return children})($2)$3}",
+		);
+
+		return str;
+	},
+	{
+		glob: /^\/xpui\.js/,
+	},
+);
+transformer(
+	(emit) => (str) => {
+		emit();
+
+		str = str.replace('["","/","/home/",', '["","/","/home/","/bespoke/*",');
+
+		return str;
+	},
+	{
+		glob: /^\/dwp\-top\-bar\.js/,
+	},
+);
+
+mountRegistryAnchor({
+	className: "spicetify-navlinks-anchor",
+	registry,
+	setRefresh: (cb) => {
+		refresh = cb;
+	},
+	findSlot: () => {
+		const wrapper = document.querySelector(".main-globalNav-historyButtonsWrapper");
+		return wrapper ? { parent: wrapper } : null;
+	},
+	// A real flex box, not the default display:contents. The history-buttons
+	// wrapper spaces its children with a wide gap meant to separate button
+	// groups; as one box the anchor takes that gap once (separating our links
+	// from the back/forward group), while the nav links inside space
+	// themselves with the client's own 8px navlink margins.
+	hostDisplay: "flex",
+});
+
+// Registered elements are frozen in the registry, so parent refreshes
+// bail out on identical children; any registered component that renders
+// route-dependent state must subscribe to history itself.
+export const useHistoryRefresh = (): void => {
+	const [, force] = React.useReducer((n: number) => n + 1, 0);
+	React.useEffect(() => {
+		try {
+			return Platform.getHistory().listen(() => force()) as (() => void) | undefined;
+		} catch (e) {
+			warn("[stdlib] cannot follow history:", e);
+			return undefined;
+		}
+	}, []);
+};
+
+export type NavLinkProps = {
+	localizedApp: string;
+	appRoutePath: string;
+	/** Inner SVG markup drawn on the stdlib 16-grid (upscaled to the client's 24px nav glyph). */
+	icon: string;
+	/** Filled variant shown while the route is active; same 16-grid contract. */
+	activeIcon: string;
+};
+export const NavLink: React.FC<NavLinkProps> = (props) => {
+	useHistoryRefresh();
+	const isActive = Platform.getHistory().location.pathname?.startsWith(props.appRoutePath);
+	const createIcon = () =>
+		// Icons are authored on the stdlib 16-grid; upscale to the client's
+		// 24px nav glyph size so they fill the circle like Home's.
+		createIconComponent({ icon: isActive ? props.activeIcon : props.icon, iconSize: 16, realIconSize: 24 });
+
+	return (
+		<_NavLinkGlobal
+			localizedApp={props.localizedApp}
+			appRoutePath={props.appRoutePath}
+			createIcon={createIcon}
+			isActive={isActive}
+		/>
+	);
+};
+
+interface NavLinkFactoryProps {
+	localizedApp: string;
+	appRoutePath: string;
+	createIcon: () => React.ReactNode;
+	isActive: boolean;
+}
+
+const _NavLinkGlobal: React.FC<NavLinkFactoryProps> = (props) => {
+	return (
+		<div className="inline-flex">
+			<Tooltip label={props.localizedApp}>
+				<UI.ButtonTertiary
+					iconOnly={props.createIcon}
+					className={classnames(
+						// The circular chrome the client paints on its own nav links
+						// (Home); without it the button renders bare on the bar.
+						"main-globalNav-navLink",
+						"main-globalNav-link-icon link-subtle",
+						{
+							"main-globalNav-navLinkActive": props.isActive,
+						},
+					)}
+					aria-label={props.localizedApp}
+					onClick={() => Platform.getHistory().push(props.appRoutePath)}
+				/>
+			</Tooltip>
+		</div>
+	);
+};

package/vendor/stdlib/src/registers/order.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// Pure ordering used by the register mount render. Kept free of any client
+// (React/DOM) imports so it can be unit-tested in Node.
+
+interface Orderable {
+	props?: { order?: number };
+}
+
+// Stable ascending sort by an optional numeric `order` prop carried on a
+// registered element (lower renders earlier). Items without one are treated
+// as order 0 and keep their registration order; equal orders fall back to it
+// too. This backs registrar.placeButton(..., { order }); plain register()
+// items are all order-0 and so keep insertion order, unchanged.
+export const byOrder = <T extends Orderable>(items: T[]): T[] =>
+	items
+		.map((item, i) => [item, i] as const)
+		.sort(([a, ai], [b, bi]) => (a?.props?.order ?? 0) - (b?.props?.order ?? 0) || ai - bi)
+		.map(([item]) => item);