@spicetify/kit 0.1.0

package/vendor/stdlib/deps.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// Prebundled vendor copy (one self-contained file; vendor/rxjs.d.ts carries
+// the types), so stdlib boots without the network. The esm.sh imports this
+// replaces were static, which put esm.sh in every client's boot path and
+// made an offline boot fail the whole module graph. A bare "rxjs" import is
+// no good either: the tree build preserves modules, so it splats the package
+// into dist as dozens of files under the resolver's store path.
+export { BehaviorSubject, Subject, Subscription } from "./vendor/rxjs.js";
+
+// The one remaining lodash consumer is startCase; a local implementation
+// beats shipping lodash for it. Splits camelCase and non-alphanumeric
+// boundaries, capitalizes each word ("miserly-magenta" -> "Miserly Magenta").
+export const startCase = (value: string): string =>
+	value
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.split(/[^a-zA-Z0-9]+/)
+		.filter(Boolean)
+		.map((word) => word[0].toUpperCase() + word.slice(1))
+		.join(" ");

package/vendor/stdlib/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import type { Transformer } from "./mixin.ts";
+
+// Lifecycle contract for the spicetify v3 modular loader (no /hooks).
+export async function mixin(transformer: Transformer, ctx: { spotifyVersion: string }) {
+	return (await import("./mixin.js")).default(transformer, ctx);
+}
+
+// The loader runs module lifecycles sequentially in dependency order. Holding
+// stdlib's preload until its webpack analysis settles prevents every later UI
+// module from observing half-populated React/component exports.
+export async function preload() {
+	const { waitForWebpackCapture } = await import("./src/webpack/index.js");
+	await waitForWebpackCapture();
+}
+
+export async function load(ctx: { spotifyVersion: string }) {
+	return (await import("./load.js")).default(ctx);
+}

package/vendor/stdlib/lib/modal.tsx

@@ -0,0 +1,128 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { React } from "../src/expose/React.ts";
+import { Locale } from "../src/webpack/misc.ts";
+
+import RootRegistry from "../src/registers/root.ts";
+const [RootChildrenRegistry] = RootRegistry;
+import { createIconComponent } from "../src/createIconComponent.tsx";
+
+let ref: React.ReactElement | undefined = undefined;
+
+export function display({ title, content, isLarge }: { title: string; content: React.ReactElement; isLarge: boolean }) {
+	hide();
+
+	RootChildrenRegistry.add(
+		(ref = (
+			<PopupModal contentLabel={title} children={content} isEmbedWidgetGeneratorOrTrackCreditsModal={isLarge} />
+		)),
+	);
+}
+
+export function hide() {
+	if (ref) {
+		RootChildrenRegistry.delete(ref);
+		ref = undefined;
+	}
+}
+
+interface PopupModalProps {
+	contentLabel: string;
+	children: React.ReactNode;
+	isEmbedWidgetGeneratorOrTrackCreditsModal: boolean;
+}
+
+// Self-contained modal shell: client modal components (GenericModal, UI.*)
+// require the client tree's contexts, which anchors don't have. The shell
+// owns the backdrop and dismissal; the MAP-classed chrome keeps native
+// styling.
+const ModalShell = (props: { contentLabel: string; children: React.ReactNode }) => {
+	React.useEffect(() => {
+		const onKey = (e: KeyboardEvent) => {
+			if (e.key === "Escape") hide();
+		};
+		document.addEventListener("keydown", onKey);
+		return () => document.removeEventListener("keydown", onKey);
+	}, []);
+
+	return (
+		<div
+			role="dialog"
+			aria-label={props.contentLabel}
+			style={{
+				position: "fixed",
+				inset: 0,
+				zIndex: 100,
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "center",
+				background: "rgba(0, 0, 0, 0.7)",
+			}}
+			onClick={(e) => {
+				if (e.target === e.currentTarget) hide();
+			}}
+		>
+			<div
+				style={{
+					background: "var(--spice-card, var(--background-elevated-base, #282828))",
+					color: "var(--spice-text, var(--text-base, #fff))",
+					borderRadius: "8px",
+					maxHeight: "80vh",
+					maxWidth: "90vw",
+					overflow: "auto",
+				}}
+			>
+				{props.children}
+			</div>
+		</div>
+	);
+};
+
+const closeIcon =
+	"<path d='M2.47 2.47a.75.75 0 0 1 1.06 0L8 6.94l4.47-4.47a.75.75 0 1 1 1.06 1.06L9.06 8l4.47 4.47a.75.75 0 1 1-1.06 1.06L8 9.06l-4.47 4.47a.75.75 0 0 1-1.06-1.06L6.94 8 2.47 3.53a.75.75 0 0 1 0-1.06Z'/>";
+
+const PopupModal = (props: PopupModalProps) => {
+	if (props.isEmbedWidgetGeneratorOrTrackCreditsModal) {
+		return (
+			<ModalShell contentLabel={props.contentLabel}>
+				<div className={MAP.modal.widget_generator.container} style={{ overflow: "scroll", width: "60vw" }}>
+					<div className={MAP.modal.widget_generator.header.container}>
+						<h1 className="encore-text encore-text-title-small">{props.contentLabel}</h1>
+						<button className={MAP.modal.widget_generator.header.close} onClick={hide}>
+							{createIconComponent({
+								icon: closeIcon,
+								"aria-label": Locale.get("close"),
+							})}
+						</button>
+					</div>
+					<div className={MAP.modal.widget_generator.content.container}>{props.children}</div>
+				</div>
+			</ModalShell>
+		);
+	}
+
+	return (
+		<ModalShell contentLabel={props.contentLabel}>
+			<div className={MAP.modal.track_credits.container}>
+				<div className={MAP.modal.track_credits.header.container}>
+					<h1 className="encore-text encore-text-title-medium">{props.contentLabel}</h1>
+					<button
+						className={MAP.modal.track_credits.header.close}
+						aria-label={Locale.get("close")}
+						onClick={hide}
+					>
+						{createIconComponent({
+							icon: closeIcon,
+							"aria-label": Locale.get("close"),
+							iconSize: 18,
+						})}
+					</button>
+				</div>
+				<div className={MAP.modal.track_credits.content.container}>{props.children}</div>
+			</div>
+		</ModalShell>
+	);
+};

