@spicetify/kit 0.1.0

package/dist/dev.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * dev - hot-push a module into a running Spotify client.
+ *
+ * Watches the module's sources; on change it rebuilds and pushes the
+ * fresh bundle over the Chrome DevTools Protocol as a local install
+ * (Spicetify.Modules.installLocal), so nothing in the staged app bundle
+ * is touched and the loop is sub-second. Spotify must be running with
+ * --remote-debugging-port=<port>. Remove the override afterwards with
+ * Spicetify.Modules.removeLocal("<name>") (or from the manager page) to
+ * fall back to the staged copy.
+ */
+import { watch } from "node:fs";
+import path from "node:path";
+import { buildModule, readMetadata, resolveModuleDir } from "./build.js";
+import { loadConfig, resolveClassmap } from "./classmap.js";
+import { launchSpotify } from "./launch.js";
+import { formatPushResult, push, record } from "./push.js";
+// Re-exported for callers that imported it from here before the push extraction.
+export { formatPushResult } from "./push.js";
+const USAGE = "spicetify-kit dev <module> [--launch] [--port 9229] [--once] [--classmap <key|path>] [--out <dir>]\n" +
+    "  --launch   start (or reuse) Spotify with the remote-debugging port itself";
+export async function runDev(argv, cwd = process.cwd()) {
+    const moduleArg = argv.find((a) => !a.startsWith("--"));
+    const flag = (n) => {
+        const i = argv.indexOf(`--${n}`);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    if (!moduleArg)
+        throw new Error(USAGE);
+    const port = flag("port") ?? "9229";
+    const once = argv.includes("--once");
+    if (argv.includes("--launch"))
+        await launchSpotify(port);
+    const config = loadConfig(cwd);
+    const modulesDir = config.modulesDir ? path.resolve(cwd, config.modulesDir) : path.join(cwd, "modules");
+    const outDir = flag("out") ?? (config.outDir ? path.resolve(cwd, config.outDir) : path.join(cwd, "dist"));
+    const moduleDir = resolveModuleDir(moduleArg, modulesDir, cwd);
+    const id = readMetadata(moduleDir).name;
+    const resolved = await resolveClassmap({
+        flag: flag("classmap") ?? null,
+        config,
+        cwd,
+        refresh: argv.includes("--refresh"),
+    });
+    if (!resolved.path)
+        throw new Error("no classmap found (pass --classmap <key|path>)");
+    const cycle = async () => {
+        const started = Date.now();
+        let distDir;
+        try {
+            // Dev never blocks on standard findings: print them, push anyway.
+            distDir = await buildModule(moduleDir, outDir, resolved, cwd, { check: "warn" });
+        }
+        catch (e) {
+            console.error(`[dev] build failed: ${e.message}`);
+            return;
+        }
+        try {
+            const raw = await push(record(distDir, id), id, port);
+            const result = formatPushResult(raw);
+            const line = `[dev] ${id} ${result.message} (${Date.now() - started}ms)`;
+            if (result.ok)
+                console.log(line);
+            else
+                console.error(line);
+        }
+        catch (e) {
+            console.error(`[dev] push failed: ${e.message}`);
+        }
+    };
+    await cycle();
+    if (once)
+        return;
+    console.log(`[dev] watching ${moduleDir} (ctrl-c to stop; removeLocal("${id}") drops the override)`);
+    let timer;
+    let loggedDts = false;
+    watch(moduleDir, { recursive: true }, (_event, file) => {
+        if (!file)
+            return;
+        // The build regenerates classmap.d.ts into the source dir on every run;
+        // reacting to it would loop. Note the skip once so it is not a mystery.
+        if (file.endsWith(".d.ts")) {
+            if (!loggedDts) {
+                console.log("[dev] ignoring generated classmap.d.ts changes");
+                loggedDts = true;
+            }
+            return;
+        }
+        if (file.startsWith("."))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => void cycle(), 200);
+    });
+    // Keep the process alive while the watcher runs.
+    await new Promise(() => { });
+}

