@spicetify/kit 0.1.0

package/vendor/stdlib/src/expose/GraphQL.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+export type GraphQLOp = "query" | "mutation";
+export type GraphQLDef<N extends string, O extends GraphQLOp> = {
+	name: N;
+	operation: O;
+	sha256Hash: string;
+	value: null;
+};
+export type GraphQLDefs = { [O in GraphQLOp]: { [N in string]: GraphQLDef<N, O> } };
+
+export const GraphQLDefs = {
+	query: {},
+	mutation: {},
+} as GraphQLDefs;
+
+transformer(
+	(emit) => (str) => {
+		emit();
+
+		const matches = str.matchAll(
+			/(=new [a-zA-Z_\$][\w\$]*\.[a-zA-Z_\$][\w\$]*\("(?<name>\w+)","(?<operation>query|mutation)","(?<sha256Hash>[\w\d]{64})",null\))/g,
+		);
+		for (const match of matches) {
+			const { name, operation, sha256Hash } = match.groups!;
+			// @ts-ignore
+			GraphQLDefs[operation][name] = { name, operation, sha256Hash, value: null };
+		}
+
+		return str;
+	},
+	{
+		glob: /.+\.js$/,
+	},
+);

package/vendor/stdlib/src/expose/Platform.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// The original exposed Platform via a runtime source transform of the client
+// core bundle, which never executes on snapshot builds. Resolve lazily: the
+// mixin phase imports this module before the client (and Spicetify._platform)
+// exists, so capture must happen on first use, not at import time.
+let cached: unknown;
+
+function resolvePlatform(): any {
+	if (cached === undefined) {
+		cached = globalThis.Spicetify?._platform ?? null;
+	}
+	return cached ?? undefined;
+}
+
+export const Platform: any = new Proxy(
+	{},
+	{
+		get: (_, key) => {
+			const p = resolvePlatform();
+			if (!p) return undefined;
+			if (key in p) return p[key];
+			if (typeof key === "string" && key.startsWith("get") && typeof p.getRegistry === "function") {
+				const description = key.slice(3);
+				for (const s of p.getRegistry()._map.keys()) {
+					if (s.description === description) return () => p.getRegistry().resolve(s);
+				}
+			}
+			return undefined;
+		},
+		has: (_, key) => {
+			const p = resolvePlatform();
+			if (!p) return false;
+			if (key in p) return true;
+			if (typeof key === "string" && key.startsWith("get") && typeof p.getRegistry === "function") {
+				const description = key.slice(3);
+				for (const s of p.getRegistry()._map.keys()) {
+					if (s.description === description) return true;
+				}
+			}
+			return false;
+		},
+	},
+);

package/vendor/stdlib/src/expose/React.ts

