@spicetify/kit 0.1.0 → 0.2.0

package/vendor/stdlib/src/registers/panel-logic.ts

@@ -0,0 +1,371 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+export interface PanelWidth {
+	default?: number;
+	min?: number;
+	max?: number;
+}
+
+export interface PanelRegistration<Content = unknown> {
+	id: string;
+	label: string;
+	render: () => Content;
+	width?: PanelWidth;
+	onOpen?: () => void;
+	onClose?: () => void;
+}
+
+export interface PanelController {
+	open(): void;
+	close(): void;
+	toggle(): void;
+	isOpen(): boolean;
+	subscribe(listener: (open: boolean) => void): () => void;
+	dispose(): void;
+}
+
+export interface PanelCoordinatorOptions<Content = unknown> {
+	document: Document;
+	window: Window;
+	mount(host: HTMLElement, panel: PanelRegistration<Content>, close: () => void): () => void;
+}
+
+export interface PanelCoordinator<Content = unknown> {
+	register(panel: PanelRegistration<Content>): PanelController;
+	dispose(): void;
+}
+
+type RegistrationState<Content> = {
+	panel: PanelRegistration<Content>;
+	disposed: boolean;
+	listeners: Set<(open: boolean) => void>;
+};
+
+type NativeSnapshot = { hidden: string | null; inert: string | null };
+type StyleSnapshot = { value: string; priority: string };
+
+const WIDTH_DEFAULT = 360;
+const WIDTH_MIN = 280;
+const WIDTH_MAX = 520;
+
+const panelWidth = ({ width }: PanelRegistration): number => {
+	const min = width?.min ?? WIDTH_MIN;
+	const max = Math.max(min, width?.max ?? WIDTH_MAX);
+	return Math.min(max, Math.max(min, width?.default ?? WIDTH_DEFAULT));
+};
+
+const validatePanelWidth = (width: PanelWidth | undefined) => {
+	if (!width) return;
+	for (const key of ["default", "min", "max"] as const) {
+		const value = width[key];
+		if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+			throw new Error(`[stdlib] panel width ${key} must be a finite non-negative number`);
+		}
+	}
+};
+
+const gridTracks = (template: string): string[] => {
+	const tracks: string[] = [];
+	let token = "";
+	let parentheses = 0;
+	let brackets = 0;
+	for (const character of template.trim()) {
+		if (/\s/.test(character) && parentheses === 0 && brackets === 0) {
+			if (token) tracks.push(token);
+			token = "";
+			continue;
+		}
+		token += character;
+		if (character === "(") parentheses += 1;
+		else if (character === ")") parentheses -= 1;
+		else if (character === "[") brackets += 1;
+		else if (character === "]") brackets -= 1;
+	}
+	if (token) tracks.push(token);
+	return tracks.filter((track) => !(track.startsWith("[") && track.endsWith("]")));
+};
+
+export function createPanelCoordinator<Content = unknown>(options: PanelCoordinatorOptions<Content>) {
+	const registrations = new Map<string, RegistrationState<Content>>();
+	const suspended = new Map<HTMLElement, NativeSnapshot>();
+	const ownedStyles = new Map<HTMLElement, Map<string, StyleSnapshot>>();
+	let active: RegistrationState<Content> | undefined;
+	let activeHost: HTMLElement | undefined;
+	let activeSidebar: HTMLElement | undefined;
+	let activeTopContainer: HTMLElement | undefined;
+	let unmount: (() => void) | undefined;
+	let shellObserver: MutationObserver | undefined;
+	let sidebarObserver: MutationObserver | undefined;
+	let returnFocus: HTMLElement | undefined;
+	let disposed = false;
+	let transitioning = false;
+	const transitions: Array<() => void> = [];
+	const Observer = (options.window as unknown as { MutationObserver: typeof MutationObserver }).MutationObserver;
+
+	const safely = (label: string, callback: (() => void) | undefined) => {
+		if (!callback) return;
+		try {
+			callback();
+		} catch (error) {
+			console.error(`[stdlib] panel ${label} failed:`, error);
+		}
+	};
+
+	const notify = (state: RegistrationState<Content>, open: boolean) => {
+		for (const listener of state.listeners) safely("subscriber", () => listener(open));
+	};
+
+	const transition = (action: () => void) => {
+		transitions.push(action);
+		if (transitioning) return;
+		transitioning = true;
+		let firstError: unknown;
+		try {
+			let next: (() => void) | undefined;
+			while ((next = transitions.shift())) {
+				try {
+					next();
+				} catch (error) {
+					firstError ??= error;
+				}
+			}
+		} finally {
+			transitioning = false;
+		}
+		if (firstError) throw firstError;
+	};
+
+	const restoreNative = () => {
+		for (const [element, snapshot] of suspended) {
+			for (const attribute of ["hidden", "inert"] as const) {
+				const value = snapshot[attribute];
+				if (value === null) element.removeAttribute(attribute);
+				else element.setAttribute(attribute, value);
+			}
+		}
+		suspended.clear();
+	};
+
+	const setOwnedStyle = (element: HTMLElement, property: string, value: string) => {
+		let snapshots = ownedStyles.get(element);
+		if (!snapshots) {
+			snapshots = new Map();
+			ownedStyles.set(element, snapshots);
+		}
+		if (!snapshots.has(property)) {
+			snapshots.set(property, {
+				value: element.style.getPropertyValue(property),
+				priority: element.style.getPropertyPriority(property),
+			});
+		}
+		element.style.setProperty(property, value, "important");
+	};
+
+	const restoreOwnedStyles = (element: HTMLElement | undefined) => {
+		if (!element) return;
+		const snapshots = ownedStyles.get(element);
+		if (!snapshots) return;
+		for (const [property, snapshot] of snapshots) {
+			if (snapshot.value) element.style.setProperty(property, snapshot.value, snapshot.priority);
+			else element.style.removeProperty(property);
+		}
+		ownedStyles.delete(element);
+	};
+
+	const suspendNative = (sidebar: HTMLElement) => {
+		for (const child of sidebar.children) {
+			if (!(child instanceof HTMLElement) || child === activeHost) continue;
+			if (!suspended.has(child)) {
+				suspended.set(child, { hidden: child.getAttribute("hidden"), inert: child.getAttribute("inert") });
+			}
+			child.setAttribute("hidden", "");
+			child.setAttribute("inert", "");
+		}
+	};
+
+	const observeSidebar = (sidebar: HTMLElement) => {
+		sidebarObserver?.disconnect();
+		sidebarObserver = new Observer(() => suspendNative(sidebar));
+		sidebarObserver.observe(sidebar, { childList: true });
+	};
+
+	const clearLayout = () => {
+		activeTopContainer?.removeAttribute("data-spicetify-panel-active");
+		restoreOwnedStyles(activeTopContainer);
+		restoreOwnedStyles(activeSidebar);
+		activeTopContainer = undefined;
+		activeSidebar = undefined;
+	};
+
+	const placeActiveHost = (): boolean => {
+		if (!active || !activeHost) return false;
+		const sidebar = options.document.querySelector<HTMLElement>(".Root__right-sidebar");
+		const topContainer = options.document.querySelector<HTMLElement>(".Root__top-container");
+		if (!sidebar || !topContainer) return false;
+
+		if (activeSidebar !== sidebar) {
+			restoreNative();
+			restoreOwnedStyles(activeSidebar);
+			activeSidebar = sidebar;
+			observeSidebar(sidebar);
+		}
+		if (activeHost.parentElement !== sidebar) sidebar.prepend(activeHost);
+		if (activeTopContainer !== topContainer) {
+			activeTopContainer?.removeAttribute("data-spicetify-panel-active");
+			restoreOwnedStyles(activeTopContainer);
+			activeTopContainer = topContainer;
+		}
+		topContainer.dataset.spicetifyPanelActive = "";
+		const trailingTracks = gridTracks(options.window.getComputedStyle(topContainer).gridTemplateColumns).slice(3);
+		const trailingWidth = trailingTracks.reduce(
+			(total, track) => total + (track.endsWith("px") ? Number.parseFloat(track) || 0 : 0),
+			0,
+		);
+		setOwnedStyle(topContainer, "--spicetify-panel-requested-width", `${panelWidth(active.panel)}px`);
+		setOwnedStyle(topContainer, "--spicetify-panel-trailing-width", `${trailingWidth}px`);
+		setOwnedStyle(
+			topContainer,
+			"grid-template-columns",
+			["auto", "minmax(0, 1fr)", "var(--spicetify-panel-width)", ...trailingTracks].join(" "),
+		);
+		setOwnedStyle(sidebar, "width", "var(--spicetify-panel-width)");
+		setOwnedStyle(sidebar, "min-width", "var(--spicetify-panel-width)");
+		suspendNative(sidebar);
+		return true;
+	};
+
+	const closeActive = (restoreFocus: boolean) => {
+		const closing = active;
+		if (!closing) return;
+		active = undefined;
+		shellObserver?.disconnect();
+		shellObserver = undefined;
+		sidebarObserver?.disconnect();
+		sidebarObserver = undefined;
+		safely("unmount", unmount);
+		unmount = undefined;
+		activeHost?.remove();
+		activeHost = undefined;
+		restoreNative();
+		clearLayout();
+		safely("onClose", closing.panel.onClose);
+		notify(closing, false);
+		if (restoreFocus) {
+			if (returnFocus?.isConnected) returnFocus.focus();
+			returnFocus = undefined;
+		}
+	};
+
+	const open = (state: RegistrationState<Content>) => {
+		if (disposed || state.disposed) return;
+		if (active === state) return;
+		const replacing = !!active;
+		if (replacing) closeActive(false);
+		const focused = options.document.activeElement;
+		if (!replacing) returnFocus = focused instanceof HTMLElement ? focused : undefined;
+		active = state;
+		activeHost = options.document.createElement("section");
+		activeHost.className = "spicetify-panel-host";
+		activeHost.dataset.panelId = state.panel.id;
+		activeHost.setAttribute("role", "complementary");
+		activeHost.setAttribute("aria-label", state.panel.label);
+		activeHost.tabIndex = -1;
+		try {
+			unmount = options.mount(activeHost, state.panel, () => transition(() => closeActive(true)));
+		} catch (error) {
+			active = undefined;
+			activeHost.remove();
+			activeHost = undefined;
+			if (returnFocus?.isConnected) returnFocus.focus();
+			returnFocus = undefined;
+			throw error;
+		}
+		placeActiveHost();
+		shellObserver = new Observer(() => {
+			if (activeHost?.isConnected && activeSidebar?.isConnected && activeTopContainer?.isConnected) return;
+			placeActiveHost();
+		});
+		if (options.document.body) shellObserver.observe(options.document.body, { childList: true, subtree: true });
+		safely("onOpen", state.panel.onOpen);
+		notify(state, true);
+		activeHost.focus();
+	};
+
+	const onKeyDown = (event: KeyboardEvent) => {
+		if (event.key !== "Escape" || event.defaultPrevented || !active) return;
+		if (
+			options.document.querySelector(
+				".spicetify-popover, .spicetify-scrim, .spicetify-root-children [role='dialog']",
+			)
+		)
+			return;
+		event.preventDefault();
+		transition(() => closeActive(true));
+	};
+	options.document.addEventListener("keydown", onKeyDown);
+
+	const register = (panel: PanelRegistration<Content>): PanelController => {
+		if (disposed) throw new Error("[stdlib] panel coordinator is disposed");
+		if (!panel.id.trim()) throw new Error("[stdlib] panel id must not be empty");
+		if (!panel.label.trim()) throw new Error("[stdlib] panel label must not be empty");
+		validatePanelWidth(panel.width);
+		if (registrations.has(panel.id)) throw new Error(`[stdlib] duplicate panel id: ${panel.id}`);
+		const state: RegistrationState<Content> = { panel, disposed: false, listeners: new Set() };
+		registrations.set(panel.id, state);
+
+		return {
+			open: () => {
+				if (disposed || state.disposed) throw new Error(`[stdlib] panel "${state.panel.id}" is disposed`);
+				transition(() => open(state));
+			},
+			close: () => {
+				transition(() => {
+					if (active === state) closeActive(true);
+				});
+			},
+			toggle: () => {
+				if (disposed || state.disposed) throw new Error(`[stdlib] panel "${state.panel.id}" is disposed`);
+				transition(() => {
+					if (active === state) closeActive(true);
+					else open(state);
+				});
+			},
+			isOpen: () => active === state,
+			subscribe(listener) {
+				if (state.disposed) throw new Error(`[stdlib] panel "${state.panel.id}" is disposed`);
+				state.listeners.add(listener);
+				safely("subscriber", () => listener(active === state));
+				return () => state.listeners.delete(listener);
+			},
+			dispose() {
+				if (state.disposed) return;
+				state.disposed = true;
+				transition(() => {
+					if (active === state) closeActive(true);
+					state.listeners.clear();
+					registrations.delete(panel.id);
+				});
+			},
+		};
+	};
+
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		transition(() => {
+			closeActive(false);
+			returnFocus = undefined;
+			for (const state of registrations.values()) {
+				state.disposed = true;
+				state.listeners.clear();
+			}
+			registrations.clear();
+			options.document.removeEventListener("keydown", onKeyDown);
+		});
+	};
+
+	return { register, dispose } satisfies PanelCoordinator<Content>;
+}

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

