@spicetify/kit 0.3.0 → 0.4.0

package/dist/push.js

@@ -92,15 +92,140 @@ export function stampRecord(rec, id, nonce) {
 export function newNonce() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
+export const DEFAULT_PORT = "9229";
+// resolvePort picks the CDP port: an explicit --port, then SPICETIFY_CDP_PORT
+// (shared with the monorepo's maintainer scripts), then the default.
+export function resolvePort(flag, env = process.env) {
+    return flag ?? env.SPICETIFY_CDP_PORT ?? DEFAULT_PORT;
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+// classifyDevtools decides who owns a DevTools endpoint from its /json/version
+// and /json/list bodies. Spotify's CEF user agent carries "Spotify/<version>";
+// anything else (the Node inspector, wrangler, a browser) is a foreign listener
+// that would make Spotify fail to bind the port.
+export function classifyDevtools(version, targets) {
+    if (!/Spotify\//.test(String(version["User-Agent"] ?? ""))) {
+        const first = targets[0];
+        const what = String(version.Browser || first?.title || first?.type || "an unknown DevTools endpoint");
+        return { state: "other", what };
+    }
+    for (const t of targets) {
+        if (typeof t.url === "string" && t.url.includes("xpui") && typeof t.webSocketDebuggerUrl === "string") {
+            return { state: "xpui", ws: t.webSocketDebuggerUrl };
+        }
+    }
+    return { state: "spotify" };
+}
+// probePort reports whether the port is free, held by Spotify (with or without
+// its xpui page loaded yet), held by something else, or answering in a way it
+// cannot identify (a non-HTTP listener, or a client still binding the port).
+export async function probePort(port) {
+    let version;
+    try {
+        const res = await fetch(`http://localhost:${port}/json/version`, { signal: AbortSignal.timeout(2_000) });
+        if (!res.ok)
+            return { state: "unknown" };
+        const body = await res.json();
+        version = isRecord(body) ? body : {};
+    }
+    catch (e) {
+        const code = e.cause?.code;
+        return code === "ECONNREFUSED" ? { state: "free" } : { state: "unknown" };
+    }
+    let targets = [];
+    try {
+        const res = await fetch(`http://localhost:${port}/json/list`, { signal: AbortSignal.timeout(2_000) });
+        const body = res.ok ? await res.json() : [];
+        if (Array.isArray(body))
+            targets = body.filter(isRecord);
+    }
+    catch {
+        /* version answered; an unreadable list classifies from the version alone */
+    }
+    return classifyDevtools(version, targets);
+}
+export function portInUseMessage(port, what) {
+    return (`port ${port} is already in use by ${what}, not Spotify. ` +
+        "Node's inspector (node --inspect, wrangler dev) defaults to 9229 too. " +
+        "Stop that process, or pick another port with --port <n> or SPICETIFY_CDP_PORT=<n>.");
+}
 export async function wsUrl(port) {
-    const res = await fetch(`http://localhost:${port}/json/list`);
-    const targets = (await res.json());
-    const target = targets.find((t) => t.url?.includes("xpui"));
-    if (!target?.webSocketDebuggerUrl) {
-        throw new Error(`no xpui debug target on port ${port}. Start Spotify with --remote-debugging-port=${port} ` +
-            "(or pass --launch), and ensure `spicetify apply` has staged the v3 loader.");
+    const probe = await probePort(port);
+    if (probe.state === "xpui")
+        return probe.ws;
+    if (probe.state === "other")
+        throw new Error(portInUseMessage(port, probe.what));
+    if (probe.state === "spotify") {
+        throw new Error(`Spotify is listening on port ${port} but has no xpui page yet. ` +
+            "Wait for it to finish starting, and ensure `spicetify apply` has staged the v3 loader.");
     }
-    return target.webSocketDebuggerUrl;
+    if (probe.state === "unknown") {
+        throw new Error(`port ${port} answered, but not as a Spotify DevTools endpoint; retry once Spotify has started.`);
+    }
+    throw new Error(`no Spotify listening on port ${port}. Start it with --remote-debugging-port=${port}, ` +
+        "or run `spicetify-kit dev`, which starts it for you.");
+}
+// A freshly launched client exposes its xpui target before the loader has
+// booted, so client-side code waits up to 10s for Spicetify.Modules.
+const AWAIT_LOADER = `let M = globalThis.Spicetify?.Modules;
+		for (let i = 0; !M && i < 100; i++) {
+			await new Promise((r) => setTimeout(r, 100));
+			M = globalThis.Spicetify?.Modules;
+		}`;
+// evaluate runs an expression in the xpui page over CDP and resolves with its
+// string value.
+export function evaluate(port, expr, timeoutMs = 15_000) {
+    return new Promise((resolve, reject) => {
+        void wsUrl(port).then((url) => {
+            let ws;
+            try {
+                ws = new WebSocket(url);
+            }
+            catch (e) {
+                reject(new Error(`could not open the client websocket: ${e.message}`));
+                return;
+            }
+            const timer = setTimeout(() => {
+                ws.close();
+                reject(new Error("client evaluation timed out"));
+            }, timeoutMs);
+            ws.addEventListener("error", (e) => {
+                clearTimeout(timer);
+                reject(new Error(`websocket error: ${String(e.message ?? e)}`));
+            });
+            // A settled promise ignores this; it only fires for a socket the client
+            // closed before answering (for instance Spotify quitting mid-push).
+            ws.addEventListener("close", () => {
+                clearTimeout(timer);
+                reject(new Error("the client closed the connection before answering"));
+            });
+            ws.addEventListener("open", () => {
+                ws.send(JSON.stringify({
+                    id: 1,
+                    method: "Runtime.evaluate",
+                    params: { expression: expr, awaitPromise: true, returnByValue: true },
+                }));
+            });
+            ws.addEventListener("message", (ev) => {
+                let msg;
+                try {
+                    msg = JSON.parse(String(ev.data));
+                }
+                catch {
+                    return;
+                }
+                if (msg.id !== 1)
+                    return;
+                clearTimeout(timer);
+                ws.close();
+                const outcome = interpretResult(msg);
+                if ("error" in outcome)
+                    reject(new Error(outcome.error));
+                else
+                    resolve(outcome.value);
+            });
+        }, reject);
+    });
 }
 export function push(rec, id, port) {
     // Stamp before the quota check so the stamp's own bytes are counted.
@@ -112,14 +237,18 @@ export function push(rec, id, port) {
     // The whole exchange runs in the client: disable the old instance, install
     // the fresh content, and re-enable anything the unload cascade took down.
     const expr = `(async () => {
-		const M = globalThis.Spicetify?.Modules;
+		${AWAIT_LOADER}
 		if (!M) return JSON.stringify({ error: "loader not ready" });
 		const rec = ${JSON.stringify(rec)};
 		const id = ${JSON.stringify(id)};
 		const before = M.list().filter((m) => m.loaded).map((m) => m.identifier);
 		const hadPrevious = before.includes(id);
-		await M.disable(id).catch(() => {});
-		await M.installLocal(id, rec);
+		const installed = await M.installLocal(id, rec);
+		// installLocal keeps a module the client has marked disabled off. Pushing
+		// it is an explicit request to run it, so load it for this session;
+		// reload is transient, so the persisted choice still applies after removal.
+		const reenabled = installed?.disabled === true;
+		if (reenabled) await (M.reload ?? M.enable)(id);
 		// Re-enabling a theme the loader just unloaded would fight the
 		// single-active-theme invariant and knock the pushed theme back off.
 		const pushedIsTheme = (rec.metadata.tags ?? []).includes("theme");
@@ -136,40 +265,54 @@ export function push(rec, id, port) {
 			failed: M.report?.failed?.[id] ?? null,
 			stamp: ${stamped ? '(stampLive ? "live" : "stale")' : '"unstamped"'},
 			hadPrevious,
+			reenabled,
 		});
 	})()`;
-    return new Promise((resolve, reject) => {
-        void wsUrl(port).then((url) => {
-            const ws = new WebSocket(url);
-            const timer = setTimeout(() => {
-                ws.close();
-                reject(new Error("push timed out"));
-            }, 15_000);
-            ws.addEventListener("error", (e) => {
-                clearTimeout(timer);
-                reject(new Error(`websocket error: ${String(e.message ?? e)}`));
-            });
-            ws.addEventListener("open", () => {
-                ws.send(JSON.stringify({
-                    id: 1,
-                    method: "Runtime.evaluate",
-                    params: { expression: expr, awaitPromise: true, returnByValue: true },
-                }));
-            });
-            ws.addEventListener("message", (ev) => {
-                const msg = JSON.parse(String(ev.data));
-                if (msg.id !== 1)
-                    return;
-                clearTimeout(timer);
-                ws.close();
-                const outcome = interpretResult(msg);
-                if ("error" in outcome)
-                    reject(new Error(outcome.error));
-                else
-                    resolve(outcome.value);
-            });
-        }, reject);
-    });
+    return evaluate(port, expr);
+}
+// removeLocal drops a hot-pushed override so the client falls back to the
+// staged or store-installed copy.
+export async function removeLocal(id, port) {
+    const raw = await evaluate(port, `(async () => {
+		${AWAIT_LOADER}
+		if (!M?.removeLocal) return JSON.stringify({ error: "loader not ready" });
+		const id = ${JSON.stringify(id)};
+		const had = M.list().some((m) => m.identifier === id && m.local) ||
+			(M.listLocal?.() ?? []).some((r) => r?.metadata?.identifier === id);
+		const out = await M.removeLocal(id);
+		return JSON.stringify({ had, out: out ?? null });
+	})()`);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        parsed = null;
+    }
+    if (isRecord(parsed) && parsed.error) {
+        throw new Error("the v3 loader is not staged in this client (Spicetify.Modules is absent)");
+    }
+    if (!isRecord(parsed) || typeof parsed.had !== "boolean") {
+        throw new Error(`unexpected removeLocal result: ${raw.slice(0, 200)}`);
+    }
+    const out = isRecord(parsed.out) ? parsed.out : {};
+    if (out.requiresRestart === true)
+        return { kind: "requires-restart" };
+    if (typeof out.revertedTo === "string")
+        return { kind: "reverted", version: out.revertedTo };
+    return parsed.had ? { kind: "removed" } : { kind: "none" };
+}
+export function formatRemoveOutcome(id, outcome) {
+    switch (outcome.kind) {
+        case "none":
+            return `${id} has no local override to remove`;
+        case "removed":
+            return `removed the local override of ${id} (no staged copy, so it is no longer installed)`;
+        case "reverted":
+            return `removed the local override of ${id}; the client is back on the installed ${outcome.version}`;
+        case "requires-restart":
+            return `removed the local override of ${id}; restart Spotify to finish reverting it`;
+    }
 }
 // Turn the raw client-side push result into an honest, actionable line.
 export function formatPushResult(raw) {
@@ -199,9 +342,9 @@ export function formatPushResult(raw) {
                 "Restart the client (or removeLocal, then push again) before trusting any verification.",
         };
     }
-    const remount = parsed.hadPrevious
+    const remount = (parsed.hadPrevious
         ? " — UI mounted before the push may still be the old build; re-navigate to its surface to remount"
-        : "";
+        : "") + (parsed.reenabled ? " (it was disabled in the client; the push turned it back on)" : "");
     if (parsed.stamp === "live")
         return { ok: true, message: `loaded, pushed build verified executing${remount}` };
     // css-only records carry no executable entry to stamp.

package/dist/remove.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * remove - drop a hot-pushed local override from a running client, so it
+ * falls back to the staged or store-installed copy. Takes a module directory
+ * (its metadata.json names the id) or the id itself.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { flagValue } from "./args.js";
+import { formatRemoveOutcome, removeLocal, resolvePort } from "./push.js";
+const USAGE = "spicetify-kit remove <module-dir|id> [--port 9229]";
+// moduleId reads the id from <target>/metadata.json when target is a module
+// directory, and otherwise treats target as the id.
+export function moduleId(target, cwd) {
+    const meta = path.join(path.resolve(cwd, target), "metadata.json");
+    if (!existsSync(meta))
+        return target;
+    const name = JSON.parse(readFileSync(meta, "utf8")).name;
+    if (typeof name !== "string" || !name)
+        throw new Error(`${meta} has no "name" to identify the module by`);
+    return name;
+}
+export async function runRemove(argv, cwd = process.cwd()) {
+    const target = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--port");
+    if (!target || argv.includes("--help") || argv.includes("-h")) {
+        console.log(USAGE);
+        if (!target)
+            process.exitCode = 1;
+        return;
+    }
+    const port = resolvePort(flagValue(argv, "port"));
+    const id = moduleId(target, cwd);
+    console.log(`[remove] ${formatRemoveOutcome(id, await removeLocal(id, port))}`);
+}

package/dist/stdlib-boundary.js

@@ -7,7 +7,7 @@ import path from "node:path";
 export const STDLIB_BOUNDARY_WARNING_RULES = ["ambient-client", "client-dom", "direct-map"];
 const SOURCE_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".ts", ".tsx"]);
 const STYLE_EXTENSIONS = new Set([".css", ".scss"]);
-const PUBLIC_STDLIB_IMPORT = /^\/modules\/stdlib\/(?:mod\.(?:js|ts)|lib\/primitives(?:-classes|-vanilla)?\.(?:js|ts|tsx))$/;
+const PUBLIC_STDLIB_IMPORT = /^\/modules\/stdlib\/(?:(?:mod|query)\.(?:js|ts)|lib\/primitives(?:-classes|-vanilla)?\.(?:js|ts|tsx))$/;
 const CLIENT_DOM_PATTERN = /(?:^|[^A-Za-z0-9_-])(?:Root__|main-[A-Za-z]|player-controls__|playback-progressbar|npv-)|\[data-testid(?:=|\])/;
 const posix = (value) => value.split(path.sep).join("/");
 const lineAt = (text, index) => text.slice(0, index).split("\n").length;
@@ -98,7 +98,7 @@ export function inspectStdlibBoundaryFile(file, text) {
                 file: normalizedFile,
                 line: lineAt(source, match.index),
                 rule: "private-stdlib-import",
-                detail: `${match[1]} is private; import through /modules/stdlib/mod.js or the primitives kit`,
+                detail: `${match[1]} is private; import through /modules/stdlib/mod.js, query.js, or the primitives kit`,
             });
         }
         const ambient = firstMatch(source, /\bSpicetify\s*(?:\?\.|\.)|\b(?:globalThis|window)\s*\.\s*Spicetify\b/);

