@spicetify/kit 0.1.0

package/vendor/stdlib/lib/primitives.tsx

@@ -0,0 +1,314 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The React tier of the component kit: the reusable UI primitives, the
+ * same Spotify-look chrome as the vanilla kit (lib/primitives-vanilla.ts) but as React
+ * components for module UI that already renders inside a React tree
+ * (routes, registers, modals). Both tiers apply the shared class contract
+ * (primitives-classes.ts) so they can never drift.
+ *
+ * Deep-import at runtime: `import { Button } from
+ * "/modules/stdlib/lib/primitives.js"`. This is not in the mod.ts barrel
+ * to avoid colliding with the vanilla kit's identical export names; a
+ * module uses one tier. Requires the client React instance, so only
+ * modules that declare stdlib as a dependency should use it (the vanilla
+ * kit is the React-free choice for standalone surfaces).
+ */
+
+import { React, ReactDOM } from "../src/expose/React.ts";
+import {
+	activateToggleOnKeyDown,
+	TOGGLE_CLASSES,
+	SETTINGS_ROW_CLASS,
+	SETTINGS_ROW_CONTROL_CLASS,
+	SETTINGS_ROW_LABEL_CLASS,
+	SETTINGS_SECTION_CLASS,
+	badgeClass,
+	buttonClass,
+	type BadgeTone,
+	type ButtonVariant,
+	CARD_CLASS,
+	chipClass,
+	DIALOG_BODY_CLASS,
+	DIALOG_CLASS,
+	DIALOG_HEADER_CLASS,
+	ICON_BUTTON_CLASS,
+	MENU_ITEM_CLASS,
+	SCRIM_CLASS,
+	SEARCHBAR_CLASS,
+	SELECT_CLASS,
+} from "./primitives-classes.ts";
+
+export type { BadgeTone, ButtonVariant } from "./primitives-classes.ts";
+
+// ---------- buttons ----------
+
+export const Button: React.FC<{
+	variant?: ButtonVariant;
+	disabled?: boolean;
+	onClick?: () => void;
+	children: React.ReactNode;
+}> = (props) => (
+	<button type="button" className={buttonClass(props.variant)} disabled={props.disabled} onClick={props.onClick}>
+		{props.children}
+	</button>
+);
+
+// The circular icon button Spotify uses for modal close (Credits, etc).
+export const IconButton: React.FC<{
+	ariaLabel: string;
+	disabled?: boolean;
+	onClick?: () => void;
+	children: React.ReactNode;
+}> = (props) => (
+	<button
+		type="button"
+		className={ICON_BUTTON_CLASS}
+		aria-label={props.ariaLabel}
+		disabled={props.disabled}
+		onClick={props.onClick}
+	>
+		{props.children}
+	</button>
+);
+
+// ---------- inputs ----------
+
+export function Select<T extends string>(props: {
+	options: ReadonlyArray<{ value: T; label: string }>;
+	value: T;
+	onChange: (value: T) => void;
+}): React.ReactElement {
+	return (
+		<select className={SELECT_CLASS} value={props.value} onChange={(e) => props.onChange(e.target.value as T)}>
+			{props.options.map((option) => (
+				<option key={option.value} value={option.value}>
+					{option.label}
+				</option>
+			))}
+		</select>
+	);
+}
+
+export const TextInput: React.FC<{
+	placeholder?: string;
+	value?: string;
+	disabled?: boolean;
+	onInput?: (value: string) => void;
+}> = (props) => (
+	<input
+		type="text"
+		className={SEARCHBAR_CLASS}
+		placeholder={props.placeholder}
+		value={props.value}
+		disabled={props.disabled}
+		onChange={(e) => props.onInput?.(e.target.value)}
+	/>
+);
+
+export const Textarea: React.FC<{
+	placeholder?: string;
+	value?: string;
+	onInput?: (value: string) => void;
+}> = (props) => (
+	<textarea placeholder={props.placeholder} value={props.value} onChange={(e) => props.onInput?.(e.target.value)} />
+);
+
+// ---------- badges, chips, cards ----------
+
+export const Badge: React.FC<{ tone?: BadgeTone; children: React.ReactNode }> = (props) => (
+	<span className={badgeClass(props.tone)}>{props.children}</span>
+);
+
+export const Chip: React.FC<{ active: boolean; onClick?: () => void; children: React.ReactNode }> = (props) => (
+	<button type="button" className={chipClass(props.active)} onClick={props.onClick}>
+		{props.children}
+	</button>
+);
+
+// A plain elevated container; slot layout is the consumer's own concern.
+export const Card: React.FC<{ children: React.ReactNode }> = (props) => (
+	<article className={CARD_CLASS}>{props.children}</article>
+);
+
+// ---------- settings ----------
+
+// Native-looking settings chrome for the `settingsSection` register. These
+// render the client's own section/row structure rather than capturing its
+// components: the settings route is a lazily loaded chunk, and the loader
+// does not source-transform those, so a capture there never resolves.
+export const SettingsSection: React.FC<{ title?: React.ReactNode; children: React.ReactNode }> = (props) => (
+	<div className={SETTINGS_SECTION_CLASS}>
+		{props.title === undefined ? null : <h2>{props.title}</h2>}
+		{props.children}
+	</div>
+);
+
+// One labelled row. `label` fills the client's first column and `children`
+// the control column, so a toggle or select lines up with the native rows
+// above and below it.
+export const SettingsRow: React.FC<{ label: React.ReactNode; htmlFor?: string; children: React.ReactNode }> = (
+	props,
+) => (
+	<div className={SETTINGS_ROW_CLASS}>
+		<div className={SETTINGS_ROW_LABEL_CLASS}>
+			{props.htmlFor === undefined ? props.label : <label htmlFor={props.htmlFor}>{props.label}</label>}
+		</div>
+		<div className={SETTINGS_ROW_CONTROL_CLASS}>{props.children}</div>
+	</div>
+);
+
+// The client's own switch structure around a native checkbox. Its semantic
+// classes are recreated by the CLI css-map, so Spotify and themes style this
+// exactly like the adjacent settings controls.
+export const Toggle: React.FC<{
+	id?: string;
+	ariaLabel?: string;
+	value: boolean;
+	onChange: (value: boolean) => void;
+}> = (props) => (
+	<label className={TOGGLE_CLASSES.wrapper}>
+		<input
+			type="checkbox"
+			className={TOGGLE_CLASSES.input}
+			id={props.id}
+			aria-label={props.ariaLabel}
+			checked={props.value}
+			onKeyDown={activateToggleOnKeyDown}
+			onChange={(e) => props.onChange((e.target as HTMLInputElement).checked)}
+		/>
+		<span className={TOGGLE_CLASSES.indicatorWrapper} aria-hidden="true">
+			<span className={TOGGLE_CLASSES.indicator} />
+		</span>
+	</label>
+);
+
+// The "module with one boolean setting" pattern as a single row for the
+// `settingsRow` register. `getValue` is read lazily on every mount so
+// reopening settings always reflects the current state; the element itself
+// is created once at module load, so a plain value prop would go stale.
+export const SettingsToggleRow: React.FC<{
+	label: React.ReactNode;
+	getValue: () => boolean;
+	onChange: (value: boolean) => void;
+}> = (props) => {
+	const id = React.useId();
+	const [value, setValue] = React.useState(props.getValue);
+	return (
+		<SettingsRow label={props.label} htmlFor={id}>
+			<Toggle
+				id={id}
+				value={value}
+				onChange={(v) => {
+					setValue(v);
+					props.onChange(v);
+				}}
+			/>
+		</SettingsRow>
+	);
+};
+
+// ---------- context-menu item ----------
+
+// A row for one of Spotify's context menus — register it through the
+// "menu" register. It owns the native context-menu class so module code
+// gets Spotify styling without ever naming a client class; pass `className`
+// only for a module-specific hook on top of the native look.
+export const MenuItem: React.FC<{
+	onClick?: () => void;
+	className?: string;
+	children: React.ReactNode;
+}> = (props) => (
+	<button
+		type="button"
+		role="menuitem"
+		className={props.className ? `${MENU_ITEM_CLASS} ${props.className}` : MENU_ITEM_CLASS}
+		onClick={props.onClick}
+	>
+		<span>{props.children}</span>
+	</button>
+);
+
+// ---------- two-step confirm ----------
+
+// The arm-then-confirm pattern: the first click swaps the label and arms
+// a revert timer; a second click within the window confirms.
+export const ConfirmButton: React.FC<{
+	label: string;
+	confirmLabel: string;
+	onConfirm: () => void;
+	variant?: ButtonVariant;
+	windowMs?: number;
+}> = (props) => {
+	const [armed, setArmed] = React.useState(false);
+	const timer = React.useRef<ReturnType<typeof setTimeout>>();
+	React.useEffect(() => () => clearTimeout(timer.current), []);
+	return (
+		<button
+			type="button"
+			className={buttonClass(props.variant)}
+			onClick={() => {
+				if (armed) {
+					clearTimeout(timer.current);
+					setArmed(false);
+					props.onConfirm();
+					return;
+				}
+				setArmed(true);
+				timer.current = setTimeout(() => setArmed(false), props.windowMs ?? 4000);
+			}}
+		>
+			{armed ? props.confirmLabel : props.label}
+		</button>
+	);
+};
+
+// ---------- dialog ----------
+
+// Modal chrome: the consumer controls mounting with a conditional render
+// (`{open && <Dialog ... />}`), the idiomatic React equivalent of the
+// vanilla kit's openDialog(). It portals to document.body so the
+// position:fixed scrim anchors to the viewport — a fixed element inside a
+// transformed ancestor (the norm for Spotify's scroll containers) would
+// otherwise be clipped/offset to that ancestor. The backdrop and the ×
+// button both call onClose.
+export const Dialog: React.FC<{ title: string; onClose: () => void; children: React.ReactNode }> = (props) => {
+	const { onClose } = props;
+	// Escape closes the dialog, matching every native modal. A capturing
+	// document listener catches the key wherever focus sits (the client's own
+	// components steal focus), and the client's shortcut handlers do not see it.
+	React.useEffect(() => {
+		const onKey = (e: KeyboardEvent) => {
+			if (e.key === "Escape") {
+				e.preventDefault();
+				e.stopPropagation();
+				onClose();
+			}
+		};
+		document.addEventListener("keydown", onKey, true);
+		return () => document.removeEventListener("keydown", onKey, true);
+	}, [onClose]);
+
+	return ReactDOM.createPortal(
+		<div
+			className={SCRIM_CLASS}
+			onClick={(e) => {
+				if (e.target === e.currentTarget) onClose();
+			}}
+		>
+			<div className={DIALOG_CLASS} role="dialog" aria-modal="true" aria-label={props.title}>
+				<div className={DIALOG_HEADER_CLASS}>
+					<h2>{props.title}</h2>
+					<IconButton ariaLabel="Close" onClick={onClose}>
+						×
+					</IconButton>
+				</div>
+				<div className={DIALOG_BODY_CLASS}>{props.children}</div>
+			</div>
+		</div>,
+		document.body,
+	);
+};