@@ -0,0 +1,95 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { exports as webpackExports } from "../webpack/index.ts";
+
+// One React rule: module trees mix stdlib chrome, module components, and
+// client components, so hooks and context identity must resolve to the
+// client's own React instance. The 2024 runtime unified the other way
+// (pre-boot factory swap to the esm.sh copy); post-boot that is impossible,
+// so the exposed React lazily forwards to the client instance once webpack
+// is captured.
+//
+// The esm.sh copy only backs pre-capture access — element creation is
+// instance-independent, and module hooks never run pre-capture (the loader
+// gates module loads on webpackLoaded). It therefore loads lazily, and only
+// on an actual pre-capture miss: a static import here would put esm.sh in
+// every client's boot path and make an offline boot fail the whole module
+// graph.
+// Fires when any lazy fallback module lands, so the named live bindings in
+// the react shims can run a second populate pass. Without it, a capture miss
+// (needle drift after a client update) leaves the named bindings frozen
+// undefined even though the default-export proxy path recovers.
+const recoverySubscribers = new Set<() => void>();
+let anyFallbackLanded = false;
+export function onFallbackRecovery(cb: () => void): void {
+	recoverySubscribers.add(cb);
+	if (anyFallbackLanded) cb();
+}
+const notifyRecovery = () => {
+	anyFallbackLanded = true;
+	for (const cb of recoverySubscribers) {
+		try {
+			cb();
+		} catch {
+			/* a subscriber must not break the others */
+		}
+	}
+};
+
+const lazyFallback = (url: string, pick: (m: Record<string, unknown>) => object | undefined) => {
+	let mod: object | undefined;
+	let requested = false;
+	return (): object | undefined => {
+		if (!mod && !requested) {
+			requested = true;
+			void import(url)
+				.then((m) => {
+					mod = pick(m);
+					notifyRecovery();
+				})
+				.catch(() => {
+					/* offline: the client instance is the real path anyway */
+				});
+		}
+		return mod;
+	};
+};
+
+const lazyInstance = <T extends object>(find: () => object | undefined, fallback: () => object | undefined): T => {
+	let cached: object | undefined;
+	return new Proxy({} as T, {
+		get: (_target, key) => {
+			cached ??= find();
+			return ((cached ?? fallback()) as Record<PropertyKey, unknown> | undefined)?.[key];
+		},
+	});
+};
+
+type ReactModule = typeof import("react");
+type ReactDOMModule = typeof import("react-dom") & typeof import("react-dom/client");
+
+export const React: ReactModule = lazyInstance(
+	() =>
+		webpackExports?.find(
+			(m) =>
+				m &&
+				typeof m.createElement === "function" &&
+				typeof m.useReducer === "function" &&
+				typeof m.useEffect === "function",
+		),
+	lazyFallback("https://esm.sh/react@18.3.1", (m) => (m.default ?? m) as object),
+);
+export const ReactDOM: ReactDOMModule = lazyInstance(
+	() => webpackExports?.find((m) => m && typeof m.createRoot === "function" && typeof m.createPortal === "function"),
+	lazyFallback("https://esm.sh/react-dom@18.3.1", (m) => (m.default ?? m) as object),
+);
+// The client bundles its own react-dom/server (renderToString consumers);
+// forward to it, esm.sh only as the same lazy last resort.
+export const ReactDOMServer: typeof import("react-dom/server") = lazyInstance(
+	() => webpackExports?.find((m) => m && typeof m.renderToString === "function"),
+	lazyFallback("https://esm.sh/react-dom@18.3.1/server", (m) => (m.default ?? m) as object),
+);

package/vendor/stdlib/src/expose/ReactFlipToolkitSpring.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+import type { spring } from "npm:react-flip-toolkit";
+
+export type ReactFlipToolkitSpring = typeof spring;
+export let ReactFlipToolkitSpring: ReactFlipToolkitSpring;
+
+transformer<ReactFlipToolkitSpring>(
+	(emit) => (str) => {
+		str = str.replace(
+			/([a-zA-Z_\$][\w\$]*)=((?:function|\()([\w$.,{}()= ]+(?:springConfig|overshootClamping)){2})/,
+			"$1=__ReactFlipToolkitSpring=$2",
+		);
+		Object.defineProperty(globalThis, "__ReactFlipToolkitSpring", { set: emit });
+		return str;
+	},
+	{
+		glob: /^\/vendor~xpui\.js/,
+	},
+).then(($) => {
+	ReactFlipToolkitSpring = $;
+});

package/vendor/stdlib/src/expose/ReduxStore.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+type Store = any;
+
+export type ReduxStore = Store;
+export let ReduxStore: ReduxStore;
+export let Platform: any;
+
+transformer(
+	(emit) => (str) => {
+		str = str.replace(
+			/\.jsx\)\(([a-zA-Z_\$][\w\$]*),\{store:([a-zA-Z_\$][\w\$]*),platform:([a-zA-Z_\$][\w\$]*)\}\)/,
+			".jsx)($1,{store:__ReduxStore=$2,platform:__Platform=$3})",
+		);
+		Object.defineProperty(globalThis, "__ReduxStore", {
+			set: (value) => {
+				emit();
+				ReduxStore = value;
+			},
+			get: () => ReduxStore,
+		});
+		// Object.defineProperty(globalThis, "__Platform", {
+		// 	set: (value) => {
+		// 		emit();
+		// 		Platform = value;
+		// 	},
+		// 	get: () => Platform,
+		// });
+		return str;
+	},
+	{
+		glob: /^\/xpui\.js/,
+	},
+);

package/vendor/stdlib/src/expose/SettingsSection.ts