@@ -1,168 +1,80 @@
 /*
  * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-import { transformer } from "../../mixin.ts";
-
-import type { createMachine as createMachineT } from "npm:xstate";
+import { React, ReactDOM } from "../expose/React.ts";
+import { createItemBoundary } from "./mount.ts";
 import { Registry } from "./registry.ts";
-
-export type StateMachine = ReturnType<typeof createMachineT>;
-export let Machine: StateMachine;
-
-const registry = new (class extends Registry<React.ReactNode> {
-	private static NodeNash = Symbol.for("NodeHash");
-
-	getHash(value: React.ReactNode) {
-		if (!this.has(value)) {
-			return null;
-		}
-		// @ts-ignore
-		const hash = value[this.constructor.NodeNash];
-		const state = `bespoke_${hash}`;
-		const event = `bespoke_${hash}_button_click`;
-		return { state, event };
-	}
-
-	override add(value: React.ReactNode, onEntry?: any, onExit?: any): this {
-		const hash = crypto.randomUUID();
-		// @ts-ignore
-		value[this.constructor.NodeNash] = hash;
-		const state = `bespoke_${hash}`;
-		const event = `bespoke_${hash}_button_click`;
-
-		stateToNode.set(state, value);
-
-		ON[event] = {
-			target: state,
-		};
-
-		STATES[state] = {
-			on: Object.setPrototypeOf(
-				{
-					[event]: {
-						target: "disabled",
+import {
+	createPanelCoordinator,
+	type PanelController,
+	type PanelCoordinator,
+	type PanelRegistration,
+} from "./panel-logic.ts";
+
+export type { PanelController, PanelRegistration, PanelWidth } from "./panel-logic.ts";
+
+const mountReactPanel = (host: HTMLElement, panel: PanelRegistration<React.ReactNode>, close: () => void) => {
+	const root = ReactDOM.createRoot(host);
+	const PanelBoundary = createItemBoundary(React, "panel") as unknown as React.ComponentType<{
+		children?: React.ReactNode;
+	}>;
+	const PanelContent = () => React.createElement("div", { className: "spicetify-panel-content" }, panel.render());
+	const PanelSurface = () =>
+		React.createElement(
+			React.Fragment,
+			null,
+			React.createElement(
+				"header",
+				{ className: "spicetify-panel-header" },
+				React.createElement("h2", { className: "spicetify-panel-title" }, panel.label),
+				React.createElement(
+					"button",
+					{
+						className: "spicetify-panel-close spicetify-button-circle",
+						"aria-label": `Close ${panel.label}`,
+						onClick: close,
 					},
-				},
-				ON,
+					"×",
+				),
 			),
-		};
-
-		if (onEntry) {
-			const entry = `bespoke_${hash}_entry`;
-			STATES[state].entry = [entry];
-			ACTIONS[entry] = onEntry;
-		}
-		if (onExit) {
-			const exit = `bespoke_${hash}_exit`;
-			Machine.config.states![state].exit = [exit];
-			ACTIONS[exit] = onExit;
-		}
+			React.createElement(PanelBoundary, null, React.createElement(PanelContent)),
+		);
+	root.render(React.createElement(PanelSurface));
+	return () => root.unmount();
+};
 
-		return super.add(value);
-	}
+const panelCoordinatorKey = Symbol.for("spicetify.stdlib.panel-coordinator");
+const shared = globalThis as typeof globalThis & Record<symbol, unknown>;
+const previousCoordinator = shared[panelCoordinatorKey] as PanelCoordinator<React.ReactNode> | undefined;
+previousCoordinator?.dispose();
 
-	override delete(item: React.ReactNode): boolean {
-		// @ts-ignore
-		const hash = item[this.constructor.NodeNash];
-		const state = `bespoke_${hash}`;
-		const event = `bespoke_${hash}_button_click`;
+export const panelCoordinator = createPanelCoordinator<React.ReactNode>({
+	document,
+	window,
+	mount: mountReactPanel,
+});
+shared[panelCoordinatorKey] = panelCoordinator;
 
-		stateToNode.delete(state);
+class PanelRegistry extends Registry<PanelRegistration<React.ReactNode>> {
+	private controllers = new Map<PanelRegistration<React.ReactNode>, PanelController>();
 
-		delete ON[event];
-		return super.delete(item);
+	override add(panel: PanelRegistration<React.ReactNode>): this {
+		this.controllers.set(panel, panelCoordinator.register(panel));
+		return super.add(panel);
 	}
-})();
-export default registry;
-
-const stateToNode = new Map<string, React.ReactNode>();
-
-declare global {
-	var __renderPanel: any;
-}
 
-globalThis.__renderPanel = (state: string) => {
-	if (!state.startsWith("bespoke_")) {
-		return null;
+	override delete(panel: PanelRegistration<React.ReactNode>): boolean {
+		this.controllers.get(panel)?.dispose();
+		this.controllers.delete(panel);
+		return super.delete(panel);
 	}
 
-	return stateToNode.get(state);
-};
-
-let ON: Record<string, any> = {};
-let STATES: Record<string, any> = {};
-let ACTIONS: Record<string, any> = {};
-
-transformer(
-	(emit) => (str) => {
-		emit();
-
-		str = str.replace(/(=\(0,[a-zA-Z_\$][\w\$]*\.[a-zA-Z_\$][\w\$]*\)\(\{id:"RightPanelState)/, "=__Machine$1");
-		Object.defineProperty(globalThis, "__Machine", {
-			set: ($: StateMachine) => {
-				Machine = $;
-
-				queueMicrotask(() => {
-					ON = {
-						...ON,
-						...Machine.config.states!.disabled.on,
-						panel_close_click: [
-							{
-								target: "disabled",
-							},
-						],
-					};
-					delete ON.playback_autoplay_context_changed;
-
-					for (const [k, v] of Object.entries(Machine.config.states! as Record<string, any>)) {
-						if (k === "puffin_activation") {
-							continue;
-						}
-						v.on = new Proxy(v.on!, {
-							get(target, p, _receiver) {
-								// @ts-ignore
-								if (p.startsWith("bespoke_")) {
-									// @ts-ignore
-									return ON[p];
-								}
-								// @ts-ignore
-								return target[p];
-							},
-						});
-					}
-
-					Object.setPrototypeOf(Machine.config.states!, STATES);
-
-					Machine._options.actions = ACTIONS;
-				});
-			},
-			get: () => Machine,
-		});
-
-		// ! HACKY ALERT
-		str = str.replace(
-			/(case [a-zA-Z_\$][\w\$]*\.[a-zA-Z_\$][\w\$]*\.Disabled:return!0;default:)/,
-			"$1return true;",
-		);
-
-		return str;
-	},
-	{
-		glob: /^\/xpui\.js/,
-	},
-);
-
-transformer(
-	(emit) => (str) => {
-		emit();
-
-		str = str.replace(/(\(([a-zA-Z_\$][\w\$]*),"PanelSection".+?children:\[?)/, "$1__renderPanel($2),");
+	controller(panel: PanelRegistration<React.ReactNode>): PanelController | undefined {
+		return this.controllers.get(panel);
+	}
+}
 
-		return str;
-	},
-	{
-		glob: /^\/dwp\-panel\-section\.js/,
-	},
-);
+export default new PanelRegistry();

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

@@ -63,7 +63,7 @@ export type PlaybarButtonProps = {
 	isActiveNoIndicator?: boolean;
 	disabled?: boolean;
 	icon?: string;
-	onClick: () => void;
+	onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
 	/** Position within the module-button group; lower renders earlier. Read by the mount sorter. */
 	order?: number;
 };

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