package/vendor/stdlib/load.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { startEventHandlers } from "./src/events.js";
+import { installPlaybarCompat } from "./src/playbar-compat.js";
+
+export default async function (_ctx: { spotifyVersion: string }) {
+	const cancelEventHandlers = startEventHandlers();
+	const uninstallPlaybarCompat = installPlaybarCompat();
+	return () => {
+		uninstallPlaybarCompat();
+		cancelEventHandlers();
+	};
+}

package/vendor/stdlib/metadata.json

@@ -0,0 +1,18 @@
+{
+	"name": "stdlib",
+	"kind": "lib",
+	"hidden": true,
+	"preview": "./assets/PREVIEW.png",
+	"version": "1.5.0",
+	"compat": ["0.3.0"],
+	"authors": ["spicetify", "Delusoire"],
+	"description": "The standard library",
+	"readme": "./assets/README.md",
+	"entries": {
+		"js": "index.js",
+		"css": "index.css"
+	},
+	"hasMixins": true,
+	"dependencies": [],
+	"tree": true
+}

package/vendor/stdlib/mixin.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// allows us to patch webpack module exports directly
+const nativeObjectDefineProperty = Object.defineProperty;
+Object.defineProperty = function (obj, prop, descriptor) {
+	if (prop !== "prototype" && descriptor) descriptor.configurable ??= true;
+	return nativeObjectDefineProperty(obj, prop, descriptor);
+};
+
+// Shape of the loader-provided source transformer: registers a rewrite
+// over client bundles matched by glob. emit() reports the needle matched
+// (optionally with a captured value the returned promise resolves with).
+export type Transformer = <T = unknown>(
+	fn: (emit: (value?: T) => void) => (str: string) => string,
+	opts?: { glob?: RegExp; wait?: boolean; noAwait?: boolean },
+) => Promise<T>;
+
+export let transformer: Transformer;
+
+export default async function (t: Transformer, _ctx: { spotifyVersion: string }) {
+	transformer = t;
+	await Promise.all([
+		import("./src/expose/index.js"),
+		import("./src/registers/index.js"),
+		import("./src/events.mix.js"),
+		import("./src/wpunpk.mix.js"),
+	]);
+}