@@ -0,0 +1,60 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+export type SettingsSectionProps = { filterMatchQuery: string; children?: React.ReactNode };
+export type SettingsSection = React.FC<SettingsSectionProps>;
+export let SettingsSection: SettingsSection;
+
+export const future = {
+	push: () => {},
+	pull(fn: () => void) {
+		const push = this.push;
+		this.push = () => {
+			push();
+			fn();
+		};
+	},
+};
+
+export type SettingsSectionTitleProps = { children?: React.ReactNode };
+export type SettingsSectionTitle = React.FC<SettingsSectionTitleProps>;
+export let SettingsSectionTitle: SettingsSectionTitle;
+
+transformer<SettingsSection>(
+	(emit) => (str) => {
+		str = str.replace(
+			/(\.jsxs\)\()([a-zA-Z_\$][\w\$]*)([^=]*"desktop.settings.compatibility")/,
+			"$1(__SettingsSection=$2)$3",
+		);
+		Object.defineProperty(globalThis, "__SettingsSection", { set: emit });
+		return str;
+	},
+	{
+		glob: /^\/xpui-routes-desktop-settings\.js/,
+		wait: false,
+	},
+).then(($) => {
+	SettingsSection = $;
+	future.push();
+});
+
+transformer<SettingsSectionTitle>(
+	(emit) => (str) => {
+		str = str.replace(
+			/("desktop.settings.compatibility"[^=]*?\.jsx\)\()([a-zA-Z_\$][\w\$]*)/,
+			"$1(__SettingsSectionTitle=$2)",
+		);
+		Object.defineProperty(globalThis, "__SettingsSectionTitle", { set: emit });
+		return str;
+	},
+	{
+		glob: /^\/xpui-routes-desktop-settings\.js/,
+		wait: false,
+	},
+).then(($) => {
+	SettingsSectionTitle = $;
+});

package/vendor/stdlib/src/expose/Snackbar.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+import type SnackbarT from "npm:notistack";
+
+export type Snackbar = typeof SnackbarT;
+export let Snackbar: Snackbar;
+
+transformer<Snackbar>(
+	(emit) => (str) => {
+		str = str.replace(
+			/var ([a-zA-Z_\$][\w\$]*);return\(\1=([^;]*?)\)\.enqueueSnackbar=/,
+			"var $1;return($1=__Snackbar=$2).enqueueSnackbar=",
+		);
+		let __Snackbar: Snackbar | undefined = undefined;
+		Object.defineProperty(globalThis, "__Snackbar", {
+			set: (value) => {
+				emit(value);
+				__Snackbar = value;
+			},
+			get: () => __Snackbar,
+		});
+		return str;
+	},
+	{
+		glob: /^\/vendor~xpui\.js/,
+	},
+).then(($) => {
+	Snackbar = $;
+});

package/vendor/stdlib/src/expose/Tippy.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+type TippyT = any;
+
+export type Tippy = TippyT;
+export let Tippy: Tippy;
+
+transformer<Tippy>(
+	(emit) => (str) => {
+		str = str.replace(/(([a-zA-Z_\$][\w\$]*)\.setDefaultProps=)/, "__Tippy=$2;$1");
+		Object.defineProperty(globalThis, "__Tippy", {
+			set: emit,
+		});
+		return str;
+	},
+	{
+		glob: /^\/vendor~xpui\.js/,
+	},
+).then(($) => {
+	Tippy = $;
+});