package/dist/version.js

@@ -4,5 +4,5 @@
  */
 // Kept in lockstep with package.json by release-please. Scaffolds must depend
 // on the kit version that generated them, especially across pre-1.0 minors.
-export const KIT_VERSION = "0.3.0"; // x-release-please-version
+export const KIT_VERSION = "0.4.0"; // x-release-please-version
 export const KIT_DEPENDENCY_RANGE = `^${KIT_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@spicetify/kit",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Developer kit for spicetify v3 modules: scaffold, build, hot-push, and pack",
 	"license": "GPL-3.0-or-later",
 	"homepage": "https://github.com/spicetify/modules#readme",
@@ -25,7 +25,8 @@
 		"./from-theme": "./dist/from-theme.js",
 		"./check": "./dist/check.js",
 		"./vault": "./dist/vault.js",
-		"./install": "./dist/install.js"
+		"./install": "./dist/install.js",
+		"./remove": "./dist/remove.js"
 	},
 	"files": [
 		"bin",
@@ -39,7 +40,7 @@
 		"access": "public"
 	},
 	"spicetify": {
-		"stdlibVersion": "1.10.1"
+		"stdlibVersion": "1.13.0"
 	},
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
@@ -48,6 +49,7 @@
 	},
 	"dependencies": {
 		"rolldown": "^1.2.0",
-		"sass-embedded": "^1.80.0"
+		"sass-embedded": "^1.80.0",
+		"@tanstack/query-core": "5.103.0"
 	}
 }

package/vendor/classmaps/1030000/classmap-19f856aefd5.json

@@ -0,0 +1,109 @@
+{
+  "main": {
+    "topbar": {
+      "wrapper": "bQetA_KiP9n0DQVcGa7m",
+      "left": {
+        "button": {
+          "wrapper": "e-10860-legacy-button e-10860-button-tertiary--icon-only-medium",
+          "icon": {
+            "wrapper": "e-10860-icon e-10860-icon--auto-mirror"
+          }
+        },
+        "button_t": {
+          "wrapper": "e-10860-legacy-button e-10860-button-tertiary--icon-only-medium"
+        }
+      },
+      "right": {
+        "button": {
+          "wrapper": "e-10860-legacy-button e-10860-button-tertiary--condensed-all"
+        },
+        "button_t": {
+          "wrapper": "nR3ekhH3c1IU7dX9smcR"
+        },
+        "upgrade_button": {
+          "wrapper": "e-10860-legacy-button e-10860-legacy-button-primary"
+        }
+      }
+    },
+    "playbar": {
+      "widget": {},
+      "controls": {},
+      "buttons": {
+        "button": {
+          "wrapper": "e-10860-legacy-button e-10860-button-tertiary--icon-only-small",
+          "wrapper__active": "e-10860-legacy-button e-10860-legacy-button-primary",
+          "wrapper__indicator": "e-10860-button-primary__inner"
+        }
+      }
+    },
+    "navbar": {
+      "link": {
+        "wrapper": "xlH6FJnBzFT4l3TgUBre",
+        "container": "xlH6FJnBzFT4l3TgUBre",
+        "container__active": "ajKYUZPcNmFVzcAzzlwe"
+      }
+    },
+    "global_navbar": {},
+    "sidebar": {},
+    "panel": {}
+  },
+  "tracklist": {
+    "column_header": "e-10860-legacy-list-row__header"
+  },
+  "search_chips": {
+    "wrapper_wrapper": "e-10860-chip-group",
+    "wrapper": "e-10860-chip-group__component",
+    "container": "e-10860-chip-group__component",
+    "chip": "e-10860-legacy-chip"
+  },
+  "modal": {
+    "widget_generator": {
+      "container": "_XeAt3IgtZQepOYqU2g4",
+      "header": {
+        "container": "mnU1hqlaF5JIcrTxLnZF",
+        "close": "AslPcD0TRZBBGZofe58g"
+      },
+      "content": {
+        "container": "Xu_Z4l6TIOF1f5kDB9dt"
+      }
+    },
+    "track_credits": {
+      "container": "gtXQasDkhtg93wGk6yNG",
+      "header": {
+        "container": "nQ_c7yoZ2XOD6fWtmv18",
+        "close": "CaHvWv36mAu4x5QTKlb1"
+      },
+      "content": {
+        "container": "wYQNBdH2rNMGe_B4oumf"
+      }
+    }
+  },
+  "settings": {
+    "header": {
+      "container": "Hwax_pfCzrntLhnYXiqL"
+    },
+    "section": {
+      "container": "HdwEUcX8xijMdU7doYPt"
+    },
+    "button": {
+      "wrapper": "e-10860-legacy-button e-10860-legacy-button--small e-10860-legacy-button-secondary"
+    },
+    "text_input": "e-10860-form-input e-10860-form-control encore-text-body-medium"
+  },
+  "scrollable_text": {
+    "container": "e-10860-legacy-box e-10860-legacy-box--naked",
+    "wrapper": "e-10860-legacy-box"
+  },
+  "sort_box": {
+    "list": {
+      "button": "MYWr4UY4pKAAscUXvqrB"
+    }
+  },
+  "search_box": {
+    "container": "mlx0CgXAnGz0dADVsCdS",
+    "expand_button": "e-10860-legacy-button e-10860-button-tertiary--icon-only-medium aslJk0YypwKvyKXaBJcG"
+  },
+  "context_menu": {
+    "menu_item": "fmmygDM45MTS7I35OyLh"
+  }
+}