@needle-tools/engine 4.15.0-next.f391a30 → 4.16.0-next.35df6b8

package/plugins/vite/dependency-watcher.js

@@ -12,14 +12,14 @@ function log(...msg) {
 }
 
 /**
- * @param {string} command
- * @param {unknown} config
+ * @param {"build" | "serve"} command
+ * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  */
-export const needleDependencyWatcher = (command, config, userSettings) => {
-    if (command === "build") return;
+export const needleDependencyWatcher = (command, _config, userSettings) => {
+    if (command === "build") return null;
 
-    if (userSettings?.noDependencyWatcher === true) return;
+    if (userSettings?.noDependencyWatcher === true) return null;
 
     const dir = process.cwd();
     const packageJsonPath = path.join(dir, "package.json");
@@ -101,6 +101,7 @@ function watchPackageJson(server, projectDir, packageJsonPath, cachePath) {
     }, 1000);
 
     setInterval(() => {
+        if (!packageJson || lastEditTime === undefined) return;
         packageJsonStat = statSync(packageJsonPath);
         let modified = false;
         if (packageJsonStat.mtime > lastEditTime) {
@@ -120,14 +121,14 @@ function watchPackageJson(server, projectDir, packageJsonPath, cachePath) {
             let newPackageJson = /** @type {PackageJson} */ (JSON.parse(readFileSync(packageJsonPath, "utf8")));
             if (newPackageJson.dependencies) {
                 for (const key in newPackageJson.dependencies) {
-                    if (packageJson.dependencies[key] !== newPackageJson.dependencies[key] && newPackageJson.dependencies[key] !== undefined) {
+                    if (packageJson.dependencies?.[key] !== newPackageJson.dependencies[key] && newPackageJson.dependencies[key] !== undefined) {
                         log("Detected new dependency: " + key)
                         requireReload = true;
                         requireInstall = true;
                     }
                 }
             }
-            if (packageJson.devDependencies) {
+            if (packageJson.devDependencies && newPackageJson.devDependencies) {
                 for (const key in packageJson.devDependencies) {
                     if (packageJson.devDependencies[key] !== newPackageJson.devDependencies[key] && newPackageJson.devDependencies[key] !== undefined) {
                         log("Detected new devDependency: " + key)
@@ -153,6 +154,7 @@ function watchPackageJson(server, projectDir, packageJsonPath, cachePath) {
 
 /** @param {string} projectDir @param {PackageJson | undefined} packageJson @returns {boolean} */
 function testIfInstallIsRequired(projectDir, packageJson) {
+    if (!packageJson) return false;
     if (packageJson.dependencies) {
         for (const key in packageJson.dependencies) {
             // make sure the dependency is installed
@@ -264,7 +266,7 @@ async function restart(server, projectDir, cachePath) {
         needleLog("needle-dependency-watcher", "-----------------------------------------------");
     }
     catch (err) {
-        log("Error restarting server", err);
+        log("Error restarting server", String(err));
         isRunningRestart = false;
     }
 

package/plugins/vite/imports-logger.js

@@ -5,13 +5,13 @@ import fs from 'fs';
 /** @typedef {{ id: string, imports: GraphNode[], importedBy: GraphNode[] }} GraphNode */
 
 /**
- * @param {string} command
- * @param {unknown} config
+ * @param {"build" | "serve"} _command
+ * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  */
-export const needleImportsLogger = (command, config, userSettings) => {
+export const needleImportsLogger = (_command, _config, userSettings) => {
 
-    if (!userSettings.debugImportChains) return;
+    if (!userSettings.debugImportChains) return null;
 
     /** @type {{allNodes: Map<string, GraphNode>, graph: Record<string, unknown>}} */
     const graph = {
@@ -47,7 +47,7 @@ export const needleImportsLogger = (command, config, userSettings) => {
                 });
             }
 
-            if (!graph.allNodes.has(importer)) {
+            if (importer && !graph.allNodes.has(importer)) {
                 graph.allNodes.set(importer, {
                     id: importer,
                     imports: [],
@@ -56,16 +56,18 @@ export const needleImportsLogger = (command, config, userSettings) => {
             }
 
             const node = graph.allNodes.get(id);
-            const importerNode = graph.allNodes.get(importer);
-            if (!node.importedBy.includes(importerNode))
-                node.importedBy.push(importerNode);
-            if (!importerNode.imports.includes(node))
-                importerNode.imports.push(node);
+            const importerNode = importer ? graph.allNodes.get(importer) : undefined;
+            if (node && importerNode) {
+                if (!node.importedBy.includes(importerNode))
+                    node.importedBy.push(importerNode);
+                if (!importerNode.imports.includes(node))
+                    importerNode.imports.push(node);
+            }
 
             return;
         },
-        /** @param {Error | undefined} [error] */
-        buildEnd(error) {
+        /** @param {Error | undefined} [_error] */
+        buildEnd(_error) {
             try {
                 // create log file and append lines to it
                 const logFile = path.resolve(process.cwd(), "imports.log");

package/plugins/vite/local-files-analysis.js

@@ -81,7 +81,7 @@ export function getLocalFilesAutoPolicy(projectDir) {
  * @returns {boolean}
  */
 export function makeFilesLocalIsEnabled(userSettings) {
-    if (typeof userSettings?.makeFilesLocal === "object") return userSettings?.makeFilesLocal?.enabled !== false;
+    if (typeof userSettings?.makeFilesLocal === "object") return userSettings?.makeFilesLocal?.enabled === true;
     if (userSettings?.makeFilesLocal === "auto") return true;
     return userSettings?.makeFilesLocal === true;
 }
@@ -93,7 +93,7 @@ export function makeFilesLocalIsEnabled(userSettings) {
 export function resolveOptions(userSettings) {
     if (typeof userSettings?.makeFilesLocal === "object") {
         const raw = userSettings.makeFilesLocal;
-        const opts = { ...raw };
+        const opts = /** @type {LocalizationOptions} */ ({ ...raw });
         if (!opts.exclude?.length && opts.excludeUrls?.length) {
             opts.exclude = opts.excludeUrls;
         }
@@ -288,7 +288,7 @@ export function analyzeProjectGlbs(projectDir) {
     const extensions = /** @type {Set<string>} */ (new Set());
     const componentTypes = /** @type {Set<string>} */ (new Set());
     const componentCounts = /** @type {Map<string, number>} */ (new Map());
-    const needleExtensionBlobs = /** @type {unknown[]} */ ([]);
+    const needleExtensionBlobs = /** @type {string[]} */ ([]);
 
     let hasWebXRComponent = false;
     let hasVideoPlayerComponent = false;
@@ -303,9 +303,9 @@ export function analyzeProjectGlbs(projectDir) {
 
     for (const file of sceneFiles) {
         try {
-            const json = file.type === "glb"
+            const json = /** @type {Record<string,any>|null} */ (file.type === "glb"
                 ? readGlbJsonChunk(file.path)
-                : readGltfJsonFile(file.path);
+                : readGltfJsonFile(file.path));
             if (!json || typeof json !== "object") continue;
 
             const used = Array.isArray(json.extensionsUsed) ? json.extensionsUsed : [];
@@ -408,7 +408,7 @@ export function analyzeProjectGlbs(projectDir) {
 }
 
 /**
- * @param {Record<string, unknown> | null | undefined} primitive
+ * @param {Record<string, any> | null | undefined} primitive
  * @returns {number}
  */
 function getPrimitivePositionAccessorIndex(primitive) {
@@ -472,9 +472,7 @@ function collectNeedleComponentNames(json) {
  * @param {Set<string>} names
  */
 function collectComponentNamesFromNeedleExtension(value, names) {
-    const builtinComponents = Array.isArray(value?.builtin_components)
-        ? value.builtin_components
-        : [];
+    const builtinComponents = value?.builtin_components ?? [];
 
     for (const entry of builtinComponents) {
         const candidateName = getBuiltinComponentName(entry);
@@ -496,10 +494,10 @@ function getBuiltinComponentName(node) {
  * @param {SceneAnalysisReport} report
  * @param {AutoPolicy | null} autoPolicy
  * @param {string} projectDir
- * @param {string} mode
+ * @param {string} _mode
  * @returns {string}
  */
-function formatSceneAnalysisReport(report, autoPolicy, projectDir, mode) {
+function formatSceneAnalysisReport(report, autoPolicy, projectDir, _mode) {
     const supportsColor = needleSupportsColor();
     const projectName = relative(process.cwd(), projectDir) || ".";
     const componentList = report.componentCounts?.size > 0
@@ -765,7 +763,7 @@ function collectSourceFiles(dir, depth = 0) {
 /**
  * @param {string} url
  * @param {UrlHandler} handler
- * @param {{ options: LocalizationOptions, autoPolicy: AutoPolicy | null }} context
+ * @param {LocalizationContext} context
  * @returns {boolean}
  */
 export function shouldHandleUrlInAutoMode(url, handler, context) {

package/plugins/vite/local-files-core.js

@@ -208,7 +208,7 @@ function recordLocalizedAsset(stats, url, sizeBytes, mimeType) {
 }
 
 /**
- * @param {string} command
+ * @param {"build" | "serve"} command
  * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | null}
@@ -259,7 +259,7 @@ export const needleMakeFilesLocal = (command, _config, userSettings) => {
         },
         async buildStart() {
             await prefetchConfiguredAssets({
-                pluginContext: this,
+                pluginContext: /** @type {import('rollup').PluginContext} */ (this),
                 cache,
                 command,
                 viteConfig,
@@ -282,7 +282,7 @@ export const needleMakeFilesLocal = (command, _config, userSettings) => {
                 const isCssTransform = /\.css($|\?)/i.test(_id || "");
                 const currentDir = isCssTransform ? assetsDir : "";
                 src = await makeLocal(src, "ext/", currentDir, {
-                    pluginContext: this,
+                    pluginContext: /** @type {import('rollup').PluginContext} */ (this),
                     cache,
                     command,
                     viteConfig,
@@ -557,7 +557,7 @@ async function expandTemplateUrls(src, stripped, basePath, currentDir, context)
         }
 
         const replaceRegex = new RegExp('`' + escapedPrefix + '([^`]*\\$\\{[^`]*)`', 'g');
-        src = src.replace(replaceRegex, (/** @type {string} */ fullMatch, /** @type {string} */ rest) => {
+        src = src.replace(replaceRegex, (/** @type {string} */ _fullMatch, /** @type {string} */ rest) => {
             const newPrefix = getRelativeToBasePath(localBasePath, currentDir);
             return '`' + newPrefix + rest + '`';
         });
@@ -770,7 +770,7 @@ function mapFeatureToOutputDir(feature) {
  */
 async function handleCssUrl(url, basePath, currentDir, context, handlers) {
     const cached = context.cache.getFromCache(url);
-    if (cached) return cached;
+    if (typeof cached === 'string') return cached;
 
     let cssContent = await downloadText(url);
     cssContent = await makeLocal(cssContent, basePath, basePath, context, handlers);
@@ -809,7 +809,7 @@ async function handleCssUrl(url, basePath, currentDir, context, handlers) {
  */
 async function handleBinaryUrl(url, basePath, currentDir, context) {
     const cached = context.cache.getFromCache(url);
-    if (cached) return cached;
+    if (typeof cached === 'string') return cached;
 
     const data = await downloadBinary(url);
     recordLocalizedAsset(context.localizationStats, url, data.length, inferMimeType(url));
@@ -844,7 +844,7 @@ async function handleBinaryUrl(url, basePath, currentDir, context) {
  */
 async function handleDecoderDir(baseUrl, basePath, currentDir, handler, context) {
     const cached = context.cache.getFromCache(baseUrl);
-    if (cached) return cached;
+    if (typeof cached === 'string') return cached;
 
     const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
     const localDir = ensureTrailingSlash(basePath);
@@ -888,7 +888,7 @@ async function handleDecoderDir(baseUrl, basePath, currentDir, handler, context)
  */
 export async function handleWebXRProfiles(baseUrl, basePath, currentDir, context) {
     const cached = context.cache.getFromCache(baseUrl);
-    if (cached) return cached;
+    if (typeof cached === 'string') return cached;
 
     const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
     const localDir = basePath + "webxr-profiles/";

package/plugins/vite/local-files-types.d.ts

@@ -19,8 +19,39 @@ export interface LocalizationStats {
     mimeCounts: Map<string, number>;
 }
 
+/**
+ * Configuration for the `makeFilesLocal` build plugin.
+ * Controls which external CDN assets are downloaded at build time and bundled locally,
+ * producing fully self-contained deployments that work without internet access.
+ * Useful for playable ads, app stores requiring single-origin bundles, offline PWAs,
+ * and restricted hosting environments.
+ */
 export interface LocalizationOptions {
+    /**
+     * Which feature categories to include when downloading assets.
+     * - `"auto"` — scan project scene files and source code to detect which features are actually used, then only download those.
+     * - `string[]` — explicit list of feature names. When set, **only** these features are processed.
+     * - When omitted, **all** features are included.
+     *
+     * Available features:
+     * `"draco"`, `"ktx2"`, `"materialx"`, `"xr"`, `"skybox"`, `"fonts"`,
+     * `"needle-fonts"`, `"needle-models"`, `"needle-avatars"`, `"needle-branding"`,
+     * `"polyhaven"`, `"cdn-scripts"`, `"github-content"`, `"threejs-models"`, `"needle-uploads"`
+     *
+     * @example
+     * features: "auto"
+     * @example
+     * features: ["draco", "ktx2", "fonts"]
+     */
     features?: string | string[];
+    /**
+     * Feature categories to exclude. Applied **after** `features` (including after auto-detection).
+     * Use this to opt out of specific categories you don't need without having to list every other one.
+     *
+     * @example
+     * // Auto-detect everything except XR controller profiles
+     * { features: "auto", excludeFeatures: ["xr"] }
+     */
     excludeFeatures?: string[];
     /** URL substrings or RegExps to skip. */
     exclude?: (string | RegExp)[];
@@ -34,9 +65,25 @@ export interface LocalizationOptions {
     skybox?: string | string[];
     /** WebXR controller profile mode: "minimal" | "quest" | "pico" | "all" */
     webxr?: string;
+    /**
+     * Template-based URL expansion rules. Used for CDN URLs that contain template-literal
+     * variables (e.g. `${version}`, `${platform}`). The plugin expands every combination
+     * of the provided variable values, downloads each concrete URL, and rewrites the
+     * template literal to point at the local copy.
+     *
+     * @example
+     * templateExpansions: [{
+     *   cdnPrefix: "https://cdn.example.com/decoders/",
+     *   variables: { version: ["v1", "v2"], arch: ["wasm", "js"] },
+     *   localPrefix: "decoders"   // optional — derived from cdnPrefix when omitted
+     * }]
+     */
     templateExpansions?: Array<{
+        /** The CDN base URL that the template literals start with. */
         cdnPrefix: string;
+        /** Map of variable names to all possible values. Every combination is expanded and downloaded. */
         variables: Record<string, string[]>;
+        /** Local output subdirectory. Derived from `cdnPrefix` hostname when omitted. */
         localPrefix?: string;
     }>;
     /** Used when makeFilesLocal is an object — set to false to disable. */
@@ -51,18 +98,9 @@ export interface AutoPolicy {
     selectedWebXRProfiles: string[];
 }
 
-export interface VitePluginContext {
-    emitFile(asset: {
-        type: "asset" | "chunk";
-        fileName?: string;
-        name?: string;
-        source?: string | Uint8Array;
-    }): string;
-    getFileName(referenceId: string): string;
-}
-
 export interface LocalizationContext {
-    pluginContext: VitePluginContext | null;
+    /** The Rollup plugin context, available during build hooks (null in dev/serve). */
+    pluginContext: import('rollup').PluginContext | null;
     cache: {
         addToCache(key: string, value: Buffer | string): void;
         getFromCache(key: string): Buffer | string | null;

package/plugins/vite/local-files-utils.js

@@ -118,7 +118,7 @@ export function ensureTrailingSlash(path) {
 export function fixRelativeNewURL(src) {
     src = src.replace(
         /(?<==\s*)(["'])((?:(?:\.{1,2}\/)|\/)?ext\/[^"']*\/)\1/g,
-        (/** @type {string} */ match, /** @type {string} */ quote, /** @type {string} */ path) => {
+        (/** @type {string} */ _match, /** @type {string} */ quote, /** @type {string} */ path) => {
             const runtimePath = path.startsWith("/ext/") ? path.substring(1) : path;
             return `new URL(${quote}${runtimePath}${quote}, self.location?.href || ${quote}${quote}).href`;
         }
@@ -126,7 +126,7 @@ export function fixRelativeNewURL(src) {
 
     src = src.replace(
         /new\s+URL\s*\(\s*(["'`])((?:(?:\.{1,2}\/)|\/)?ext\/[^"'`]+)\1\s*\)/g,
-        (/** @type {string} */ match, /** @type {string} */ quote, /** @type {string} */ path) => {
+        (/** @type {string} */ _match, /** @type {string} */ quote, /** @type {string} */ path) => {
             const runtimePath = path.startsWith("/ext/") ? path.substring(1) : path;
             return `new URL(${quote}${runtimePath}${quote}, self.location?.href)`;
         }
@@ -175,7 +175,7 @@ export function getValidFilename(path, content) {
 }
 
 /**
- * @param {string} str
+ * @param {string | Buffer} str
  * @returns {string}
  */
 function createContentMd5(str) {
@@ -197,7 +197,8 @@ export function downloadText(url) {
         const req = (url.startsWith("http://") ? http.get(url, (response) => {
             if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
                 clearTimeout(timer);
-                return downloadText(response.headers.location).then(res).catch(rej);
+                downloadText(response.headers.location).then(res).catch(rej);
+                return;
             }
 
             if (response.statusCode !== 200) {
@@ -224,7 +225,8 @@ export function downloadText(url) {
         }) : https.get(url, (response) => {
             if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
                 clearTimeout(timer);
-                return downloadText(response.headers.location).then(res).catch(rej);
+                downloadText(response.headers.location).then(res).catch(rej);
+                return;
             }
 
             if (response.statusCode !== 200) {
@@ -270,7 +272,8 @@ export function downloadBinary(url) {
         const req = (url.startsWith("http://") ? http.get(url, (response) => {
             if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
                 clearTimeout(timer);
-                return downloadBinary(response.headers.location).then(res).catch(rej);
+                downloadBinary(response.headers.location).then(res).catch(rej);
+                return;
             }
 
             if (response.statusCode !== 200) {
@@ -283,7 +286,7 @@ export function downloadBinary(url) {
             updateMakeLocalProgress(url);
 
             const chunks = /** @type {Buffer[]} */ ([]);
-            response.on('data', (/** @type {Buffer|string} */ chunk) => {
+            response.on('data', (/** @type {Buffer} */ chunk) => {
                 chunks.push(chunk);
             });
             response.on('end', () => {
@@ -297,7 +300,8 @@ export function downloadBinary(url) {
         }) : https.get(url, (response) => {
             if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
                 clearTimeout(timer);
-                return downloadBinary(response.headers.location).then(res).catch(rej);
+                downloadBinary(response.headers.location).then(res).catch(rej);
+                return;
             }
 
             if (response.statusCode !== 200) {
@@ -310,7 +314,7 @@ export function downloadBinary(url) {
             updateMakeLocalProgress(url);
 
             const chunks = /** @type {Buffer[]} */ ([]);
-            response.on('data', (/** @type {Buffer|string} */ chunk) => {
+            response.on('data', (/** @type {Buffer} */ chunk) => {
                 chunks.push(chunk);
             });
             response.on('end', () => {
@@ -337,7 +341,7 @@ export function downloadBinary(url) {
  */
 export function recordFailedDownload(context, url, err) {
     if (!url || !context?.failedDownloads) return;
-    const message = err?.message ? String(err.message) : "";
+    const message = err instanceof Error ? err.message : "";
     if (!context.failedDownloads.has(url)) {
         context.failedDownloads.set(url, message);
     }

package/plugins/vite/logger.client.js

@@ -23,10 +23,10 @@ function sendLogToServer(level, ...message) {
             }
             // @ts-ignore
             import.meta.hot.send("needle:client-log", { level, message: msg });
-        } catch (/** @type {{ message?: string }} */ e) {
+        } catch (/** @type {any} */ e) {
             // silently fail but send a message
             try {
-                import.meta.hot.send("needle:client-log", { level: "error", message: `Error during logging: ${e.message}` });
+                import.meta.hot?.send("needle:client-log", { level: "error", message: `Error during logging: ${e?.message ?? String(e)}` });
             }
             catch (/** @type {unknown} */ e2) {
                 // fallback failed as well
@@ -149,9 +149,9 @@ User Activation: ${"userActivation" in navigator ? JSON.stringify(navigator.user
                 });
         }
     }
-    catch (/** @type {{ message?: string }} */ e) {
+    catch (/** @type {any} */ e) {
         // silently fail
-        sendLogToServer("error", `Error during initial log: ${e.message}`);
+        sendLogToServer("error", `Error during initial log: ${e?.message ?? String(e)}`);
     }
 
     window.addEventListener('error', (event) => {

package/plugins/vite/logger.js

@@ -11,11 +11,11 @@ const __dirname = path.dirname(__filename);
 /**
  * write logs to local file
  * @param {string} command
- * @param {unknown} config
+ * @param {unknown} _config
  * @param {import('../types/userconfig.js').userSettings} userSettings
  * @returns {import('vite').Plugin | null}
  */
-export const needleLogger = (command, config, userSettings) => {
+export const needleLogger = (command, _config, userSettings) => {
 
     if (userSettings?.disableLogging === true) {
         return null;
@@ -35,7 +35,7 @@ export const needleLogger = (command, config, userSettings) => {
         },
         transformIndexHtml: {
             order: 'pre',
-            handler(html, ctx) {
+            handler(_html, _ctx) {
                 // inject client logger script during development
                 if (command === 'serve') {
                     const file = path.join(__dirname, 'logger.client.js');
@@ -53,6 +53,7 @@ export const needleLogger = (command, config, userSettings) => {
                         ];
                     }
                 }
+                return [];
             },
         }
     }
@@ -84,18 +85,17 @@ function logRequests(server, log_http_requests = false) {
             });
         });
         // Client log messages via websocket
-        server.ws.on('needle:client-log', async (/** @type {{level: string, message: unknown}} */ data, /** @type {{socket: import('net').Socket}} */ client) => {
+        server.ws.on('needle:client-log', async (/** @type {{level: string, message: unknown}} */ data, /** @type {import('vite').WebSocketClient} */ client) => {
             if (!data || !data.level || !data.message) {
                 console.warn("Received empty log data, ignoring");
                 return;
             }
-            const socket = client.socket;
-            const info = connectedClients.get(socket);
+            const info = connectedClients.get(client.socket);
             captureLogMessage("client", data.level, data.message, info ? info.id : null);
         });
     }
     // Log HTTP requests
-    server.middlewares.use((req, res, next) => {
+    server.middlewares.use((req, _res, next) => {
         if (log_http_requests) {
             captureLogMessage("client-http", "info", [req.method, req.url], null);
         }

package/plugins/vite/logging.js

@@ -6,6 +6,22 @@ const colors = createColors(isColorSupported);
 /** @type {null | (() => void)} */
 let transientLogLineCleaner = null;
 
+/**
+ * Tracks the last plugin name that called needleLog.
+ * Used to suppress repeated header lines for consecutive logs from the same plugin.
+ * @type {string | null}
+ */
+let lastLoggedPlugin = null;
+
+/**
+ * Resets the sticky-header state so the next needleLog call always emits its
+ * [plugin-name] header. Call this at the start of a new build or any logical
+ * output section where you want a guaranteed fresh header.
+ */
+export function resetLastLoggedPlugin() {
+    lastLoggedPlugin = null;
+}
+
 function getConsoleMethod(level) {
     if (level === 'error') return console.error;
     if (level === 'warn') return console.warn;
@@ -67,13 +83,20 @@ export function needleLog(pluginName, message, level = 'log', options = undefine
     const leadingNewline = options?.leadingNewline === true;
     const showHeader = options?.showHeader !== false;
 
+    // Sticky header: only re-emit [plugin-name] when the plugin changes.
+    // Always re-emit for warn/error (for clarity), header-only calls (no body),
+    // or section breaks (leadingNewline).
+    const pluginChanged = pluginName !== lastLoggedPlugin;
+    const emitHeader = showHeader && (pluginChanged || level !== 'log' || bodyText.length === 0 || leadingNewline);
+    lastLoggedPlugin = pluginName;
+
     if (isColorSupported) {
         const header = `\x1b[0m${headerText}`;
         const leveledBody = colorBodyByLevel(level, bodyText);
         const body = bodyText.length > 0
             ? (dimBody ? leveledBody.split('\n').map(l => colors.dim(l)).join('\n') : leveledBody)
             : "";
-        const payloadCore = showHeader
+        const payloadCore = emitHeader
             ? (body.length > 0 ? `${header}\n${body}\n` : `${header}\n`)
             : (body.length > 0 ? `${body}\n` : "");
         const payload = leadingNewline ? `\n${payloadCore}` : payloadCore;
@@ -82,11 +105,11 @@ export function needleLog(pluginName, message, level = 'log', options = undefine
     }
 
     if (bodyText.length > 0) {
-        const out = showHeader ? `${headerText} ${bodyText}` : bodyText;
+        const out = emitHeader ? `${headerText} ${bodyText}` : bodyText;
         log(leadingNewline ? `\n${out}` : out);
     }
     else {
-        const out = showHeader ? headerText : "";
+        const out = emitHeader ? headerText : "";
         if (out.length > 0) {
             log(leadingNewline ? `\n${out}` : out);
         }

package/plugins/vite/pwa.js

@@ -3,6 +3,7 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync,
 
 import { getOutputDirectory } from './config.js';
 import { getPosterPath } from './poster.js';
+import { needleLog } from './logging.js';
 
 const pwaErrorWithInstructions = "It seems that you're trying to build a PWA using 'vite-plugin-pwa'!\nNeedle can manage PWA settings for you – just pass the same 'pwaOptions' to the needlePlugins and VitePWA plugins:\n\n1. Install the vite PWA plugin: npm install vite-plugin-pwa --save-dev\n\n2. Then update your vite.config.js:\n\n    import { VitePWA } from 'vite-plugin-pwa';\n    ...\n    needlePlugins(command, needleConfig, { pwa: pwaOptions }),\n    VitePWA(pwaOptions),\n\nIf you want to manage PWA building yourself and skip this check, please pass '{ pwa: false }' to needlePlugins.";
 
@@ -267,7 +268,7 @@ updateSW = registerSW({
 }
 
 /** Checks if the vite-plugin-pwa is present in the vite config
- * @param {{ plugins?: readonly unknown[] }} config
+ * @param {import('vite').ResolvedConfig} config
  * @returns {import('vite-plugin-pwa').VitePWAOptions | null}
  */
 function findVitePWAPlugin(config) {
@@ -291,7 +292,7 @@ function findVitePWAPlugin(config) {
 /** @param {import('../types/index.d.ts').NeedlePWAProcessContext} context */
 function cleanup(context) {
     for (const file of context.generatedFiles) {
-        log("Cleanup generated file", file);
+        if (process.env.DEBUG) log("Cleanup generated file", file);
         rmSync(file);
     }
     context.generatedFiles.length = 0;
@@ -299,7 +300,7 @@ function cleanup(context) {
 
 /** @param {...unknown} args */
 function log(...args) {
-    console.log("[needle-pwa]", ...args);
+    needleLog("needle-pwa", args.map(a => a != null && typeof a === 'object' ? JSON.stringify(a) : String(a ?? "")).join(" "), "log", { dimBody: false });
 }
 
 /** Throws an error with defined stacktrace. 
@@ -451,7 +452,7 @@ function processIcons(manifest, outDir, context) {
  */
 function generateIcons(manifest, context) {
     if (!manifest.icons) manifest.icons = [];
-    log("Generating PWA icons");
+    if (process.env.DEBUG) log("Generating PWA icons");
     const sizes = [48, 128, 144, 192, 512];
     // Needle icon
     const defaultIconSVG = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 160 187.74"><defs><linearGradient id="a" x1="89.64" y1="184.81" x2="90.48" y2="21.85" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#62d399"/><stop offset=".51" stop-color="#acd842"/><stop offset=".9" stop-color="#d7db0a"/></linearGradient><linearGradient id="b" x1="69.68" y1="178.9" x2="68.08" y2="16.77" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#0ba398"/><stop offset=".5" stop-color="#4ca352"/><stop offset="1" stop-color="#76a30a"/></linearGradient><linearGradient id="c" x1="36.6" y1="152.17" x2="34.7" y2="84.19" gradientUnits="userSpaceOnUse"><stop offset=".19" stop-color="#36a382"/><stop offset=".54" stop-color="#49a459"/><stop offset="1" stop-color="#76a30b"/></linearGradient><linearGradient id="d" x1="15.82" y1="153.24" x2="18" y2="90.86" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#267880"/><stop offset=".51" stop-color="#457a5c"/><stop offset="1" stop-color="#717516"/></linearGradient><linearGradient id="e" x1="135.08" y1="135.43" x2="148.93" y2="63.47" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#b0d939"/><stop offset="1" stop-color="#eadb04"/></linearGradient><linearGradient id="f" x1="-4163.25" y1="2285.12" x2="-4160.81" y2="2215.34" gradientTransform="rotate(20 4088.49 13316.712)" gradientUnits="userSpaceOnUse"><stop offset=".17" stop-color="#74af52"/><stop offset=".48" stop-color="#99be32"/><stop offset="1" stop-color="#c0c40a"/></linearGradient><symbol id="g" viewBox="0 0 160 187.74"><path style="fill:url(#a)" d="M79.32 36.98v150.76L95 174.54l6.59-156.31-22.27 18.75z"/><path style="fill:url(#b)" d="M79.32 36.98 57.05 18.23l6.59 156.31 15.68 13.2V36.98z"/><path style="fill:url(#c)" d="m25.19 104.83 8.63 49.04 12.5-14.95-2.46-56.42-18.67 22.33z"/><path style="fill:url(#d)" d="M25.19 104.83 0 90.24l16.97 53.86 16.85 9.77-8.63-49.04z"/><path style="fill:#9c3" d="M43.86 82.5 18.69 67.98 0 90.24l25.18 14.59L43.86 82.5z"/><path style="fill:url(#e)" d="m134.82 78.69-9.97 56.5 15.58-9.04L160 64.1l-25.18 14.59z"/><path style="fill:url(#f)" d="m134.82 78.69-18.68-22.33-2.86 65 11.57 13.83 9.97-56.5z"/><path style="fill:#ffe113" d="m160 64.1-18.69-22.26-25.17 14.52 18.67 22.33L160 64.1z"/><path style="fill:#f3e600" d="M101.59 18.23 79.32 0 57.05 18.23l22.27 18.75 22.27-18.75z"/></symbol></defs><use width="160" height="187.74" xlink:href="#g"/></svg>`;
@@ -504,7 +505,7 @@ function copyIcons(manifest, outDir) {
                 if (!existsSync(outputDirectory)) {
                     mkdirSync(outputDirectory, { recursive: true });
                 }
-                log("Copy PWA icon " + src + " to output");
+                if (process.env.DEBUG) log("Copy PWA icon " + src + " to output");
                 copyFileSync(srcPath, targetPath);
             }
         }