@@ -97,11 +97,12 @@ mountRegistryAnchor({
 		const route = items.find((item: any) => {
 			const path = item?.props?.path;
 			return typeof path === "string" && matchRoute(pathname, path);
-		}) as { props: { element?: unknown; children?: unknown } } | undefined;
+		}) as { props: { path: string; element?: unknown; children?: unknown } } | undefined;
 		if (!route) return null;
 		return (React as any).createElement(
 			"div",
 			{
+				key: route.props.path,
 				className: "spicetify-route-page",
 				style: {
 					position: "absolute",

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

@@ -8,9 +8,9 @@ import { SettingsSection } from "../../lib/primitives.tsx";
 import { Registry } from "./registry.ts";
 import settingsSection from "./settingsSection.ts";
 
-// Rows from every module, rendered together under one "Spicetify" section
-// in the client's settings page. A module with a single setting registers a
-// row here instead of claiming a whole section (or a profile-menu slot) of
+// Rows from every module, rendered together under one "General" section on
+// the standalone Spicetify Settings page. A module with a single setting
+// registers a row here instead of claiming a whole section (or a menu slot) of
 // its own; SettingsToggleRow (lib/primitives.tsx) is the one-boolean case.
 const listeners = new Set<() => void>();
 
@@ -38,7 +38,7 @@ const SpicetifyGroup = () => {
 	const rows = registry.all();
 	if (rows.length === 0) return null;
 	return (
-		<SettingsSection title="Spicetify">
+		<SettingsSection title="General">
 			{rows.map((row, i) => (
 				<React.Fragment key={i}>{row}</React.Fragment>
 			))}