package/dist/from-theme.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * from-theme - migrate a classic spicetify theme (user.css + color.ini)
+ * into a v3 theme module.
+ *
+ * Theme modules are CSS-only modules: user.css becomes the css entry,
+ * color.ini ships alongside it and the loader applies the preferred
+ * scheme at load ([Section] names become switchable schemes). Previews
+ * are copied into assets/.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+const USAGE = 'spicetify-kit from-theme <classic-theme-dir> [--name <id>] [--author "..."] [--bare]';
+export async function runFromTheme(argv, cwd = process.cwd()) {
+    const source = argv.find((a) => !a.startsWith("--"));
+    const flag = (n) => {
+        const i = argv.indexOf(`--${n}`);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const bare = argv.includes("--bare");
+    if (!source)
+        throw new Error(USAGE);
+    const themeDir = path.resolve(cwd, source);
+    const userCss = path.join(themeDir, "user.css");
+    const colorIni = path.join(themeDir, "color.ini");
+    if (!existsSync(userCss) && !existsSync(colorIni)) {
+        throw new Error(`${themeDir} has neither user.css nor color.ini; not a classic theme`);
+    }
+    const name = flag("name") ??
+        path
+            .basename(themeDir)
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/^-+|-+$/g, "");
+    if (!/^[a-z][a-z0-9-]*$/.test(name))
+        throw new Error(`derived name "${name}" is not kebab-case; pass --name`);
+    const author = flag("author") ?? "spicetify";
+    const dir = bare ? path.join(cwd, "modules", name) : path.join(cwd, name);
+    if (existsSync(dir))
+        throw new Error(`${dir} already exists`);
+    mkdirSync(dir, { recursive: true });
+    const hasCss = existsSync(userCss);
+    if (hasCss)
+        cpSync(userCss, path.join(dir, "index.css"));
+    if (existsSync(colorIni))
+        cpSync(colorIni, path.join(dir, "color.ini"));
+    const previews = readdirSync(themeDir)
+        .filter((f) => /\.(png|jpe?g|gif|webp)$/i.test(f))
+        .sort();
+    if (previews.length) {
+        mkdirSync(path.join(dir, "assets"), { recursive: true });
+        for (const p of previews)
+            cpSync(path.join(themeDir, p), path.join(dir, "assets", p));
+    }
+    writeFileSync(path.join(dir, "metadata.json"), `${JSON.stringify({
+        name,
+        tags: ["theme"],
+        version: "0.1.0",
+        authors: [author],
+        description: `${path.basename(themeDir)} theme, migrated from the classic format`,
+        ...(previews.length ? { preview: `./assets/${previews[0]}` } : {}),
+        entries: hasCss ? { css: "index.css" } : {},
+        hasMixins: false,
+        dependencies: {},
+    }, null, "\t")}\n`);
+    if (!bare) {
+        writeFileSync(path.join(dir, "package.json"), `${JSON.stringify({
+            name,
+            private: true,
+            type: "module",
+            scripts: {
+                build: "spicetify-kit build .",
+                dev: "spicetify-kit dev .",
+            },
+            devDependencies: {
+                "@spicetify/kit": "^0.1.0",
+            },
+        }, null, "\t")}\n`);
+        writeFileSync(path.join(dir, ".gitignore"), "node_modules/\ndist/\n");
+    }
+    const rel = path.relative(cwd, dir) || ".";
+    console.log(`created ${rel}/ from ${path.basename(themeDir)}`);
+    console.log("notes:");
+    console.log("  - classic user.css targets classic class names; selectors may need updating for current clients");
+    if (existsSync(colorIni)) {
+        console.log("  - color.ini sections become switchable schemes (Spicetify.Modules.schemes/setScheme)");
+    }
+    if (!bare) {
+        console.log("next steps:");
+        console.log(`  cd ${rel} && npm install`);
+        console.log("  npm run dev        # hot-push into a running client");
+    }
+}