package/vendor/stdlib/lib/popover.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// Anchored popover: positions content in a floating panel under a trigger
+// element (topbar buttons, playbar buttons, ...) and owns dismissal —
+// click-outside, Escape, and reposition on resize. Content can be a React
+// node (rendered with the client React) or a plain HTMLElement, so vanilla
+// modules can use it without touching React.
+
+import { React, ReactDOM } from "../src/expose/React.ts";
+
+export interface PopoverHandle {
+	close: () => void;
+	host: HTMLElement;
+}
+
+export interface PopoverOptions {
+	anchor: HTMLElement;
+	content: HTMLElement | React.ReactNode;
+	onClose?: () => void;
+	gap?: number;
+}
+
+export function openPopover({ anchor, content, onClose, gap = 8 }: PopoverOptions): PopoverHandle {
+	const host = document.createElement("div");
+	host.className = "spicetify-popover";
+	Object.assign(host.style, {
+		position: "fixed",
+		zIndex: "1000",
+		background: "var(--spice-card, var(--background-elevated-base, #282828))",
+		color: "var(--spice-text, var(--text-base, #fff))",
+		borderRadius: "8px",
+		boxShadow: "0 16px 24px rgba(0, 0, 0, 0.3), 0 6px 8px rgba(0, 0, 0, 0.2)",
+		maxHeight: "80vh",
+		overflow: "auto",
+	});
+
+	const place = () => {
+		const rect = anchor.getBoundingClientRect();
+		host.style.top = `${Math.round(Math.min(rect.bottom + gap, window.innerHeight - 64))}px`;
+		const left = Math.min(Math.max(8, rect.left), Math.max(8, window.innerWidth - host.offsetWidth - 8));
+		host.style.left = `${Math.round(left)}px`;
+	};
+
+	let root: { unmount: () => void } | undefined;
+	if (content instanceof HTMLElement) {
+		host.appendChild(content);
+	} else {
+		const createRoot = (ReactDOM as any).createRoot;
+		root = createRoot(host);
+		(root as any).render(React.createElement(React.Fragment, null, content as any));
+	}
+
+	let closed = false;
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		window.removeEventListener("resize", place);
+		document.removeEventListener("mousedown", onDocDown, true);
+		document.removeEventListener("keydown", onKey, true);
+		root?.unmount();
+		host.remove();
+		onClose?.();
+	};
+	const onDocDown = (e: MouseEvent) => {
+		const target = e.target as Node;
+		if (!host.contains(target) && !anchor.contains(target)) close();
+	};
+	const onKey = (e: KeyboardEvent) => {
+		if (e.key === "Escape") close();
+	};
+
+	document.body.appendChild(host);
+	place();
+	// A second pass once layout has produced the real width, for clamping.
+	requestAnimationFrame(place);
+	window.addEventListener("resize", place);
+	document.addEventListener("mousedown", onDocDown, true);
+	document.addEventListener("keydown", onKey, true);
+
+	return { close, host };
+}