package/vendor/stdlib/mod.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// Runtime context the v3 loader passes into preload/load.
+export interface ModuleRuntimeContext {
+	spotifyVersion: string;
+	identifier: string;
+	defer: (fn: () => void | Promise<void>) => void;
+}
+
+export * from "./src/registers/index.ts";
+export * from "./src/client.ts";
+export * from "./src/events.ts";
+// Vanilla component kit for module-owned DOM (React-free).
+export * from "./lib/primitives-vanilla.ts";
+export * from "./src/storage.ts";
+export * from "./src/wpunpk.ts";
+export * from "./src/logger.ts";
+
+// Public barrel: everything dependent modules are allowed to deep-import.
+// Import from /modules/stdlib/mod.js at runtime; nothing else is public.
+export * from "./src/webpack/misc.xpui.ts";
+export * from "./src/webpack/ComponentLibrary.xpui.ts";
+export * from "./src/webpack/ReactComponents.xpui.ts";

package/vendor/stdlib/src/chunks.d.ts

@@ -0,0 +1,10 @@
+// Ambient declaration for the chunk-promise table the modular loader
+// maintains on globalThis; keyed by chunk path plus aliases like "xpui".
+declare global {
+	var CHUNKS: Record<
+		string,
+		{ promise: Promise<unknown>; resolve?: (value?: unknown) => void; reject?: (reason?: unknown) => void }
+	>;
+}
+
+export {};

