From 76182aa546e0637ebc296db0ae2b1d0a597ebdd2 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:28:55 +0200
Subject: [PATCH 01/14] perf(loader): skip the capture wait when push runs the
 callback

---
 .../modularLoader/boot-order.test.mts         | 19 +++++++++++++++++++
 src/jsHelper/modularLoader/webpackCapture.ts  |  2 ++
 2 files changed, 21 insertions(+)

diff --git a/src/jsHelper/modularLoader/boot-order.test.mts b/src/jsHelper/modularLoader/boot-order.test.mts
index 5418464424..905c984b31 100644
--- a/src/jsHelper/modularLoader/boot-order.test.mts
+++ b/src/jsHelper/modularLoader/boot-order.test.mts
@@ -42,6 +42,25 @@ describe("modular loader boot order", () => {
     assert.equal(typeof captured, "function");
   });
 
+  it("returns without waiting when push runs the runtime callback synchronously", async () => {
+    let waits = 0;
+    let captured: unknown;
+    const ok = await captureModule!.captureWebpackRequire({
+      maxWaitMs: 30000,
+      now: Date.now,
+      wait: async () => {
+        waits++;
+      },
+      getQueue: () => ({
+        push: (chunk: unknown[]) => (chunk[2] as (require: unknown) => unknown)(() => "webpack"),
+      }),
+      getCaptured: () => captured,
+      setCaptured: (require) => (captured = require),
+    });
+    assert.equal(ok, true);
+    assert.equal(waits, 0);
+  });
+
   it("times out when queue push never invokes the runtime callback", async () => {
     let now = 0;
     const ok = await captureModule!.captureWebpackRequire({
diff --git a/src/jsHelper/modularLoader/webpackCapture.ts b/src/jsHelper/modularLoader/webpackCapture.ts
index 6823378c52..fa596471c4 100644
--- a/src/jsHelper/modularLoader/webpackCapture.ts
+++ b/src/jsHelper/modularLoader/webpackCapture.ts
@@ -23,6 +23,8 @@ export async function captureWebpackRequire(options: WebpackCaptureOptions): Pro
 					return require;
 				},
 			]);
+			// The runtime usually runs the chunk callback inside push.
+			if (typeof options.getCaptured() === "function") return true;
 		}
 		// Capture is an ordered poll: each wait must observe whether the runtime
 		// callback fired before another attempt or the deadline check.

From c4ac903b4a58b000a608031ee82865c30b3db364 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:29:50 +0200
Subject: [PATCH 02/14] fix(wrapper): limit the scrolling fix to Spotify 1.2.56
 and older

---
 src/jsHelper/spicetifyWrapper/platform.js         |  4 ++--
 src/jsHelper/spicetifyWrapper/shared/version.js   | 13 +++++++++++++
 .../spicetifyWrapper/shared/version.test.mts      | 15 +++++++++++++++
 3 files changed, 30 insertions(+), 2 deletions(-)
 create mode 100644 src/jsHelper/spicetifyWrapper/shared/version.js
 create mode 100644 src/jsHelper/spicetifyWrapper/shared/version.test.mts

diff --git a/src/jsHelper/spicetifyWrapper/platform.js b/src/jsHelper/spicetifyWrapper/platform.js
index 6b5f74e14d..141851467c 100644
--- a/src/jsHelper/spicetifyWrapper/platform.js
+++ b/src/jsHelper/spicetifyWrapper/platform.js
@@ -14,6 +14,7 @@ import {
 } from "./shared/daemonRpc.js";
 import { managedSpotify } from "./shared/managedSpotify.js";
 import { installUpdateJobBridge, updateAndApply, updateApiSupported } from "./shared/updateAndApply.js";