package/dist/install.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * install - sideload a packed module (or a dist dir) into a running client.
+ *
+ * One-shot CDP hot-push via Spicetify.Modules.installLocal, reusing the dev
+ * loop's push machinery. Nothing is written to the spicetify config folder.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { formatPushResult, push, record } from "./push.js";
+const USAGE = "spicetify-kit install <zip|dist-dir> [--port 9229]\n  (requires `unzip` on PATH for a .zip)";
+function unzipTo(zipPath, dest) {
+    try {
+        execFileSync("unzip", ["-q", "-o", zipPath, "-d", dest], { stdio: "ignore" });
+    }
+    catch {
+        throw new Error("`unzip` is required to install a .zip but was not found on PATH");
+    }
+}
+export async function runInstall(argv, cwd = process.cwd()) {
+    const target = argv.find((a) => !a.startsWith("--"));
+    const flag = (n) => {
+        const i = argv.indexOf(`--${n}`);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const port = flag("port") ?? "9229";
+    if (!target)
+        throw new Error(USAGE);
+    const abs = path.resolve(cwd, target);
+    if (!existsSync(abs))
+        throw new Error(`${target} not found`);
+    let distDir = abs;
+    let tmp = null;
+    if (statSync(abs).isFile() && abs.endsWith(".zip")) {
+        tmp = mkdtempSync(path.join(tmpdir(), "kit-install-"));
+        unzipTo(abs, tmp);
+        distDir = tmp;
+    }
+    try {
+        if (!existsSync(path.join(distDir, "metadata.json"))) {
+            throw new Error(`no metadata.json in ${target} (not a built/packed module)`);
+        }
+        const meta = JSON.parse(readFileSync(path.join(distDir, "metadata.json"), "utf8"));
+        const id = meta.name;
+        const raw = await push(record(distDir, id), id, port);
+        const result = formatPushResult(raw);
+        console.log(`[install] ${id} ${result.message}`);
+        if (!result.ok)
+            process.exitCode = 1;
+    }
+    finally {
+        if (tmp)
+            rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/launch.js

@@ -0,0 +1,122 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * launch - bring up a debuggable Spotify client for the dev loop.
+ *
+ * Discovers the Spotify binary per platform (mirroring the CLI's
+ * restart.go), reuses an already-debuggable instance when one is running
+ * on the target port, otherwise kills the running client and spawns a
+ * fresh one with --remote-debugging-port. AppX (Microsoft Store) installs
+ * are unsupported: the kit cannot supply the spicetify-staged
+ * --app-directory without reading CLI config, so launching would yield an
+ * unpatched client where hot-push fails right after a "successful" launch.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const APPX_MESSAGE = "Spotify is a Microsoft Store (AppX) install, which the kit cannot launch with a debug port: " +
+    "it needs the spicetify-staged --app-directory, which only the CLI knows. " +
+    "Start Spotify yourself with --remote-debugging-port, or run `spicetify-kit dev` without --launch.";
+// which returns the resolved path of a command on PATH, or null.
+function defaultWhich(cmd) {
+    try {
+        const out = execFileSync(process.platform === "win32" ? "where" : "which", [cmd], {
+            encoding: "utf8",
+        });
+        return out.split(/\r?\n/).find(Boolean) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// discoverSpotify resolves the launchable Spotify per platform. Pure over
+// its injected probes so it can be unit-tested with a fixture path table.
+export function discoverSpotify(platform = process.platform, env = process.env, exists = existsSync, which = defaultWhich) {
+    if (platform === "darwin") {
+        const app = "/Applications/Spotify.app";
+        if (exists(app))
+            return { kind: "macos", app };
+        throw new Error(`Spotify not found at ${app}. Install Spotify, or start it yourself with --remote-debugging-port and run dev without --launch.`);
+    }
+    if (platform === "win32") {
+        // win32.join so paths use backslashes on any host (matters for tests).
+        const exe = path.win32.join(env.APPDATA ?? "", "Spotify", "Spotify.exe");
+        if (exists(exe))
+            return { kind: "windows", exe };
+        const appx = path.win32.join(env.LOCALAPPDATA ?? "", "Microsoft", "WindowsApps", "Spotify.exe");
+        if (exists(appx))
+            return { kind: "appx" };
+        throw new Error(`Spotify.exe not found (looked in ${exe} and ${appx}). Install the standalone Spotify, or start it yourself with --remote-debugging-port.`);
+    }
+    const onPath = which("spotify");
+    if (onPath)
+        return { kind: "linux", exe: onPath };
+    throw new Error("'spotify' not found on PATH. Install Spotify, or start it yourself with --remote-debugging-port and run dev without --launch.");
+}
+// hasXpuiTarget reports whether a debuggable xpui page is already listening
+// on the port, so an already-good client is reused rather than killed.
+export async function hasXpuiTarget(port) {
+    try {
+        const res = await fetch(`http://localhost:${port}/json/list`);
+        if (!res.ok)
+            return false;
+        const targets = (await res.json());
+        return targets.some((t) => t.url?.includes("xpui"));
+    }
+    catch {
+        return false;
+    }
+}
+// waitForTarget polls until an xpui debug target appears or the timeout
+// fires; the timeout error names the port and the flag so the remedy is
+// obvious.
+export async function waitForTarget(port, timeoutMs = 30_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await hasXpuiTarget(port))
+            return;
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    throw new Error(`timed out waiting for a Spotify xpui debug target on port ${port}. ` +
+        `Confirm Spotify started with --remote-debugging-port=${port} and that spicetify apply has staged the v3 loader.`);
+}
+function killRunning(platform) {
+    try {
+        if (platform === "win32")
+            execFileSync("taskkill", ["/F", "/IM", "Spotify.exe"], { stdio: "ignore" });
+        else
+            execFileSync("pkill", ["-x", platform === "darwin" ? "Spotify" : "spotify"], { stdio: "ignore" });
+    }
+    catch {
+        // Not running is fine.
+    }
+}
+function spawnDetached(cmd, args) {
+    // Detached + unref'd so the client survives the kit process (matters on
+    // Linux/Windows; macOS `open` already returns immediately).
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    child.unref();
+}
+// launchSpotify reuses a good client, otherwise (re)starts one with the
+// debug port and waits for its xpui target. Returns "reused" or "launched".
+export async function launchSpotify(port, log = console.log, platform = process.platform) {
+    if (await hasXpuiTarget(port)) {
+        log(`[dev] reusing the Spotify client already debuggable on port ${port}`);
+        return "reused";
+    }
+    const target = discoverSpotify(platform);
+    if (target.kind === "appx")
+        throw new Error(APPX_MESSAGE);
+    log(`[dev] (re)starting Spotify with --remote-debugging-port=${port}`);
+    killRunning(platform);
+    await new Promise((r) => setTimeout(r, 1500));
+    const portFlag = `--remote-debugging-port=${port}`;
+    if (target.kind === "macos")
+        spawnDetached("open", ["-a", target.app, "--args", portFlag]);
+    else
+        spawnDetached(target.exe, [portFlag]);
+    await waitForTarget(port);
+    return "launched";
+}

package/dist/pack.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * pack - zip a built module into <name>@<version>.zip and print its
+ * sha256, ready to upload as a release artifact.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+const USAGE = "spicetify-kit pack <dist-dir> [--out <dir>]";
+export async function runPack(argv, cwd = process.cwd()) {
+    const distDir = argv.find((a) => !a.startsWith("--"));
+    const outIdx = argv.indexOf("--out");
+    if (!distDir)
+        throw new Error(USAGE);
+    const outDir = outIdx >= 0 ? argv[outIdx + 1] : ".";
+    const abs = path.resolve(cwd, distDir);
+    const meta = JSON.parse(readFileSync(path.join(abs, "metadata.json"), "utf8"));
+    if (!meta.name || !meta.version)
+        throw new Error(`${distDir}/metadata.json must set name and version`);
+    const zipPath = path.resolve(cwd, outDir, `${meta.name}@${meta.version}.zip`);
+    rmSync(zipPath, { force: true });
+    // Zip contents at the archive root (metadata.json at top level), the
+    // layout installLocal and the module installers expect.
+    execFileSync("zip", ["-qr", zipPath, "."], { cwd: abs });
+    const digest = createHash("sha256").update(readFileSync(zipPath)).digest("hex");
+    console.log(`${zipPath}\nsha256:${digest}`);
+}

package/dist/push.js

@@ -0,0 +1,211 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+/**
+ * push - shared CDP hot-push machinery for the dev loop and install.
+ *
+ * Builds the LocalModuleRecord a dist dir installs as (metadata + files +
+ * sidecar), finds the client's xpui debug target, and runs
+ * Spicetify.Modules.installLocal in the client so nothing in the staged app
+ * bundle is touched.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+// localStorage quota is ~5 MB for the xpui origin, shared with Spotify's own
+// keys and other local modules, so thresholds are conservative. Counted in
+// UTF-16 code units (JSON.stringify(...).length), the unit the quota counts.
+const WARN_BYTES = 4_000_000;
+const ABORT_BYTES = 4_500_000;
+export function estimateRecordSize(rec) {
+    return JSON.stringify(rec).length;
+}
+function largestFiles(rec, n = 3) {
+    return Object.entries(rec.files ?? {})
+        .map(([f, c]) => [f, c.length])
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, n)
+        .map(([f, len]) => `${f} (~${Math.round(len / 1024)}KB)`)
+        .join(", ");
+}
+// checkQuota estimates the serialized install size before the socket opens:
+// over the abort threshold it refuses with guidance, over the warn threshold
+// it prints the size and the largest files.
+export function checkQuota(rec, log = console.warn) {
+    const size = estimateRecordSize(rec);
+    if (size >= ABORT_BYTES) {
+        throw new Error(`install is ~${Math.round(size / 1024)}KB, over the ~${Math.round(ABORT_BYTES / 1024)}KB local-install ` +
+            `limit (localStorage is shared across the whole client). Largest: ${largestFiles(rec)}. ` +
+            "Sourcemaps and assets are already excluded — trim shipped chunks or split the module.");
+    }
+    if (size >= WARN_BYTES) {
+        log(`[push] warning: install is ~${Math.round(size / 1024)}KB, approaching the local-install limit. ` +
+            `Largest: ${largestFiles(rec)}`);
+    }
+}
+// interpretResult turns a CDP Runtime.evaluate response into a value or a
+// named error. A client-side QuotaExceededError arrives via exceptionDetails
+// (not the resolved value), so it is detected and translated here.
+export function interpretResult(msg) {
+    const ex = msg.result?.exceptionDetails;
+    if (ex) {
+        const text = ex.exception?.description ?? ex.text ?? JSON.stringify(ex);
+        if (/quota/i.test(text)) {
+            return {
+                error: "client rejected the install: localStorage quota exceeded (shared across the whole client). " +
+                    "Trim shipped chunks or split the module.",
+            };
+        }
+        return { error: `client evaluation error: ${text.slice(0, 200)}` };
+    }
+    return { value: msg.result?.result?.value ?? JSON.stringify(msg) };
+}
+// record builds the install payload from a dist dir. Maps and asset dirs stay
+// out of localStorage; metadata rides separately (it is stamped with the id).
+export function record(distDir, id) {
+    const metadata = JSON.parse(readFileSync(path.join(distDir, "metadata.json"), "utf8"));
+    metadata.identifier = id;
+    const sidecar = JSON.parse(readFileSync(path.join(distDir, "spicetify-module.json"), "utf8"));
+    const files = {};
+    for (const f of readdirSync(distDir)) {
+        if (f === "metadata.json" || f.endsWith(".map"))
+            continue;
+        if (statSync(path.join(distDir, f)).isDirectory())
+            continue;
+        files[f] = readFileSync(path.join(distDir, f), "utf8");
+    }
+    return { metadata, files, sidecar };
+}
+// stampRecord appends an execution stamp to the record's js entry. The push
+// asserts the stamp after enable, turning "the client says loaded" into "the
+// pushed code demonstrably ran". A loaded flag alone can be a stale instance:
+// the dev loop once reported a build live whose code had never executed.
+// Returns false when the record has no js entry to stamp (css-only themes).
+export function stampRecord(rec, id, nonce) {
+    const entry = rec.metadata.entries?.js;
+    if (!entry || typeof rec.files[entry] !== "string")
+        return false;
+    rec.files[entry] +=
+        `\nglobalThis.__spicetifyPushStamps = Object.assign(globalThis.__spicetifyPushStamps ?? {}, ${JSON.stringify({ [id]: nonce })});\n`;
+    return true;
+}
+export function newNonce() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+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.");
+    }
+    return target.webSocketDebuggerUrl;
+}
+export function push(rec, id, port) {
+    // Stamp before the quota check so the stamp's own bytes are counted.
+    const nonce = newNonce();
+    const stamped = stampRecord(rec, id, nonce);
+    // Refuse an oversized install before opening the socket (U7), so the failure
+    // is a named cause here rather than an opaque client-side quota error.
+    checkQuota(rec);
+    // 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;
+		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);
+		// 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");
+		const isTheme = (mid) => ((M.manifest?.modules?.find((m) => m.identifier === mid)?.tags) ?? []).includes("theme");
+		for (const other of before) {
+			if (pushedIsTheme && isTheme(other)) continue;
+			const s = M.list().find((m) => m.identifier === other);
+			if (s && !s.loaded) await M.enable(other).catch(() => {});
+		}
+		const s = M.list().find((m) => m.identifier === id);
+		const stampLive = ${stamped ? `globalThis.__spicetifyPushStamps?.[id] === ${JSON.stringify(nonce)}` : "null"};
+		return JSON.stringify({
+			loaded: s?.loaded ?? false,
+			failed: M.report?.failed?.[id] ?? null,
+			stamp: ${stamped ? '(stampLive ? "live" : "stale")' : '"unstamped"'},
+			hadPrevious,
+		});
+	})()`;
+    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);
+    });
+}
+// Turn the raw client-side push result into an honest, actionable line.
+export function formatPushResult(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, message: `unexpected push result (not JSON): ${raw}` };
+    }
+    if (parsed.error === "loader not ready") {
+        return {
+            ok: false,
+            message: "the v3 loader is not staged in this client (Spicetify.Modules is absent). " +
+                "Run `spicetify apply` with v3 modules installed, then retry.",
+        };
+    }
+    if (parsed.failed)
+        return { ok: false, message: `module loaded but failed: ${parsed.failed}` };
+    if (parsed.loaded !== true)
+        return { ok: false, message: "installed but not loaded" };
+    // The loaded flag alone is not proof the pushed code runs; the stamp is.
+    if (parsed.stamp === "stale") {
+        return {
+            ok: false,
+            message: "installed, but the pushed code did NOT execute — a stale instance is still live. " +
+                "Restart the client (or removeLocal, then push again) before trusting any verification.",
+        };
+    }
+    const remount = parsed.hadPrevious
+        ? " — UI mounted before the push may still be the old build; re-navigate to its surface to remount"
+        : "";
+    if (parsed.stamp === "live")
+        return { ok: true, message: `loaded, pushed build verified executing${remount}` };
+    // css-only records carry no executable entry to stamp.
+    if (parsed.stamp === "unstamped")
+        return { ok: true, message: `loaded (css-only, no execution stamp)${remount}` };
+    return { ok: true, message: "loaded" };
+}