package/vendor/stdlib/src/client.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright (C) 2026 spicetify
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The stable module-facing boundary around the wrapper runtime.
+ *
+ * Keep ambient `Spicetify` access in this adapter. Modules import `client`
+ * instead, which gives stdlib one place to replace or harden a capability as
+ * Spotify changes. Getters are intentionally lazy: some surfaces, notably the
+ * modular loader API, are attached after the client has started loading
+ * modules.
+ */
+
+type SpicetifyRuntime = typeof Spicetify;
+
+export type PlayerState = Spicetify.PlayerState;
+
+export interface ClientCapabilities {
+	readonly player: typeof Spicetify.Player;
+	readonly platform: typeof Spicetify.Platform;
+	readonly storage: typeof Spicetify.LocalStorage;
+	readonly uri: typeof Spicetify.URI;
+	readonly cosmos: typeof Spicetify.CosmosAsync;
+	readonly corsProxy: typeof Spicetify.CORSProxy;
+	readonly graphQL: typeof Spicetify.GraphQL;
+	readonly locale: typeof Spicetify.Locale;
+	readonly icons: typeof Spicetify.SVGIcons;
+	readonly keyboard: typeof Spicetify.Keyboard;
+	readonly mousetrap: typeof Spicetify.Mousetrap;
+	readonly contextMenu: typeof Spicetify.ContextMenu;
+	readonly popupModal: typeof Spicetify.PopupModal;
+	readonly config: typeof Spicetify.Config;
+	readonly modules: typeof Spicetify.Modules;
+	readonly react: typeof Spicetify.React;
+	readonly reactDOM: typeof Spicetify.ReactDOM;
+	readonly tippy: typeof Spicetify.Tippy;
+	readonly tippyProps: typeof Spicetify.TippyProps;
+	readonly playbar: typeof Spicetify.Playbar;
+	readonly notify: typeof Spicetify.showNotification;
+}
+
+const runtime = (): SpicetifyRuntime => {
+	const value = (globalThis as unknown as { Spicetify?: SpicetifyRuntime }).Spicetify;
+	if (!value) throw new Error("Spicetify client runtime is unavailable");
+	return value;
+};
+
+export const client: ClientCapabilities = {
+	get player() {
+		return runtime().Player;
+	},
+	get platform() {
+		return runtime().Platform;
+	},
+	get storage() {
+		return runtime().LocalStorage;
+	},
+	get uri() {
+		return runtime().URI;
+	},
+	get cosmos() {
+		return runtime().CosmosAsync;
+	},
+	get corsProxy() {
+		return runtime().CORSProxy;
+	},
+	get graphQL() {
+		return runtime().GraphQL;
+	},
+	get locale() {
+		return runtime().Locale;
+	},
+	get icons() {
+		return runtime().SVGIcons;
+	},
+	get keyboard() {
+		return runtime().Keyboard;
+	},
+	get mousetrap() {
+		return runtime().Mousetrap;
+	},
+	get contextMenu() {
+		return runtime().ContextMenu;
+	},
+	get popupModal() {
+		return runtime().PopupModal;
+	},
+	get config() {
+		return runtime().Config;
+	},
+	get modules() {
+		return runtime().Modules;
+	},
+	get react() {
+		return runtime().React;
+	},
+	get reactDOM() {
+		return runtime().ReactDOM;
+	},
+	get tippy() {
+		return runtime().Tippy;
+	},
+	get tippyProps() {
+		return runtime().TippyProps;
+	},
+	get playbar() {
+		return runtime().Playbar;
+	},
+	get notify() {
+		return runtime().showNotification;
+	},
+};