+import { isVersionBefore } from "./shared/version.js";
 
 const updateAndApplySupported = async () => {
   const daemonSupported = await daemonUpdateAndApplySupported();
@@ -100,8 +101,7 @@ function applyScrollingFix() {
   }
 
   // Run only for 1.2.56 and lower
-  const version = Spicetify.Platform.version.split(".").map((i) => Number.parseInt(i, 10));
-  if (version[1] >= 2 && version[2] >= 57) return;
+  if (!isVersionBefore(Spicetify.Platform.version, [1, 2, 57])) return;
 
   const scrollableElements = Array.from(document.querySelectorAll("*:not([data-scroll-optimized])")).filter((el) => {
     if (
diff --git a/src/jsHelper/spicetifyWrapper/shared/version.js b/src/jsHelper/spicetifyWrapper/shared/version.js
new file mode 100644
index 0000000000..006d4067a6
--- /dev/null
+++ b/src/jsHelper/spicetifyWrapper/shared/version.js
@@ -0,0 +1,13 @@
+/**
+ * Whether a dotted Spotify version such as "1.3.3.264" is older than `target`.
+ * @param {string} version
+ * @param {number[]} target
+ */
+export function isVersionBefore(version, target) {
+  const parts = version.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  for (let i = 0; i < target.length; i++) {
+    const part = parts[i] ?? 0;
+    if (part !== target[i]) return part < target[i];
+  }
+  return false;
+}
diff --git a/src/jsHelper/spicetifyWrapper/shared/version.test.mts b/src/jsHelper/spicetifyWrapper/shared/version.test.mts
new file mode 100644
index 0000000000..994b401af5
--- /dev/null
+++ b/src/jsHelper/spicetifyWrapper/shared/version.test.mts
@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { isVersionBefore } from "./version.js";
+
+describe("isVersionBefore", () => {
+  it("compares each component in order instead of independently", () => {
+    assert.equal(isVersionBefore("1.2.56.502", [1, 2, 57]), true);
+    assert.equal(isVersionBefore("1.2.57.463", [1, 2, 57]), false);
+    assert.equal(isVersionBefore("1.2.94.522", [1, 2, 57]), false);
+    assert.equal(isVersionBefore("1.3.3.264", [1, 2, 57]), false);
+    assert.equal(isVersionBefore("2.0.0", [1, 2, 57]), false);
+    assert.equal(isVersionBefore("1.1.99", [1, 2, 57]), true);
+  });
+});

From 0895d574f85d70800214ce95f03311588fd5d742 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:31:59 +0200
Subject: [PATCH 03/14] perf(loader): load the boot theme before other modules

---
 src/jsHelper/modularLoader/registry.test.mts | 23 +++++++++++++++++
 src/jsHelper/modularLoader/registry.ts       | 27 ++++++++++++++++----
 2 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/src/jsHelper/modularLoader/registry.test.mts b/src/jsHelper/modularLoader/registry.test.mts
index 1d330c06b5..45285d435d 100644
--- a/src/jsHelper/modularLoader/registry.test.mts
+++ b/src/jsHelper/modularLoader/registry.test.mts
@@ -739,3 +739,26 @@ describe("persisted disable", () => {
 		assert.equal(await r.disable("ext"), true, "disable still unloads without persistence");
 	});
 });
+
+describe("boot load order and prefetch", () => {
+	const theme = (id: string, deps: Record<string, string> = {}) =>
+		mod(id, "1.0.0", { kind: "theme", entries: { js: "index.js", css: "index.css" }, dependencies: deps });
+
+	it("loads the boot theme and its dependencies before other extensions", async () => {
+		const calls: string[] = [];
+		const r = new Registry(
+			manifest([
+				mod("stdlib", "1.0.0"),
+				mod("alpha", "1.0.0", { dependencies: { stdlib: "^1.0.0" } }),
+				mod("chrome", "1.0.0"),
+				theme("zeta", { chrome: "^1.0.0", stdlib: "^1.0.0" }),
+			]),
+			trackingEffects(calls),
+		);
+		const report = await r.boot();
+		assert.deepEqual(report.failed, {});
+		const imports = calls.filter((c) => c.startsWith("import:")).map((c) => c.split("/")[2]);
+		assert.deepEqual(imports, ["stdlib", "chrome", "zeta", "alpha"]);
+	});
+
+});
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index 76e5bc4680..5d11ae0fe7 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -245,10 +245,10 @@ export class Registry {
 		}
 	}
 
-	// runLoads executes preload/css/load for all eligible modules, after the
-	// client is up. Call runMixins first during early boot.
-	async runLoads(report: BootReport): Promise<void> {
-		const disabled = this.disabledSet();
+	// bootLoadOrder is the order runLoads walks: the boot theme and everything
+	// it depends on first, so the client is themed before extensions mount,
+	// then every other eligible module in dependency order.
+	private bootLoadOrder(report: BootReport, disabled: Set<string>): { order: string[]; bootTheme?: string } {
 		const eligible = this.eligibleOrder(report, disabled);
 		// Two installed themes would otherwise both load at boot. The persisted
 		// preference (last theme the user enabled) wins; without one, the last
@@ -266,7 +266,24 @@ export class Registry {
 				: preferred && themes.includes(preferred)
 					? preferred
 					: themes[themes.length - 1];
-		for (const id of eligible) {
+		const first = new Set<string>();
+		const pull = (id: string) => {
+			const m = this.modules.get(id);
+			if (!m || first.has(id)) return;
+			for (const dep of Object.keys(m.dependencies)) pull(dep);
+			first.add(id);
+		};
+		if (bootTheme) pull(bootTheme);
+		const order = [...eligible.filter((id) => first.has(id)), ...eligible.filter((id) => !first.has(id))];
+		return { order, bootTheme };
+	}
+
+	// runLoads executes preload/css/load for all eligible modules, after the
+	// client is up. Call runMixins first during early boot.
+	async runLoads(report: BootReport): Promise<void> {
+		const disabled = this.disabledSet();
+		const { order, bootTheme } = this.bootLoadOrder(report, disabled);
+		for (const id of order) {
 			if (report.failed[id]) continue;
 			if (this.isTheme(id) && id !== bootTheme) {
 				this.effects.log("info", `skipping theme ${id}: ${bootTheme} is active (one theme at a time)`);

From 590b725a0e891f4e374d5f549d063dae907c2694 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:32:07 +0200
Subject: [PATCH 04/14] perf(loader): prefetch module entries while the client
 boots

---
 src/jsHelper/modularLoader/index.ts          | 25 ++++++++++++++++++--
 src/jsHelper/modularLoader/registry.test.mts | 23 ++++++++++++++++++
 src/jsHelper/modularLoader/registry.ts       | 17 +++++++++++++
 src/jsHelper/modularLoader/types.ts          |  2 ++
 4 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/src/jsHelper/modularLoader/index.ts b/src/jsHelper/modularLoader/index.ts
index d6896b53d2..4ff4a406e4 100644
--- a/src/jsHelper/modularLoader/index.ts
+++ b/src/jsHelper/modularLoader/index.ts
@@ -71,9 +71,28 @@ async function cssFromSource(text: string): Promise<CSSStyleSheet | string> {
 	return text;
 }
 
+const prefetchedCss = new Map<string, Promise<string>>();
+
+function prefetch(path: string, kind: "js" | "css"): void {
+	if (kind === "js") {
+		const link = document.createElement("link");
+		link.rel = "modulepreload";
+		link.href = path;
+		document.head.appendChild(link);
+		return;
+	}
+	if (prefetchedCss.has(path)) return;
+	const text = fetch(path).then((res) => res.text());
+	// A failed prefetch is retried by loadCss, so it must not surface here.
+	text.catch(() => {});
+	prefetchedCss.set(path, text);
+}
+
 async function loadCss(path: string): Promise<CSSStyleSheet | string> {
-	const res = await fetch(path);
-	return cssFromSource(await res.text());
+	const prefetched = prefetchedCss.get(path);
+	prefetchedCss.delete(path);
+	const text = (await prefetched?.catch(() => undefined)) ?? (await (await fetch(path)).text());
+	return cssFromSource(text);
 }
 
 // parseColorSchemes parses classic spicetify color.ini into named
@@ -486,6 +505,7 @@ async function boot(): Promise<BootReport | null> {
 		importSource,
 		loadCss,
 		cssFromSource,
+		prefetch,
 		adoptCss,
 		applyScheme,
 		activeThemePref: {
@@ -506,6 +526,7 @@ async function boot(): Promise<BootReport | null> {
 	// the 2024 mixin machinery created it. Define it empty so references are
 	// inert instead of fatal.
 	(globalThis as never as Record<string, unknown>).CHUNKS ??= {};
+	registry.prefetchLoads(report);
 	await registry.runMixins(report);
 	await bootClient(transforms);
 
diff --git a/src/jsHelper/modularLoader/registry.test.mts b/src/jsHelper/modularLoader/registry.test.mts
index 45285d435d..1e21f02af9 100644
--- a/src/jsHelper/modularLoader/registry.test.mts
+++ b/src/jsHelper/modularLoader/registry.test.mts
@@ -761,4 +761,27 @@ describe("boot load order and prefetch", () => {
 		assert.deepEqual(imports, ["stdlib", "chrome", "zeta", "alpha"]);
 	});
 
+	it("prefetches only the staged entries boot will import or adopt", () => {
+		const prefetched: string[] = [];
+		const effects = { ...trackingEffects([]), prefetch: (path: string, kind: string) => prefetched.push(`${kind}:${path}`) };
+		const r = new Registry(
+			manifest([
+				mod("stdlib", "1.0.0"),
+				mod("mixer", "1.0.0", { hasMixins: true, entries: { js: "index.js", css: "index.css" } }),
+				mod("off", "1.0.0"),
+				mod("local", "1.0.0"),
+				theme("theme-a"),
+				theme("theme-b"),
+			]),
+			{ ...effects, disabledPref: { get: () => ["off"], add: () => {}, remove: () => {} } },
+		);
+		r.registerLocal({ metadata: mod("local", "1.0.0"), files: { "index.js": "" } });
+		r.prefetchLoads({ loaded: [], failed: {} });
+		assert.deepEqual(prefetched, [
+			"js:/modules/theme-b/index.js",
+			"css:/modules/theme-b/index.css",
+			"js:/modules/stdlib/index.js",
+			"css:/modules/mixer/index.css",
+		]);
+	});
 });
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index 5d11ae0fe7..6e1b1e6605 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -278,6 +278,23 @@ export class Registry {
 		return { order, bootTheme };
 	}
 
+	// prefetchLoads starts fetching the entries runLoads will import or adopt,
+	// without evaluating anything, so they download while the client boots.
+	// Local installs are already in memory, and mixin modules were imported
+	// by runMixins.
+	prefetchLoads(report: BootReport): void {
+		if (!this.effects.prefetch) return;
+		const disabled = this.disabledSet();
+		const { order, bootTheme } = this.bootLoadOrder(report, disabled);
+		for (const id of order) {
+			const m = this.modules.get(id)!;
+			if (report.failed[id] || this.localFiles.has(id)) continue;
+			if (this.isTheme(id) && id !== bootTheme) continue;
+			if (m.entries.js && !m.hasMixins) this.effects.prefetch(entryUrl(id, m.entries.js), "js");
+			if (m.entries.css) this.effects.prefetch(entryUrl(id, m.entries.css), "css");
+		}
+	}
+
 	// runLoads executes preload/css/load for all eligible modules, after the
 	// client is up. Call runMixins first during early boot.
 	async runLoads(report: BootReport): Promise<void> {
diff --git a/src/jsHelper/modularLoader/types.ts b/src/jsHelper/modularLoader/types.ts
index 819152a8d8..159c9fca6e 100644
--- a/src/jsHelper/modularLoader/types.ts
+++ b/src/jsHelper/modularLoader/types.ts
@@ -88,6 +88,8 @@ export interface Effects {
 	// turned back on. Only disable()/enable() write here: internal unloads
 	// (theme switching, dependency cascades) persist nothing.
 	disabledPref?: { get(): string[]; add(identifier: string): void; remove(identifier: string): void };
+	// Starts downloading a module entry ahead of runLoads without evaluating it.
+	prefetch?(path: string, kind: "js" | "css"): void;
 	log(level: "info" | "error", ...args: unknown[]): void;
 }
 

From e20cc379c6e6e77803c5cea28888ab2e69326e79 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:32:07 +0200
Subject: [PATCH 05/14] perf(loader): poll for the client every 25ms

---
 src/jsHelper/modularLoader/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/jsHelper/modularLoader/index.ts b/src/jsHelper/modularLoader/index.ts
index 4ff4a406e4..4391604da0 100644
--- a/src/jsHelper/modularLoader/index.ts
+++ b/src/jsHelper/modularLoader/index.ts
@@ -402,7 +402,7 @@ async function waitForClient(timeoutMs: number): Promise<boolean> {
 	// Base gate: the main view is mounted and the Platform API is up.
 	while (Date.now() < deadline) {
 		if (document.querySelector("main") && spice()?.Platform) break;
-		await new Promise((r) => setTimeout(r, 200));
+		await new Promise((r) => setTimeout(r, 25));
 	}
 	if (!(document.querySelector("main") && spice()?.Platform)) return false;
 	// Platform lands before the webpack-extracted surface (URI, Mousetrap,

From 5a3495b35b7571f24b663193f1b19d2f6aa17c3a Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:51:40 +0200
Subject: [PATCH 06/14] fix(loader): keep theme stylesheets after other module
 stylesheets

---
 src/jsHelper/modularLoader/adopt-css.test.mts | 39 +++++++++++++++++++
 src/jsHelper/modularLoader/index.ts           | 15 +++++--
 src/jsHelper/modularLoader/registry.ts        |  4 +-
 src/jsHelper/modularLoader/types.ts           |  2 +-
 4 files changed, 54 insertions(+), 6 deletions(-)
 create mode 100644 src/jsHelper/modularLoader/adopt-css.test.mts

diff --git a/src/jsHelper/modularLoader/adopt-css.test.mts b/src/jsHelper/modularLoader/adopt-css.test.mts
new file mode 100644
index 0000000000..06c4f7ee51
--- /dev/null
+++ b/src/jsHelper/modularLoader/adopt-css.test.mts
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { Window } from "happy-dom";
+
+import { adoptCss } from "./index.ts";
+
+const win = new Window();
+Object.assign(globalThis, { document: win.document, CSSStyleSheet: win.CSSStyleSheet });
+
+const sheet = (name: string) => {
+	const s = new win.CSSStyleSheet();
+	s.replaceSync(`.${name} {}`);
+	return s;
+};
+const order = () => document.adoptedStyleSheets.map((s) => s.cssRules[0].cssText.split(" ")[0]);
+
+describe("adoptCss", () => {
+	it("keeps theme sheets after extension sheets adopted later", () => {
+		document.adoptedStyleSheets = [];
+		const disposeTheme = adoptCss(sheet("theme"), { theme: true });
+		adoptCss(sheet("alpha"));
+		adoptCss(sheet("beta"));
+		assert.deepEqual(order(), [".alpha", ".beta", ".theme"]);
+		disposeTheme();
+		adoptCss(sheet("gamma"));
+		assert.deepEqual(order(), [".alpha", ".beta", ".gamma"]);
+	});
+
+	it("keeps theme <style> fallbacks after extension ones", () => {
+		document.head.replaceChildren();
+		adoptCss("@import url(x.css); .theme {}", { theme: true });
+		adoptCss("@import url(y.css); .alpha {}");
+		assert.deepEqual(
+			[...document.head.querySelectorAll("style")].map((el) => el.textContent.split("; ")[1]),
+			[".alpha {}", ".theme {}"],
+		);
+	});
+});
diff --git a/src/jsHelper/modularLoader/index.ts b/src/jsHelper/modularLoader/index.ts
index 4391604da0..a2160ee2d7 100644
--- a/src/jsHelper/modularLoader/index.ts
+++ b/src/jsHelper/modularLoader/index.ts
@@ -295,16 +295,25 @@ async function applyScheme(identifier: string, source?: string): Promise<(() =>
 	};
 }
 
-function adoptCss(sheet: unknown): () => void {
+const themeSheets = new Set<CSSStyleSheet>();
+
+// Theme sheets stay after every other module sheet, so a theme overrides
+// extension styles at equal specificity whatever order modules load in.
+export function adoptCss(sheet: unknown, options: { theme?: boolean } = {}): () => void {
 	if (sheet instanceof CSSStyleSheet) {
-		document.adoptedStyleSheets.push(sheet);
+		const sheets = document.adoptedStyleSheets;
+		const at = options.theme ? -1 : sheets.findIndex((s) => themeSheets.has(s));
+		if (options.theme) themeSheets.add(sheet);
+		document.adoptedStyleSheets = at < 0 ? [...sheets, sheet] : [...sheets.slice(0, at), sheet, ...sheets.slice(at)];
 		return () => {
+			themeSheets.delete(sheet);
 			document.adoptedStyleSheets = document.adoptedStyleSheets.filter((s) => s !== sheet);
 		};
 	}
 	const el = document.createElement("style");
 	el.textContent = String(sheet);
-	document.head.appendChild(el);
+	if (options.theme) el.dataset.spicetifyTheme = "";
+	document.head.insertBefore(el, options.theme ? null : document.head.querySelector("style[data-spicetify-theme]"));
 	return () => el.remove();
 }
 
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index 6e1b1e6605..0849e2d592 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -334,7 +334,7 @@ export class Registry {
 
 				if (m.entries.css) {
 					const sheet = await this.cssSheetOf(m);
-					state.disposers.push(this.effects.adoptCss(sheet));
+					state.disposers.push(this.effects.adoptCss(sheet, { theme: this.isTheme(id) }));
 					if (this.effects.applyScheme) {
 						const schemeDisposer = await this.effects.applyScheme(
 							m.identifier,
@@ -438,7 +438,7 @@ export class Registry {
 			if (preloaded) state.disposers.push(preloaded);
 			if (m.entries.css) {
 				const sheet = await this.cssSheetOf(m);
-				state.disposers.push(this.effects.adoptCss(sheet));
+				state.disposers.push(this.effects.adoptCss(sheet, { theme: this.isTheme(identifier) }));
 				if (this.effects.applyScheme) {
 					const schemeDisposer = await this.effects.applyScheme(
 						identifier,
diff --git a/src/jsHelper/modularLoader/types.ts b/src/jsHelper/modularLoader/types.ts
index 159c9fca6e..01d269f0df 100644
--- a/src/jsHelper/modularLoader/types.ts
+++ b/src/jsHelper/modularLoader/types.ts
@@ -77,7 +77,7 @@ export interface Effects {
 	importSource(content: string): Promise<JsIndex>;
 	loadCss(path: string): Promise<unknown>;
 	cssFromSource(content: string): Promise<unknown>;
-	adoptCss(sheet: unknown): DisposeFn;
+	adoptCss(sheet: unknown, options?: { theme?: boolean }): DisposeFn;
 	createTransformer(): TransformerShim;
 	applyScheme?(identifier: string, source?: string): Promise<DisposeFn | null>;
 	// Persisted "last theme the user enabled": boot prefers it over manifest

From e31ac3ee01f6685b155f1aebb7d86488cf6bfc8d Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:51:50 +0200
Subject: [PATCH 07/14] fix(loader): prefetch after mixins and only what boot
 will load

---
 src/jsHelper/modularLoader/index.ts          | 12 +++--
 src/jsHelper/modularLoader/registry.test.mts |  8 ++-
 src/jsHelper/modularLoader/registry.ts       | 56 ++++++++++++--------
 3 files changed, 48 insertions(+), 28 deletions(-)

diff --git a/src/jsHelper/modularLoader/index.ts b/src/jsHelper/modularLoader/index.ts
index a2160ee2d7..990653cf2d 100644
--- a/src/jsHelper/modularLoader/index.ts
+++ b/src/jsHelper/modularLoader/index.ts
@@ -83,7 +83,7 @@ function prefetch(path: string, kind: "js" | "css"): void {
 	}
 	if (prefetchedCss.has(path)) return;
 	const text = fetch(path).then((res) => res.text());
-	// A failed prefetch is retried by loadCss, so it must not surface here.
+	// loadCss reports a failed prefetch when it falls back to its own fetch.
 	text.catch(() => {});
 	prefetchedCss.set(path, text);
 }
@@ -91,8 +91,11 @@ function prefetch(path: string, kind: "js" | "css"): void {
 async function loadCss(path: string): Promise<CSSStyleSheet | string> {
 	const prefetched = prefetchedCss.get(path);
 	prefetchedCss.delete(path);
-	const text = (await prefetched?.catch(() => undefined)) ?? (await (await fetch(path)).text());
-	return cssFromSource(text);
+	const text = await prefetched?.catch((e: unknown) => {
+		log("error")(`prefetch of ${path} failed; fetching again`, e);
+		return undefined;
+	});
+	return cssFromSource(text ?? (await (await fetch(path)).text()));
 }
 
 // parseColorSchemes parses classic spicetify color.ini into named
@@ -535,15 +538,16 @@ async function boot(): Promise<BootReport | null> {
 	// the 2024 mixin machinery created it. Define it empty so references are
 	// inert instead of fatal.
 	(globalThis as never as Record<string, unknown>).CHUNKS ??= {};
-	registry.prefetchLoads(report);
 	await registry.runMixins(report);
 	await bootClient(transforms);
+	registry.prefetchLoads(report);
 
 	if (!(await waitForClient(15000))) {
 		log("error")("client did not come up in time; running module loads anyway");
 	}
 	await captureWebpackRequire();
 	await registry.runLoads(report);
+	prefetchedCss.clear();
 
 	globalThis.Spicetify = globalThis.Spicetify ?? {};
 	const modules = (globalThis.Spicetify as Record<string, unknown>).Modules = {
diff --git a/src/jsHelper/modularLoader/registry.test.mts b/src/jsHelper/modularLoader/registry.test.mts
index 1e21f02af9..a6d8efef9e 100644
--- a/src/jsHelper/modularLoader/registry.test.mts
+++ b/src/jsHelper/modularLoader/registry.test.mts
@@ -761,7 +761,7 @@ describe("boot load order and prefetch", () => {
 		assert.deepEqual(imports, ["stdlib", "chrome", "zeta", "alpha"]);
 	});
 
-	it("prefetches only the staged entries boot will import or adopt", () => {
+	it("prefetches only the staged entries boot will import or adopt", async () => {
 		const prefetched: string[] = [];
 		const effects = { ...trackingEffects([]), prefetch: (path: string, kind: string) => prefetched.push(`${kind}:${path}`) };
 		const r = new Registry(
@@ -769,6 +769,8 @@ describe("boot load order and prefetch", () => {
 				mod("stdlib", "1.0.0"),
 				mod("mixer", "1.0.0", { hasMixins: true, entries: { js: "index.js", css: "index.css" } }),
 				mod("off", "1.0.0"),
+				mod("needs-off", "1.0.0", { dependencies: { off: "^1.0.0" } }),
+				mod("after-needs-off", "1.0.0", { dependencies: { "needs-off": "^1.0.0" } }),
 				mod("local", "1.0.0"),
 				theme("theme-a"),
 				theme("theme-b"),
@@ -776,7 +778,9 @@ describe("boot load order and prefetch", () => {
 			{ ...effects, disabledPref: { get: () => ["off"], add: () => {}, remove: () => {} } },
 		);
 		r.registerLocal({ metadata: mod("local", "1.0.0"), files: { "index.js": "" } });
-		r.prefetchLoads({ loaded: [], failed: {} });
+		const report = { loaded: [], failed: {} };
+		await r.runMixins(report);
+		r.prefetchLoads(report);
 		assert.deepEqual(prefetched, [
 			"js:/modules/theme-b/index.js",
 			"css:/modules/theme-b/index.css",
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index 0849e2d592..c8699c4420 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -278,18 +278,44 @@ export class Registry {
 		return { order, bootTheme };
 	}
 
+	// skipReason is why runLoads would not load a module at boot, if it would not.
+	private skipReason(id: string, report: BootReport, disabled: Set<string>, bootTheme?: string) {
+		if (report.failed[id]) return { failed: false, reason: report.failed[id] };
+		if (this.isTheme(id) && id !== bootTheme) {
+			return { failed: false, reason: `skipping theme ${id}: ${bootTheme} is active (one theme at a time)` };
+		}
+		const m = this.modules.get(id)!;
+		// A disabled dependency is not a failure of its own, but a dependent
+		// that loads against it half-works silently (stdlib's registers
+		// never mount, and nothing says why).
+		const blockedBy = Object.keys(m.dependencies).find((dep) => report.failed[dep] || disabled.has(dep));
+		if (blockedBy) {
+			return {
+				failed: true,
+				reason: disabled.has(blockedBy) ? `dependency ${blockedBy} is disabled` : `dependency ${blockedBy} failed`,
+			};
+		}
+		if (m.hasMixins && !this.state(id).mixedIn) return { failed: true, reason: "mixins not loaded" };
+		return undefined;
+	}
+
 	// prefetchLoads starts fetching the entries runLoads will import or adopt,
 	// without evaluating anything, so they download while the client boots.
-	// Local installs are already in memory, and mixin modules were imported
-	// by runMixins.
+	// Call it after runMixins. Local installs are already in memory, and
+	// mixin modules were imported by runMixins.
 	prefetchLoads(report: BootReport): void {
 		if (!this.effects.prefetch) return;
 		const disabled = this.disabledSet();
 		const { order, bootTheme } = this.bootLoadOrder(report, disabled);
+		const blocked = new Set<string>();
 		for (const id of order) {
 			const m = this.modules.get(id)!;
-			if (report.failed[id] || this.localFiles.has(id)) continue;
-			if (this.isTheme(id) && id !== bootTheme) continue;
+			const blockedDep = Object.keys(m.dependencies).some((dep) => blocked.has(dep));
+			if (blockedDep || this.skipReason(id, report, disabled, bootTheme)) {
+				blocked.add(id);
+				continue;
+			}
+			if (this.localFiles.has(id)) continue;
 			if (m.entries.js && !m.hasMixins) this.effects.prefetch(entryUrl(id, m.entries.js), "js");
 			if (m.entries.css) this.effects.prefetch(entryUrl(id, m.entries.css), "css");
 		}
@@ -302,25 +328,11 @@ export class Registry {
 		const { order, bootTheme } = this.bootLoadOrder(report, disabled);
 		for (const id of order) {
 			if (report.failed[id]) continue;
-			if (this.isTheme(id) && id !== bootTheme) {
-				this.effects.log("info", `skipping theme ${id}: ${bootTheme} is active (one theme at a time)`);
-				continue;
-			}
+			const skip = this.skipReason(id, report, disabled, bootTheme);
+			if (skip?.failed) report.failed[id] = skip.reason;
+			else if (skip) this.effects.log("info", skip.reason);
+			if (skip) continue;
 			const m = this.modules.get(id)!;
-			// A disabled dependency is not a failure of its own, but a dependent
-			// that loads against it half-works silently (stdlib's registers
-			// never mount, and nothing says why).
-			const blockedBy = Object.keys(m.dependencies).find((dep) => report.failed[dep] || disabled.has(dep));
-			if (blockedBy) {
-				report.failed[id] = disabled.has(blockedBy)
-					? `dependency ${blockedBy} is disabled`
-					: `dependency ${blockedBy} failed`;
-				continue;
-			}
-			if (m.hasMixins && !this.state(id).mixedIn) {
-				report.failed[id] = "mixins not loaded";
-				continue;
-			}
 			const loadOnce = async () => {
 				const index = await this.jsIndexOf(m);
 				const state = this.state(id);

From 344f01f681e6cf6f350653c70e6d92d644a1f97c Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 22:51:50 +0200
Subject: [PATCH 08/14] fix(loader): guard the boot theme dependency walk
 against cycles

---
 src/jsHelper/modularLoader/registry.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index c8699c4420..e1487139a9 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -267,9 +267,11 @@ export class Registry {
 					? preferred
 					: themes[themes.length - 1];
 		const first = new Set<string>();
+		const visiting = new Set<string>();
 		const pull = (id: string) => {
 			const m = this.modules.get(id);
-			if (!m || first.has(id)) return;
+			if (!m || first.has(id) || visiting.has(id)) return;
+			visiting.add(id);
 			for (const dep of Object.keys(m.dependencies)) pull(dep);
 			first.add(id);
 		};

From 898538c645168c04ecc50a85d37c81bb619c8528 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 23:30:21 +0200
Subject: [PATCH 09/14] perf(loader): look up color schemes only for themes

---
 src/jsHelper/modularLoader/registry.test.mts | 21 ++++++++++++++++++++
 src/jsHelper/modularLoader/registry.ts       |  4 ++--
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/jsHelper/modularLoader/registry.test.mts b/src/jsHelper/modularLoader/registry.test.mts
index a6d8efef9e..648abf6810 100644
--- a/src/jsHelper/modularLoader/registry.test.mts
+++ b/src/jsHelper/modularLoader/registry.test.mts
@@ -788,4 +788,25 @@ describe("boot load order and prefetch", () => {
 			"css:/modules/mixer/index.css",
 		]);
 	});
+
+	it("looks up a color scheme only for themes", async () => {
+		const schemes: string[] = [];
+		const effects = {
+			...trackingEffects([]),
+			applyScheme: async (id: string) => {
+				schemes.push(id);
+				return null;
+			},
+		};
+		const r = new Registry(
+			manifest([mod("styled", "1.0.0", { entries: { js: "index.js", css: "index.css" } }), theme("theme-a")]),
+			effects,
+		);
+		const report = await r.boot();
+		assert.deepEqual(report.failed, {});
+		assert.deepEqual(schemes, ["theme-a"]);
+		await r.unload("styled");
+		await r.enable("styled", report);
+		assert.deepEqual(schemes, ["theme-a"]);
+	});
 });
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index e1487139a9..9f0e72320b 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -349,7 +349,7 @@ export class Registry {
 				if (m.entries.css) {
 					const sheet = await this.cssSheetOf(m);
 					state.disposers.push(this.effects.adoptCss(sheet, { theme: this.isTheme(id) }));
-					if (this.effects.applyScheme) {
+					if (this.effects.applyScheme && this.isTheme(id)) {
 						const schemeDisposer = await this.effects.applyScheme(
 							m.identifier,
 							this.getLocalFile(m.identifier, "color.ini"),
@@ -453,7 +453,7 @@ export class Registry {
 			if (m.entries.css) {
 				const sheet = await this.cssSheetOf(m);
 				state.disposers.push(this.effects.adoptCss(sheet, { theme: this.isTheme(identifier) }));
-				if (this.effects.applyScheme) {
+				if (this.effects.applyScheme && this.isTheme(identifier)) {
 					const schemeDisposer = await this.effects.applyScheme(
 						identifier,
 						this.getLocalFile(identifier, "color.ini"),

From 08d8f91c36cbe0d25e07a924088a51044837a532 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 23:36:14 +0200
Subject: [PATCH 10/14] feat(apply): list the scripts of multi-file modules in
 the manifest

---
 rust/crates/spicetify/src/module/stage.rs | 70 ++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

diff --git a/rust/crates/spicetify/src/module/stage.rs b/rust/crates/spicetify/src/module/stage.rs
index 7b1e846cc5..13dc838ab7 100644
--- a/rust/crates/spicetify/src/module/stage.rs
+++ b/rust/crates/spicetify/src/module/stage.rs
@@ -68,6 +68,11 @@ pub(crate) struct StagedModule {
     pub identifier: String,
     #[serde(flatten)]
     pub metadata: ModuleMetadata,
+    /// Every other script of a multi-file module, relative to its directory,
+    /// so the loader can fetch the whole tree while the client boots instead
+    /// of one import level at a time.
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub preload: Vec<String>,
 }
 
 #[derive(Debug, Serialize)]
@@ -280,6 +285,42 @@ fn remap_source(
     Err(anyhow::anyhow!("classmap references failed ({})", parts.join("; ")))
 }
 
+// module_scripts lists a staged module's JavaScript files other than its
+// entry, sorted, when it has more than one. Tests are left out.
+fn module_scripts(dir: &Path, entry: Option<&str>) -> Vec<String> {
+    fn walk(root: &Path, dir: &Path, out: &mut Vec<String>) {
+        let Ok(entries) = std::fs::read_dir(dir) else { return };
+        for entry in entries.filter_map(std::result::Result::ok) {
+            let path = entry.path();
+            if path.is_dir() {
+                walk(root, &path, out);
+                continue;
+            }
+            let Some(name) = path.file_name().and_then(|n| n.to_str()) else { continue };
+            let script = path
+                .extension()
+                .and_then(|e| e.to_str())
+                .is_some_and(|e| e.eq_ignore_ascii_case("js") || e.eq_ignore_ascii_case("mjs"));
+            if !script || name.contains(".test.") {
+                continue;
+            }
+            if let Ok(relative) = path.strip_prefix(root) {
+                let parts: Vec<_> =
+                    relative.components().map(|c| c.as_os_str().to_string_lossy()).collect();
+                out.push(parts.join("/"));
+            }
+        }
+    }
+    let mut scripts = Vec::new();
+    walk(dir, dir, &mut scripts);
+    if scripts.len() < 2 {
+        return Vec::new();
+    }
+    scripts.retain(|script| Some(script.as_str()) != entry);
+    scripts.sort();
+    scripts
+}
+
 fn stage_tree(
     src_root: &Path,
     out_dir: &Path,
@@ -407,7 +448,8 @@ pub(crate) fn stage_modules(
             tracing::warn!("skipping module {identifier}: {e}");
             continue;
         }
-        staged.push(StagedModule { identifier, metadata });
+        let preload = module_scripts(&out_dir, metadata.entries.get("js").and_then(|v| v.as_str()));
+        staged.push(StagedModule { identifier, metadata, preload });
     }
 
     if staged.is_empty() {
@@ -518,6 +560,32 @@ mod tests {
         std::fs::remove_dir_all(root).expect("cleanup");
     }
 
+    #[test]
+    fn lists_the_other_scripts_of_a_multi_file_module() {
+        let root = scratch("module-scripts");
+        let tree = root.join("tree");
+        std::fs::create_dir_all(tree.join("src/webpack")).expect("tree dirs");
+        for file in [
+            "index.js",
+            "load.js",
+            "src/webpack/index.js",
+            "src/util.test.mjs",
+            "index.css",
+            "index.js.map",
+        ] {
+            std::fs::write(tree.join(file), "").expect("tree file");
+        }
+        assert_eq!(
+            module_scripts(&tree, Some("index.js")),
+            vec!["load.js", "src/webpack/index.js"]
+        );
+
+        let single = root.join("single");
+        std::fs::create_dir_all(&single).expect("single dir");
+        std::fs::write(single.join("index.js"), "").expect("single entry");
+        assert!(module_scripts(&single, Some("index.js")).is_empty());
+    }
+
     #[test]
     fn stamps_verified_support_into_the_loader_manifest() {
         let manifest = ModulesManifest {

From b15be9c8ce695246fe6bbd8d3d6981a429b38ed2 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 23:36:14 +0200
Subject: [PATCH 11/14] perf(loader): prefetch every script of multi-file
 modules

---
 src/jsHelper/modularLoader/index.ts          | 4 ++++
 src/jsHelper/modularLoader/registry.test.mts | 8 +++++++-
 src/jsHelper/modularLoader/registry.ts       | 1 +
 src/jsHelper/modularLoader/types.ts          | 3 +++
 4 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/jsHelper/modularLoader/index.ts b/src/jsHelper/modularLoader/index.ts
index 990653cf2d..dc2f29602f 100644
--- a/src/jsHelper/modularLoader/index.ts
+++ b/src/jsHelper/modularLoader/index.ts
@@ -73,8 +73,12 @@ async function cssFromSource(text: string): Promise<CSSStyleSheet | string> {
 
 const prefetchedCss = new Map<string, Promise<string>>();
 
+const prefetchedJs = new Set<string>();
+
 function prefetch(path: string, kind: "js" | "css"): void {
 	if (kind === "js") {
+		if (prefetchedJs.has(path)) return;
+		prefetchedJs.add(path);
 		const link = document.createElement("link");
 		link.rel = "modulepreload";
 		link.href = path;
diff --git a/src/jsHelper/modularLoader/registry.test.mts b/src/jsHelper/modularLoader/registry.test.mts
index 648abf6810..5f7919d1b1 100644
--- a/src/jsHelper/modularLoader/registry.test.mts
+++ b/src/jsHelper/modularLoader/registry.test.mts
@@ -767,7 +767,11 @@ describe("boot load order and prefetch", () => {
 		const r = new Registry(
 			manifest([
 				mod("stdlib", "1.0.0"),
-				mod("mixer", "1.0.0", { hasMixins: true, entries: { js: "index.js", css: "index.css" } }),
+				mod("mixer", "1.0.0", {
+					hasMixins: true,
+					entries: { js: "index.js", css: "index.css" },
+					preload: ["load.js", "src/util.js"],
+				}),
 				mod("off", "1.0.0"),
 				mod("needs-off", "1.0.0", { dependencies: { off: "^1.0.0" } }),
 				mod("after-needs-off", "1.0.0", { dependencies: { "needs-off": "^1.0.0" } }),
@@ -785,6 +789,8 @@ describe("boot load order and prefetch", () => {
 			"js:/modules/theme-b/index.js",
 			"css:/modules/theme-b/index.css",
 			"js:/modules/stdlib/index.js",
+			"js:/modules/mixer/load.js",
+			"js:/modules/mixer/src/util.js",
 			"css:/modules/mixer/index.css",
 		]);
 	});
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index 9f0e72320b..09d5151aab 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -319,6 +319,7 @@ export class Registry {
 			}
 			if (this.localFiles.has(id)) continue;
 			if (m.entries.js && !m.hasMixins) this.effects.prefetch(entryUrl(id, m.entries.js), "js");
+			for (const script of m.preload ?? []) this.effects.prefetch(entryUrl(id, script), "js");
 			if (m.entries.css) this.effects.prefetch(entryUrl(id, m.entries.css), "css");
 		}
 	}
diff --git a/src/jsHelper/modularLoader/types.ts b/src/jsHelper/modularLoader/types.ts
index 01d269f0df..39ee36a8db 100644
--- a/src/jsHelper/modularLoader/types.ts
+++ b/src/jsHelper/modularLoader/types.ts
@@ -29,6 +29,9 @@ export interface ModuleMetadata {
 
 export interface ManifestModule extends ModuleMetadata {
 	identifier: string;
+	// Every other script of a staged multi-file module, relative to its
+	// directory (absent in manifests from older CLIs).
+	preload?: string[];
 }
 
 export type Classmap = Record<string, unknown>;

From 93031bc07464054aa0b4a4249a5833f77509091d Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 23:45:32 +0200
Subject: [PATCH 12/14] fix(apply): preload only importable scripts of modules
 with a JS entry

---
 rust/crates/spicetify/src/module/stage.rs | 31 ++++++++++++++++++-----
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/rust/crates/spicetify/src/module/stage.rs b/rust/crates/spicetify/src/module/stage.rs
index 13dc838ab7..8d1e9620f5 100644
--- a/rust/crates/spicetify/src/module/stage.rs
+++ b/rust/crates/spicetify/src/module/stage.rs
@@ -286,22 +286,25 @@ fn remap_source(
 }
 
 // module_scripts lists a staged module's JavaScript files other than its
-// entry, sorted, when it has more than one. Tests are left out.
+// entry, sorted, when it has a JS entry and more than one script. Tests,
+// specs, tool configs and hidden directories are left out.
 fn module_scripts(dir: &Path, entry: Option<&str>) -> Vec<String> {
     fn walk(root: &Path, dir: &Path, out: &mut Vec<String>) {
         let Ok(entries) = std::fs::read_dir(dir) else { return };
         for entry in entries.filter_map(std::result::Result::ok) {
             let path = entry.path();
+            let Some(name) = path.file_name().and_then(|n| n.to_str()) else { continue };
             if path.is_dir() {
-                walk(root, &path, out);
+                if !name.starts_with('.') && name != "__tests__" {
+                    walk(root, &path, out);
+                }
                 continue;
             }
-            let Some(name) = path.file_name().and_then(|n| n.to_str()) else { continue };
             let script = path
                 .extension()
                 .and_then(|e| e.to_str())
                 .is_some_and(|e| e.eq_ignore_ascii_case("js") || e.eq_ignore_ascii_case("mjs"));
-            if !script || name.contains(".test.") {
+            if !script || [".test.", ".spec.", ".config."].iter().any(|part| name.contains(part)) {
                 continue;
             }
             if let Ok(relative) = path.strip_prefix(root) {
@@ -311,12 +314,15 @@ fn module_scripts(dir: &Path, entry: Option<&str>) -> Vec<String> {
             }
         }
     }
+    let Some(entry) = entry.map(|e| e.trim_start_matches("./")) else {
+        return Vec::new();
+    };
     let mut scripts = Vec::new();
     walk(dir, dir, &mut scripts);
     if scripts.len() < 2 {
         return Vec::new();
     }
-    scripts.retain(|script| Some(script.as_str()) != entry);
+    scripts.retain(|script| script != entry);
     scripts.sort();
     scripts
 }
@@ -564,26 +570,37 @@ mod tests {
     fn lists_the_other_scripts_of_a_multi_file_module() {
         let root = scratch("module-scripts");
         let tree = root.join("tree");
-        std::fs::create_dir_all(tree.join("src/webpack")).expect("tree dirs");
+        for dir in ["src/webpack", ".cache", "__tests__"] {
+            std::fs::create_dir_all(tree.join(dir)).expect("tree dirs");
+        }
         for file in [
             "index.js",
             "load.js",
             "src/webpack/index.js",
             "src/util.test.mjs",
+            "src/util.spec.js",
+            "vite.config.js",
+            ".cache/chunk.js",
+            "__tests__/a.js",
             "index.css",
             "index.js.map",
         ] {
             std::fs::write(tree.join(file), "").expect("tree file");
         }
         assert_eq!(
-            module_scripts(&tree, Some("index.js")),
+            module_scripts(&tree, Some("./index.js")),
             vec!["load.js", "src/webpack/index.js"]
         );
+        assert!(
+            module_scripts(&tree, None).is_empty(),
+            "without a JS entry nothing imports the scripts"
+        );
 
         let single = root.join("single");
         std::fs::create_dir_all(&single).expect("single dir");
         std::fs::write(single.join("index.js"), "").expect("single entry");
         assert!(module_scripts(&single, Some("index.js")).is_empty());
+        std::fs::remove_dir_all(root).expect("cleanup");
     }
 
     #[test]

From 43061f78b5662a5dafa44ff8047a1ba53e1cdbf6 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 23:45:32 +0200
Subject: [PATCH 13/14] fix(loader): encode preloaded script paths

---
 src/jsHelper/modularLoader/index.ts    | 4 ----
 src/jsHelper/modularLoader/registry.ts | 4 +++-
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/src/jsHelper/modularLoader/index.ts b/src/jsHelper/modularLoader/index.ts
index dc2f29602f..990653cf2d 100644
--- a/src/jsHelper/modularLoader/index.ts
+++ b/src/jsHelper/modularLoader/index.ts
@@ -73,12 +73,8 @@ async function cssFromSource(text: string): Promise<CSSStyleSheet | string> {
 
 const prefetchedCss = new Map<string, Promise<string>>();
 
-const prefetchedJs = new Set<string>();
-
 function prefetch(path: string, kind: "js" | "css"): void {
 	if (kind === "js") {
-		if (prefetchedJs.has(path)) return;
-		prefetchedJs.add(path);
 		const link = document.createElement("link");
 		link.rel = "modulepreload";
 		link.href = path;
diff --git a/src/jsHelper/modularLoader/registry.ts b/src/jsHelper/modularLoader/registry.ts
index 09d5151aab..cc1c87e302 100644
--- a/src/jsHelper/modularLoader/registry.ts
+++ b/src/jsHelper/modularLoader/registry.ts
@@ -319,7 +319,9 @@ export class Registry {
 			}
 			if (this.localFiles.has(id)) continue;
 			if (m.entries.js && !m.hasMixins) this.effects.prefetch(entryUrl(id, m.entries.js), "js");
-			for (const script of m.preload ?? []) this.effects.prefetch(entryUrl(id, script), "js");
+			for (const script of m.preload ?? []) {
+				this.effects.prefetch(entryUrl(id, script.split("/").map(encodeURIComponent).join("/")), "js");
+			}
 			if (m.entries.css) this.effects.prefetch(entryUrl(id, m.entries.css), "css");
 		}
 	}

From d1517ef69860932f70425f9a211a38d30ff56ae7 Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Thu, 1 Oct 2026 23:57:17 +0200
Subject: [PATCH 14/14] fix(apply): keep pnpm dependencies in the preload list

---
 rust/crates/spicetify/src/module/stage.rs | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/rust/crates/spicetify/src/module/stage.rs b/rust/crates/spicetify/src/module/stage.rs
index 8d1e9620f5..f158ca1b7f 100644
--- a/rust/crates/spicetify/src/module/stage.rs
+++ b/rust/crates/spicetify/src/module/stage.rs
@@ -287,7 +287,8 @@ fn remap_source(
 
 // module_scripts lists a staged module's JavaScript files other than its
 // entry, sorted, when it has a JS entry and more than one script. Tests,
-// specs, tool configs and hidden directories are left out.
+// specs and tool configs are left out; hidden directories are kept because
+// pnpm installs dependencies under node_modules/.pnpm.
 fn module_scripts(dir: &Path, entry: Option<&str>) -> Vec<String> {
     fn walk(root: &Path, dir: &Path, out: &mut Vec<String>) {
         let Ok(entries) = std::fs::read_dir(dir) else { return };
@@ -295,7 +296,7 @@ fn module_scripts(dir: &Path, entry: Option<&str>) -> Vec<String> {
             let path = entry.path();
             let Some(name) = path.file_name().and_then(|n| n.to_str()) else { continue };
             if path.is_dir() {
-                if !name.starts_with('.') && name != "__tests__" {
+                if name != "__tests__" {
                     walk(root, &path, out);
                 }
                 continue;
@@ -570,7 +571,7 @@ mod tests {
     fn lists_the_other_scripts_of_a_multi_file_module() {
         let root = scratch("module-scripts");
         let tree = root.join("tree");
-        for dir in ["src/webpack", ".cache", "__tests__"] {
+        for dir in ["src/webpack", "node_modules/.pnpm/dep", "__tests__"] {
             std::fs::create_dir_all(tree.join(dir)).expect("tree dirs");
         }
         for file in [
@@ -580,7 +581,7 @@ mod tests {
             "src/util.test.mjs",
             "src/util.spec.js",
             "vite.config.js",
-            ".cache/chunk.js",
+            "node_modules/.pnpm/dep/index.js",
             "__tests__/a.js",
             "index.css",
             "index.js.map",
@@ -589,7 +590,7 @@ mod tests {
         }
         assert_eq!(
             module_scripts(&tree, Some("./index.js")),
-            vec!["load.js", "src/webpack/index.js"]
+            vec!["load.js", "node_modules/.pnpm/dep/index.js", "src/webpack/index.js"]
         );
         assert!(
             module_scripts(&tree, None).is_empty(),