package/vendor/stdlib/lib/primitives-classes.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The single source of truth for the module chrome-class contract. Both
+ * the vanilla kit (ui.ts) and the React primitives (primitives.tsx) apply these,
+ * so the two tiers can never drift on which class means which primitive.
+ * The classes themselves live in stdlib's stylesheet (index.scss).
+ */
+
+export type ButtonVariant = "primary" | "secondary" | "danger";
+export type BadgeTone = "neutral" | "ok" | "bad";
+
+export const buttonClass = (variant: ButtonVariant = "primary"): string =>
+	variant === "primary" ? "spicetify-button" : `spicetify-button spicetify-button--${variant}`;
+
+export const badgeClass = (tone: BadgeTone = "neutral"): string =>
+	tone === "neutral" ? "spicetify-badge" : `spicetify-badge spicetify-badge--${tone}`;
+
+export const chipClass = (active: boolean): string =>
+	active ? "spicetify-chip spicetify-chip--active" : "spicetify-chip";
+
+export const ICON_BUTTON_CLASS = "spicetify-button-circle";
+// A row in one of Spotify's own context menus. Unlike the spicetify-*
+// classes above (ours, styled in index.scss), this is Spotify's stable
+// semantic class — the kit owns it in this one place so module code never
+// has to name a client class to get a native-looking menu item.
+export const MENU_ITEM_CLASS = "main-contextMenu-menuItemButton";
+export const SELECT_CLASS = "spicetify-select";
+export const SEARCHBAR_CLASS = "spicetify-searchbar";
+export const CARD_CLASS = "spicetify-card";
+export const SCRIM_CLASS = "spicetify-scrim";
+export const DIALOG_CLASS = "spicetify-dialog";
+export const DIALOG_HEADER_CLASS = "spicetify-dialog-header";
+export const DIALOG_BODY_CLASS = "spicetify-dialog-body";
+
+// The client's own settings chrome. These names exist because the CLI's
+// css-map recreates them, so a module row is styled by Spotify's own CSS
+// instead of approximating it.
+export const SETTINGS_SECTION_CLASS = "x-settings-section";
+export const SETTINGS_ROW_CLASS = "x-settings-row";
+export const SETTINGS_ROW_LABEL_CLASS = "x-settings-firstColumn";
+export const SETTINGS_ROW_CONTROL_CLASS = "x-settings-secondColumn";
+export const TOGGLE_CLASSES = {
+	wrapper: "x-toggle-wrapper",
+	input: "x-toggle-input",
+	indicatorWrapper: "x-toggle-indicatorWrapper",
+	indicator: "x-toggle-indicator",
+} as const;
+
+/** @deprecated Use TOGGLE_CLASSES with the native switch structure. */
+export const TOGGLE_CLASS = "spicetify-toggle";
+
+export function activateToggleOnKeyDown(event: {
+	key: string;
+	currentTarget: { click: () => void };
+	preventDefault: () => void;
+	stopPropagation: () => void;
+}): void {
+	if (event.key !== " " && event.key !== "Enter") return;
+	event.preventDefault();
+	event.stopPropagation();
+	event.currentTarget.click();
+}

package/vendor/stdlib/lib/primitives-vanilla.ts