package/vendor/stdlib/src/createIconComponent.tsx

@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { React } from "./expose/React.ts";
+import { UI } from "./webpack/ComponentLibrary.ts";
+
+export const createIconComponent = ({
+	icon,
+	iconSize = 16,
+	realIconSize = iconSize,
+	...props
+}: {
+	[k: string]: any;
+	icon: string;
+	realIconSize?: number;
+	iconSize?: number;
+}) => {
+	return (
+		<UI.Icon
+			autoMirror={false}
+			iconSize={realIconSize}
+			viewBox={`0 0 ${iconSize} ${iconSize}`}
+			dangerouslySetInnerHTML={{ __html: icon }}
+			{...props}
+		/>
+	);
+};

package/vendor/stdlib/src/events.mix.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { postWebpackRequireHooks } from "./wpunpk.mix.ts";
+
+import { BehaviorSubject, Subject } from "../deps.ts";
+
+function createGlobalThisShadow() {
+	const globalThisShadow = {} as typeof globalThis;
+
+	Object.setPrototypeOf(globalThisShadow, globalThis);
+
+	Object.defineProperty(globalThisShadow, "self", { value: globalThisShadow });
+	Object.defineProperty(globalThisShadow, "globalThis", { value: globalThisShadow });
+	Object.defineProperty(globalThisShadow, "window", { value: globalThisShadow });
+
+	return globalThisShadow;
+}
+
+type CosmosRequest = { uri: string; method: string; body: string };
+
+const CosmosRequestSubject = new Subject<CosmosRequest>();
+export const UpdateTitlebarSubject = new BehaviorSubject<number>(-1);
+
+postWebpackRequireHooks.push(($) => {
+	const globalThisShadow = ($.g = createGlobalThisShadow());
+
+	const $sendCosmosRequest = globalThis.sendCosmosRequest;
+	Object.defineProperty(globalThisShadow, "sendCosmosRequest", {
+		value: function ($: any) {
+			const request = JSON.parse($.request);
+
+			CosmosRequestSubject.next(request);
+
+			return $sendCosmosRequest($);
+		},
+	});
+});
+
+const controlMessageListener = (request: CosmosRequest) => {
+	const { uri, method } = request;
+
+	if (uri === "sp://messages/v1/container/control" && method === "POST") {
+		const body = JSON.parse(request.body);
+		const { type, height } = body;
+
+		if (type === "update_titlebar") {
+			UpdateTitlebarSubject.next(height);
+		}
+	}
+};
+
+CosmosRequestSubject.subscribe(controlMessageListener);

package/vendor/stdlib/src/events.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { Platform } from "./expose/Platform.ts";
+
+import { BehaviorSubject } from "../deps.ts";
+import { UpdateTitlebarSubject } from "./events.mix.ts";
+
+const newEventBus = () => {
+	const PlayerAPI = Platform.getPlayerAPI();
+	const History = Platform.getHistory();
+
+	const playerState = PlayerAPI.getState();
+	return {
+		Player: {
+			state_updated: new BehaviorSubject(playerState),
+			status_changed: new BehaviorSubject(playerState),
+			song_changed: new BehaviorSubject(playerState),
+		},
+		History: {
+			updated: new BehaviorSubject(History.location),
+		},
+		ControlMessage: {
+			titlebar_updated: new BehaviorSubject<number>(-1),
+		},
+	};
+};
+
+const EventBus = newEventBus();
+export type EventBus = typeof EventBus;
+
+let cachedState: any = {};
+const playerListener = ({ data: state }: any) => {
+	EventBus.Player.state_updated.next(state);
+	if (state?.item?.uri !== cachedState?.item?.uri) EventBus.Player.song_changed.next(state);
+	if (state?.isPaused !== cachedState?.isPaused || state?.isBuffering !== cachedState?.isBuffering) {
+		EventBus.Player.status_changed.next(state);
+	}
+	cachedState = state;
+};
+
+const historyListener = (location) => EventBus.History.updated.next(location);
+
+const updateTitlebarListener = (height: number) => EventBus.ControlMessage.titlebar_updated.next(height);
+
+export function startEventHandlers() {
+	const cancelPlayerListener = Platform.getPlayerAPI().getEvents().addListener("update", playerListener);
+	const cancelHistoryListener = Platform.getHistory().listen(historyListener);
+	const updateTitlebarListenerSubscription = UpdateTitlebarSubject.subscribe(updateTitlebarListener);
+
+	return () => {
+		cancelPlayerListener();
+		cancelHistoryListener();
+		updateTitlebarListenerSubscription.unsubscribe();
+	};
+}