package/vendor/stdlib/src/expose/enqueueImageSnackbar.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { transformer } from "../../mixin.ts";
+
+export let enqueueImageSnackbar: any;
+
+// TODO: replace with a custom enqueueCustomSnackbar wrapper
+transformer(
+	(emit) => (str) => {
+		str = str.replace(/(\(\({[^}]*,\s*imageSrc)/, "__enqueueImageSnackbar=$1");
+		Object.defineProperty(globalThis, "__enqueueImageSnackbar", {
+			set: emit,
+		});
+		return str;
+	},
+	{
+		glob: /^\/xpui\.js/,
+		wait: false,
+	},
+).then(($: any) => {
+	enqueueImageSnackbar = $;
+});

package/vendor/stdlib/src/expose/index.ts

@@ -0,0 +1,14 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import "./enqueueImageSnackbar.ts";
+import "./GraphQL.ts";
+import "./Platform.ts";
+import "./React.ts";
+import "./ReactFlipToolkitSpring.ts";
+import "./ReduxStore.ts";
+import "./SettingsSection.ts";
+import "./Snackbar.ts";
+import "./Tippy.ts";

package/vendor/stdlib/src/expose/jsx-runtime.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// Automatic-runtime JSX backed by the captured client React. The kit build
+// aliases "react/jsx-runtime" here so a module's boot never depends on the
+// network (the esm.sh runtime it replaces was a static import in every
+// built .tsx module). Element creation must go through the client instance
+// anyway — one React rule.
+
+import { React } from "./React.ts";
+
+// A stable local sentinel rather than a snapshot of React.Fragment: this
+// module can be evaluated before the webpack capture completes (a mixin or
+// any early importer is enough), and a `const Fragment = React.Fragment`
+// taken at that moment freezes undefined forever — after which every
+// fragment in every module renders as React error #130 and the route
+// overlay shows a blank page. All fragment usage flows through jsx/jsxs
+// below, so the sentinel is swapped for the real React.Fragment at call
+// time, when the capture is live.
+export const Fragment: unknown = Symbol.for("spicetify.jsx.Fragment");
+
+// The automatic runtime passes children inside props and the key as a third
+// argument; createElement wants the key in props. Children stay in props
+// untouched — createElement reads config.children when no vararg children
+// are given — because re-spreading them as varargs changes arity: a
+// one-element array arrives as a bare child and an empty array as
+// undefined, so any component that does children.map() breaks only when the
+// list happens to have one entry. jsx/jsxs differ only in a static-children
+// guarantee createElement doesn't care about.
+//
+// The sentinel translation only covers these create paths. An element built
+// by handing this module's Fragment straight to React.createElement fails
+// visibly, and element.type === Fragment is always false for JSX-created
+// elements — both need unusual hand-written imports.
+function create(type: unknown, props: Record<string, unknown> | null, key?: unknown) {
+	if (type === Fragment) type = React.Fragment;
+	const config = key !== undefined ? { ...props, key } : (props ?? {});
+	const ce = React.createElement as (...args: unknown[]) => unknown;
+	return ce(type, config);
+}
+
+export const jsx = create;
+export const jsxs = create;
+export const jsxDEV = create;

package/vendor/stdlib/src/expose/react-dom-shim.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// npm-style `import ... from "react-dom"` resolves here, forwarding to the
+// client's own ReactDOM. Live bindings populated at capture time rather than
+// init-time snapshots — see react-shim.ts for why a snapshot here freezes
+// undefined for the whole session.
+
+import { warn } from "../logger.ts";
+import { onWebpackCaptured } from "../webpack/index.ts";
+import { onFallbackRecovery, ReactDOM } from "./React.ts";
+
+const RD = ReactDOM as any;
+
+export default ReactDOM;
+
+export let createPortal: any;
+export let createRoot: any;
+export let findDOMNode: any;
+export let flushSync: any;
+export let hydrate: any;
+export let hydrateRoot: any;
+export let render: any;
+export let unmountComponentAtNode: any;
+export let version: any;
+
+function populate() {
+	createPortal = RD.createPortal;
+	createRoot = RD.createRoot;
+	findDOMNode = RD.findDOMNode;
+	flushSync = RD.flushSync;
+	hydrate = RD.hydrate;
+	hydrateRoot = RD.hydrateRoot;
+	render = RD.render;
+	unmountComponentAtNode = RD.unmountComponentAtNode;
+	version = RD.version;
+}
+
+onWebpackCaptured(() => {
+	populate();
+	if (typeof createRoot !== "function") {
+		warn(
+			"[stdlib] capture health: the client ReactDOM was not found in the webpack capture — " +
+				"named `react-dom` imports are degraded until the fallback loads",
+		);
+		onFallbackRecovery(populate);
+	}
+});

package/vendor/stdlib/src/expose/react-shim.ts

@@ -0,0 +1,116 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// npm-style `import ... from "react"` in module code resolves here (the kit
+// build externalizes it to this runtime URL), so every module shares the
+// client's React instance — hooks, context, and Component identity all match
+// the renderer. The jsx runtime is stdlib-local too (./jsx-runtime.ts), so a
+// built module's boot never depends on the network.
+//
+// Live bindings, not init-time snapshots: a `const X = R.X` taken while this
+// file evaluates freezes whatever the lazy proxy returned at that moment —
+// undefined, whenever anything evaluates the shim before the webpack capture
+// (the Fragment bug, at 33x the blast radius). `export let` populated by the
+// capture callback keeps the bindings live: consumers evaluate post-capture
+// (the loader gates module loads on webpackLoaded) and read real values.
+
+import { warn } from "../logger.ts";
+import { onWebpackCaptured } from "../webpack/index.ts";
+import { onFallbackRecovery, React } from "./React.ts";
+
+const R = React as any;
+
+export default React;
+
+export let Children: any;
+export let Component: any;
+export let Fragment: any;
+export let Profiler: any;
+export let PureComponent: any;
+export let StrictMode: any;
+export let Suspense: any;
+export let cloneElement: any;
+export let createContext: any;
+export let createElement: any;
+export let createFactory: any;
+export let createRef: any;
+export let forwardRef: any;
+export let isValidElement: any;
+export let lazy: any;
+export let memo: any;
+export let startTransition: any;
+export let useCallback: any;
+export let useContext: any;
+export let useDebugValue: any;
+export let useDeferredValue: any;
+export let useEffect: any;
+export let useId: any;
+export let useImperativeHandle: any;
+export let useInsertionEffect: any;
+export let useLayoutEffect: any;
+export let useMemo: any;
+export let useReducer: any;
+export let useRef: any;
+export let useState: any;
+export let useSyncExternalStore: any;
+export let useTransition: any;
+export let version: any;
+
+// Capture health (D3): a populate that comes up empty means the React
+// needle missed the capture — the silent needle-drift failure after a client
+// update. Say so where the manager can show it, and re-populate when the
+// esm.sh fallback lands (L2) so named imports degrade to the fallback copy
+// instead of staying frozen undefined.
+function populate() {
+	Children = R.Children;
+	Component = R.Component;
+	Fragment = R.Fragment;
+	Profiler = R.Profiler;
+	PureComponent = R.PureComponent;
+	StrictMode = R.StrictMode;
+	Suspense = R.Suspense;
+	cloneElement = R.cloneElement;
+	createContext = R.createContext;
+	createElement = R.createElement;
+	createFactory = R.createFactory;
+	createRef = R.createRef;
+	forwardRef = R.forwardRef;
+	isValidElement = R.isValidElement;
+	lazy = R.lazy;
+	memo = R.memo;
+	startTransition = R.startTransition;
+	useCallback = R.useCallback;
+	useContext = R.useContext;
+	useDebugValue = R.useDebugValue;
+	useDeferredValue = R.useDeferredValue;
+	useEffect = R.useEffect;
+	useId = R.useId;
+	useImperativeHandle = R.useImperativeHandle;
+	useInsertionEffect = R.useInsertionEffect;
+	useLayoutEffect = R.useLayoutEffect;
+	useMemo = R.useMemo;
+	useReducer = R.useReducer;
+	useRef = R.useRef;
+	useState = R.useState;
+	useSyncExternalStore = R.useSyncExternalStore;
+	useTransition = R.useTransition;
+	version = R.version;
+}
+
+onWebpackCaptured(() => {
+	populate();
+	if (typeof createElement !== "function") {
+		warn(
+			"[stdlib] capture health: the client React was not found in the webpack capture — " +
+				"named `react` imports are degraded until the fallback loads (needle drift after a Spotify update?)",
+		);
+		onFallbackRecovery(() => {
+			populate();
+			if (typeof createElement === "function") {
+				warn("[stdlib] capture health: named `react` imports recovered via the fallback copy");
+			}
+		});
+	}
+});

package/vendor/stdlib/src/logger.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// warn logs to the console and, when the loader's diagnostics buffer exists,
+// records the entry so management UIs can surface drift without the
+// devtools console. stdlib never creates the buffer — the loader owns it.
+const DIAGNOSTICS_CAP = 200;
+
+const safeString = (value: unknown): string => {
+	try {
+		return String(value);
+	} catch {
+		return "[unprintable]";
+	}
+};
+
+export const warn = (...args: unknown[]): void => {
+	console.warn(...args);
+	// Same cap the loader enforces; this is a public barrel export, so it
+	// must neither grow the buffer unboundedly nor throw on hostile args.
+	try {
+		const buffer = (
+			globalThis as never as {
+				__SPICETIFY_DIAGNOSTICS__?: Array<{ ts: number; level: string; message: string }>;
+			}
+		).__SPICETIFY_DIAGNOSTICS__;
+		if (!buffer) return;
+		buffer.push({ ts: Date.now(), level: "warn", message: args.map(safeString).join(" ") });
+		if (buffer.length > DIAGNOSTICS_CAP) buffer.splice(0, buffer.length - DIAGNOSTICS_CAP);
+	} catch {
+		// Never break the caller for a diagnostics write.
+	}
+};