@@ -0,0 +1,277 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * A vanilla, React-free component kit for module UIs. Every primitive is
+ * a plain function returning a typed HTMLElement, built on the `h()`
+ * hyperscript, and applies the shared `.spicetify-*` chrome classes from
+ * stdlib's stylesheet. Because it touches nothing but `document`, it is
+ * safe on standalone module surfaces (anchors, body dialogs, popovers)
+ * where the client React instance and client webpack components are
+ * unavailable — the same tier-2 role the chrome classes already fill,
+ * now as named, composable primitives.
+ *
+ * Inside a client React tree, prefer the real client components via
+ * stdlib's ComponentLibrary; this kit is for module-owned DOM.
+ */
+
+import {
+	badgeClass,
+	buttonClass,
+	type BadgeTone,
+	type ButtonVariant,
+	CARD_CLASS,
+	chipClass,
+	DIALOG_BODY_CLASS,
+	DIALOG_CLASS,
+	DIALOG_HEADER_CLASS,
+	ICON_BUTTON_CLASS,
+	SCRIM_CLASS,
+	SEARCHBAR_CLASS,
+	SELECT_CLASS,
+} from "./primitives-classes.ts";
+
+export type { BadgeTone, ButtonVariant } from "./primitives-classes.ts";
+
+// Typed event handlers: only real DOM events are accepted, so a
+// misspelled `onClik` is a type error rather than a silently-attached
+// listener for a "clik" event.
+type EventHandlers = {
+	[E in keyof GlobalEventHandlersEventMap as `on${Capitalize<E>}`]?: (event: GlobalEventHandlersEventMap[E]) => void;
+};
+
+// Props for h(): className/textContent/style, dataset, aria-* attributes,
+// on<Event> listeners, and any writable property of the element itself
+// (value, disabled, placeholder, type, ...), so consumers never cast.
+export type Props<K extends keyof HTMLElementTagNameMap> = Partial<
+	Omit<HTMLElementTagNameMap[K], `on${string}` | "style" | "children" | "dataset">
+> &
+	EventHandlers & {
+		className?: string;
+		dataset?: Record<string, string>;
+		style?: Partial<CSSStyleDeclaration>;
+		[aria: `aria-${string}`]: string | undefined;
+	};
+
+export type Child = string | Node | false | null | undefined | Child[];
+
+const appendChild = (parent: HTMLElement, child: Child): void => {
+	if (child === false || child === null || child === undefined) return;
+	if (Array.isArray(child)) {
+		for (const c of child) appendChild(parent, c);
+		return;
+	}
+	parent.append(child);
+};
+
+// h - typed hyperscript. The generalized, exported successor to the
+// store's local el(); assigns known element properties directly (so no
+// `as HTMLXElement` casts), maps on<Event> keys to addEventListener, and
+// flattens truthy children.
+export function h<K extends keyof HTMLElementTagNameMap>(
+	tag: K,
+	props?: Props<K> | null,
+	...children: Child[]
+): HTMLElementTagNameMap[K] {
+	const node = document.createElement(tag);
+	if (props) {
+		for (const [key, value] of Object.entries(props)) {
+			if (value === undefined) continue;
+			if (key === "dataset") {
+				Object.assign(node.dataset, value);
+			} else if (key === "style") {
+				Object.assign(node.style, value);
+			} else if (key.startsWith("aria-")) {
+				node.setAttribute(key, value as string);
+			} else if (/^on[A-Z]/.test(key) && typeof value === "function") {
+				node.addEventListener(key.slice(2).toLowerCase(), value as EventListener);
+			} else {
+				(node as Record<string, unknown>)[key] = value;
+			}
+		}
+	}
+	for (const child of children) appendChild(node, child);
+	return node;
+}
+
+// ---------- buttons ----------
+
+export function Button(props: {
+	label: string;
+	variant?: ButtonVariant;
+	onClick: () => void;
+	disabled?: boolean;
+	icon?: Node;
+}): HTMLButtonElement {
+	return h(
+		"button",
+		{ type: "button", className: buttonClass(props.variant), disabled: props.disabled, onClick: props.onClick },
+		props.icon,
+		props.label,
+	);
+}
+
+// The circular icon button Spotify uses for modal close (Credits, etc).
+export function IconButton(props: { glyph: string; ariaLabel: string; onClick: () => void }): HTMLButtonElement {
+	return h("button", {
+		type: "button",
+		className: ICON_BUTTON_CLASS,
+		"aria-label": props.ariaLabel,
+		textContent: props.glyph,
+		onClick: props.onClick,
+	});
+}
+
+// ---------- inputs ----------
+
+export function Select<T extends string>(props: {
+	options: ReadonlyArray<{ value: T; label: string }>;
+	value: T;
+	onChange: (value: T) => void;
+}): HTMLSelectElement {
+	const select = h("select", {
+		className: SELECT_CLASS,
+		onChange: () => props.onChange(select.value as T),
+	});
+	for (const option of props.options) {
+		select.append(
+			h("option", { value: option.value, textContent: option.label, selected: option.value === props.value }),
+		);
+	}
+	select.value = props.value;
+	return select;
+}
+
+export function TextInput(props: {
+	placeholder?: string;
+	value?: string;
+	onInput?: (value: string) => void;
+	disabled?: boolean;
+}): HTMLInputElement {
+	const input = h("input", {
+		type: "text",
+		className: SEARCHBAR_CLASS,
+		placeholder: props.placeholder,
+		value: props.value,
+		disabled: props.disabled,
+		onInput: props.onInput ? () => props.onInput!(input.value) : undefined,
+	});
+	return input;
+}
+
+export function Textarea(props: {
+	placeholder?: string;
+	value?: string;
+	onInput?: (value: string) => void;
+}): HTMLTextAreaElement {
+	const textarea = h("textarea", {
+		placeholder: props.placeholder,
+		value: props.value,
+		onInput: props.onInput ? () => props.onInput!(textarea.value) : undefined,
+	});
+	return textarea;
+}
+
+// ---------- badges, chips, cards ----------
+
+export function Badge(props: { text: string; tone?: BadgeTone }): HTMLSpanElement {
+	return h("span", { className: badgeClass(props.tone), textContent: props.text });
+}
+
+export function Chip(props: { label: string; active: boolean; onClick: () => void }): HTMLButtonElement {
+	return h("button", {
+		type: "button",
+		className: chipClass(props.active),
+		textContent: props.label,
+		onClick: props.onClick,
+	});
+}
+
+// A plain elevated container; slot layout is the consumer's own concern.
+export function Card(props: { children: Child }): HTMLElement {
+	return h("article", { className: CARD_CLASS }, props.children);
+}
+
+// ---------- two-step confirm ----------
+
+// ConfirmButton encapsulates the arm-then-confirm pattern: the first
+// click swaps the label and arms a revert timer; a second click within
+// the window confirms. Timers are injectable so the window is
+// deterministic under test.
+export function ConfirmButton(props: {
+	label: string;
+	confirmLabel: string;
+	onConfirm: () => void;
+	variant?: ButtonVariant;
+	windowMs?: number;
+	setTimer?: (fn: () => void, ms: number) => number;
+	clearTimer?: (handle: number) => void;
+}): HTMLButtonElement {
+	const setTimer = props.setTimer ?? ((fn, ms) => setTimeout(fn, ms) as unknown as number);
+	const clearTimer = props.clearTimer ?? ((handle) => clearTimeout(handle));
+	let armed: number | null = null;
+	const disarm = () => {
+		if (armed !== null) clearTimer(armed);
+		armed = null;
+		button.textContent = props.label;
+	};
+	const button = h("button", {
+		type: "button",
+		className: buttonClass(props.variant),
+		textContent: props.label,
+		onClick: () => {
+			if (armed !== null) {
+				disarm();
+				props.onConfirm();
+				return;
+			}
+			button.textContent = props.confirmLabel;
+			armed = setTimer(disarm, props.windowMs ?? 4000);
+		},
+	});
+	return button;
+}
+
+// ---------- dialog ----------
+
+export interface DialogHandle {
+	body: HTMLElement;
+	close: () => void;
+}
+
+// openDialog mounts a scrim + dialog (with a title and circular close),
+// appends it to document.body, and returns the body plus a close(). The
+// backdrop, close button, and programmatic close() all run one teardown,
+// so onClose fires exactly once on any dismissal path (consumers use it
+// to drop their own bookkeeping, e.g. a dispose registry).
+export function openDialog(props: { title: string; children: Child; onClose?: () => void }): DialogHandle {
+	const body = h("div", { className: DIALOG_BODY_CLASS }, props.children);
+	let closed = false;
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		scrim.remove();
+		props.onClose?.();
+	};
+	const header = h(
+		"div",
+		{ className: DIALOG_HEADER_CLASS },
+		h("h2", { textContent: props.title }),
+		IconButton({ glyph: "×", ariaLabel: "Close", onClick: close }),
+	);
+	const dialog = h("div", { className: DIALOG_CLASS }, header, body);
+	const scrim = h(
+		"div",
+		{
+			className: SCRIM_CLASS,
+			onClick: (e) => {
+				if (e.target === scrim) close();
+			},
+		},
+		dialog,
+	);
+	document.body.append(scrim);
+	return { body, close };
+}