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

package/plugins/common/logger.js

@@ -31,19 +31,33 @@ const buildOutputState = {
     compressionCaptureActive: false,
 };
 
-/** @param {unknown} value @returns {number} */
+/**
+ * Parses a numeric kB value from a potentially formatted string (e.g. "1.23 kB"),
+ * stripping all non-numeric characters except the decimal point.
+ * Returns 0 for any value that cannot be parsed as a finite number.
+ * @param {unknown} value @returns {number}
+ */
 function parseKb(value) {
     const numeric = Number.parseFloat(String(value ?? "0").replace(/[^0-9.]/g, ""));
     return Number.isFinite(numeric) ? numeric : 0;
 }
 
+/**
+ * Clears the current in-place progress line from the terminal, if one is active.
+ * Has no effect in non-TTY environments (CI, piped output).
+ */
 function clearBuildProgressLine() {
     if (!process.stdout.isTTY || !buildOutputState.progressActive) return;
     process.stdout.write("\r\x1b[2K");
     buildOutputState.progressActive = false;
 }
 
-/** @param {string} text */
+/**
+ * Overwrites the current terminal line with a transient build progress indicator.
+ * Subsequent calls overwrite the same line in place, keeping the output clean.
+ * Has no effect in non-TTY environments (CI, piped output).
+ * @param {string} text
+ */
 function writeBuildProgressLine(text) {
     if (!process.stdout.isTTY) return;
     const maxLength = Math.max(24, (process.stdout.columns || 120) - 1);
@@ -52,6 +66,10 @@ function writeBuildProgressLine(text) {
     buildOutputState.progressActive = true;
 }
 
+/**
+ * Resets all per-build asset and compression counters back to zero.
+ * Called at the start of each build and after summaries are flushed.
+ */
 function resetBuildOutputState() {
     buildOutputState.progressActive = false;
     buildOutputState.assetFiles = 0;
@@ -63,6 +81,16 @@ function resetBuildOutputState() {
     buildOutputState.compressionCaptureActive = false;
 }
 
+/**
+ * Emits aggregated bundle/compression summary lines to stdout, then resets counters.
+ *
+ * During a build, Vite normally prints one line per output file (e.g.
+ * "dist/foo.js  1.23 kB │ gzip: 0.45 kB"). Those lines are intercepted by
+ * tryHandleBuildConsoleOutput, which silently accumulates file counts and sizes
+ * instead of printing them. This function is called once bundling finishes (when
+ * Vite emits "✓ built in …") and replaces all the per-file lines with a single
+ * formatted summary like "[needle-buildinfo]\n✓ Bundled 27 files (1234.56 kB)".
+ */
 function flushBuildOutputSummaries() {
     if (buildOutputState.mode !== "build") return;
     clearBuildProgressLine();
@@ -82,11 +110,20 @@ function flushBuildOutputSummaries() {
     resetBuildOutputState();
 }
 
+/**
+ * Returns true if stdout is a TTY and the NO_COLOR environment variable is not set.
+ * Used to guard ANSI escape sequences so output stays clean in CI and piped contexts.
+ */
 function supportsColorOutput() {
     return !!process.stdout?.isTTY && process.env.NO_COLOR !== "1";
 }
 
-/** @param {string} name @returns {string} */
+/**
+ * Formats a plugin name as a styled [header] string.
+ * Names starting with "needle-" or "needle:" get ANSI green coloring with a bold suffix.
+ * Falls back to plain "[name]" when color output is not supported.
+ * @param {string} name @returns {string}
+ */
 function formatNeedleHeader(name) {
     if (!supportsColorOutput()) return `[${name}]`;
     if (name.startsWith("needle-")) {
@@ -100,17 +137,39 @@ function formatNeedleHeader(name) {
     return `\x1b[32m[\x1b[0m\x1b[1;32m${name}\x1b[0m\x1b[32m]\x1b[0m`;
 }
 
-/** @param {string} body @returns {string} */
+/**
+ * Wraps a build summary string under the [needle-buildinfo] header.
+ * Used by flushBuildOutputSummaries to format the final "✓ Bundled N files"
+ * and "✓ Gzip compressed N files" lines.
+ * @param {string} body @returns {string}
+ */
 function formatBuildInfoSummaryMessage(body) {
     return `${formatNeedleHeader("needle-buildinfo")}\n${body}`;
 }
 
-/** @param {unknown[]} args @returns {string} */
+/**
+ * Joins an array of console.log arguments into a single string,
+ * serializing non-string values with stringifyLog.
+ * @param {unknown[]} args @returns {string}
+ */
 function normalizeConsoleArgs(args) {
     return args.map(arg => typeof arg === "string" ? arg : stringifyLog(arg)).join(" ");
 }
 
-/** @param {unknown[]} args @returns {boolean} */
+/**
+ * Intercepts console output during a build run and decides whether to suppress or forward it.
+ *
+ * - Per-file asset lines ("dist/foo.js  1.23 kB") are silently accumulated into
+ *   buildOutputState counters and replaced by a summary via flushBuildOutputSummaries.
+ * - vite-plugin-compression per-file lines are similarly accumulated.
+ * - "transforming (N)" progress messages are rendered as an animated in-place indicator.
+ * - Any other message (including "✓ built in …") triggers flushBuildOutputSummaries
+ *   before passing through.
+ *
+ * Returns true if the message was fully consumed (caller must not forward to original
+ * console), or false if it should pass through normally.
+ * @param {unknown[]} args @returns {boolean}
+ */
 function tryHandleBuildConsoleOutput(args) {
     if (buildOutputState.mode !== "build") return false;
 
@@ -158,8 +217,22 @@ function tryHandleBuildConsoleOutput(args) {
 }
 
 /**
+ * Patches the global console methods to intercept and process Vite build output.
+ *
+ * In build mode, per-file asset lines emitted by Vite (and vite-plugin-compression)
+ * are absorbed silently, counts and sizes are accumulated, and a concise summary is
+ * printed by flushBuildOutputSummaries once bundling completes. In serve mode all
+ * messages pass through unchanged.
+ *
+ * All console output (log/error/warn/info/debug) is also written to a rotating
+ * timestamped log file under node_modules/.needle/logs/ via captureLogMessage.
+ *
+ * Calling patchConsoleLogs a second time is a no-op and returns the same unpatch
+ * function. Call the returned function to restore the original console methods and
+ * flush any pending summaries.
+ *
  * @param {{command?: string} | undefined} [options]
- * @returns {(() => void) | undefined}
+ * @returns {(() => void) | null}
  */
 export function patchConsoleLogs(options = undefined) {
     if (didPatch) return unpatchFunction;
@@ -216,6 +289,13 @@ const isCapturingLogMessage = new Set();
 const queue = new Array();
 
 /**
+ * Serializes a log message and appends it to the rotating per-process log file
+ * (node_modules/.needle/logs/<timestamp>.server.needle.log).
+ *
+ * Re-entrant calls while a capture is already in progress are queued and
+ * processed afterwards to prevent recursive logging loops. Circular references
+ * in the log value are also guarded against via the isCapturingLogMessage set.
+ *
  * @param {ProcessType} process
  * @param {string} key
  * @param {unknown} log
@@ -236,7 +316,7 @@ export function captureLogMessage(process, key, log, connectionId, time = Date.n
     isCapturingLogMessage.add(log);
 
     try {
-        let str = stringifyLog(log);
+        let str = /** @type {string} */(stringifyLog(log));
         if (str.trim().length > 0) {
             // if(process === "server") str = stripAnsiColors(str);
             const prefix = `${getTimestamp(time, true)}, ${process}${connectionId ? (`[${connectionId}]`) : ""}.${key}: `;
@@ -261,7 +341,10 @@ export function captureLogMessage(process, key, log, connectionId, time = Date.n
 
 
 /**
- * Stringifies a log message, handling circular references and formatting.
+ * Recursively serializes an arbitrary value to a human-readable string.
+ * Handles primitives, plain objects, arrays, typed arrays, Error instances,
+ * circular references, and truncates large values based on per-environment limits
+ * (server limits are more generous than browser limits).
  * @param {unknown} log
  * @param {Set<unknown>} [seen]
  */
@@ -389,8 +472,10 @@ function stringifyLog(log, seen = /** @type {Set<unknown>} */ (new Set()), depth
 // #region utility functions
 
 /**
- * Returns the current timestamp in ISO format.
- * @param {number} [date] - Optional date to format, defaults to current date.
+ * Returns the current time as a HH:MM:SS string (timeOnly=true) or a full ISO 8601
+ * timestamp string. Used as a prefix in log file entries.
+ * @param {number} [date] - Optional timestamp in ms, defaults to now.
+ * @param {boolean} [timeOnly]
  */
 function getTimestamp(date, timeOnly = false) {
     const now = date ? new Date(date) : new Date();
@@ -467,12 +552,14 @@ if (existsSync(fileLogDirectory)) {
 }
 
 /**
- * Writes a log message to the file.
+ * Appends a single log entry to the per-process rotating file log.
+ * The file is created lazily under node_modules/.needle/logs/ on first write,
+ * using a timestamped filename so each process start gets a fresh file.
  * @param {ProcessType} process
  * @param {string} log
- * @param {string | null} connectionId - Optional connection ID for client logs.
+ * @param {string | null} _connectionId - Reserved for future per-connection log files.
  */
-function writeToFile(process, log, connectionId) {
+function writeToFile(process, log, _connectionId) {
     const filename = `${process}.needle.log`; //connectionId && process === "client" ? `${process}-${connectionId}.needle.log` : `${process}.needle.log`;
 
     if (!filestreams.has(filename)) {
@@ -492,11 +579,14 @@ function writeToFile(process, log, connectionId) {
 
 
 // #region process exit
+
+/** Flushes and closes all open log write streams. Registered for all exit-related process events. */
 function onExit() {
     filestreams.forEach((stream) => stream.end());
     filestreams.clear();
 }
 
+/** Explicitly close all log file streams. Call this before a clean process exit (e.g. end of a build run). */
 export function closeLogStreams() {
     onExit();
 }

package/plugins/types/userconfig.d.ts

@@ -14,6 +14,8 @@ export type userSettings = {
 
     /** disable vite.alias modification */
     noAlias?: boolean;
+    /** Enable verbose debug output for needle plugins. */
+    debug?: boolean;
     /**
      * When set to `true` a plugin will log all alias resolutions to a file in the project node_modules directory
      * @default false

package/plugins/vite/ai.js

@@ -36,27 +36,14 @@ export const needleAI = (command, config, userSettings) => {
     };
 };
 
-/** Read the engine version from our own package.json */
-function getEngineVersion() {
-    try {
-        const pkgPath = join(__dirname, "../../package.json");
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return pkg.version || "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
-
-function writeSkill(claudeDir, version) {
+function writeSkill(claudeDir) {
     const skillDir = join(claudeDir, "skills", "needle-engine");
     if (!existsSync(skillDir)) {
         mkdirSync(skillDir, { recursive: true });
     }
     const skillPath = join(skillDir, "SKILL.md");
-    const templatePath = join(__dirname, "../common/needle-engine-skill.md");
-    const template = readFileSync(templatePath, "utf8");
-    const content = template.replace("{{VERSION}}", version);
+    const templatePath = join(__dirname, "../../SKILL.md");
+    const content = readFileSync(templatePath, "utf8");
     writeFileSync(skillPath, content, "utf8");
     return skillPath;
 }
@@ -65,7 +52,6 @@ function installClaudeSkill() {
     const claudeDir = join(process.cwd(), ".claude");
     if (!existsSync(claudeDir)) return; // only install if developer uses Claude Code
 
-    const version = getEngineVersion();
-    const path = writeSkill(claudeDir, version);
+    const path = writeSkill(claudeDir);
     console.log(`[${pluginName}] Installed Needle Engine Claude skill → ${path}`);
 }

package/plugins/vite/alias.js

@@ -112,19 +112,6 @@ export const needleViteAlias = (command, config, userSettings) => {
             }
 
 
-            // is needle engine a local package?
-            // This will cause local changes to not be reflected anymore...
-            const localEnginePath = path.resolve(projectDir, 'node_modules/', '@needle-tools/engine', 'node_modules', '.package-lock.json');
-            if (existsSync(localEnginePath)) {
-                config.optimizeDeps ??= {};
-                config.optimizeDeps.exclude ??= [];
-                if (!config.optimizeDeps.include?.includes('@needle-tools/engine')) {
-                    config.optimizeDeps.exclude.push('@needle-tools/engine');
-                    log("Detected local @needle-tools/engine package → will exclude it from optimization");
-                }
-            }
-
-
             if (debug) {
                 const testResults = [];
                 for (const name in aliasDict) {

package/plugins/vite/asap.js

@@ -202,7 +202,7 @@ function generateGltfPreloadLinks(config, html, tags) {
                             filepath = decodeURIComponent(filepath);
                             const fullpath = path.join(process.cwd(), filepath);
                             if (!existsSync(fullpath)) {
-                                needleLog("needle:asap", `Could not insert head preload link: file not found at \"${filepath}\"`, "warn", { dimBody: false });
+                                if (process.env.DEBUG) needleLog("needle:asap", `Could not insert head preload link: file not found at "${filepath}"`, "log", { dimBody: true });
                                 continue;
                             }
                         }

package/plugins/vite/build-pipeline.js

@@ -196,11 +196,9 @@ export const needleBuildPipeline = async (command, config, userSettings) => {
                     const key = (/** @type {string} */ text) => supportsColor ? needleBlue(text) : text;
                     const outputPath = relative(process.cwd(), buildPipelineTaskResults.outputDirectory).replaceAll("\\", "/") || ".";
                     const moved = getDirectoryStats(buildPipelineTaskResults.tempDirectory);
-                    lines.push(`${key("Copying files")}: \"${outputPath}\"`);
                     const ctx = { count: 0, bytes: 0 }
                     copyFilesSync(buildPipelineTaskResults.tempDirectory, buildPipelineTaskResults.outputDirectory, true, ctx);
-                    lines.push(`${key("Copied files")}: ${ctx.count}`);
-                    lines.push(`${key("Data moved")}: ${formatBytes(moved.totalBytes)} (${moved.fileCount} files)`);
+                    lines.push(`${key("Copying")}: "${outputPath}" — ${moved.fileCount} file${moved.fileCount !== 1 ? 's' : ''}, ${formatBytes(moved.totalBytes)}`);
                 }
                 else {
                     lines.push("No files to copy - build pipeline did not run or did not finish successfully");
@@ -306,8 +304,7 @@ async function invokeBuildPipeline(opts, options = {}) {
         }
     }, 0);
     needleLog("needle-buildpipeline", [
-        `${key("Files to process")}: ${files.length} in ${rel(outputDirectory)}`,
-        `${key("Input size")}: ${formatBytes(filesBytes)}`,
+        `${key("Files to process")}: ${files.length} in ${rel(outputDirectory)}, ${formatBytes(filesBytes)}`,
         existsSync(process.cwd() + "/node_modules/.needle/build-pipeline/output") ? needleDim("Removing temporary output directory") : undefined,
     ].filter(Boolean), "log", { dimBody: false });
 

package/plugins/vite/buildinfo.js

@@ -23,14 +23,13 @@ export const needleBuildInfo = (command, config, userSettings) => {
         },
         closeBundle: async () => {
             if (--level > 0) {
-                needleLog("needle-buildinfo", "Skipped because of nested build");
-                return;
+                return; // nested build (e.g. worker entry) — skip
             }
             const buildDirectory = getOutputDirectory();
             const beforeStats = collectBuildDirectoryStats(buildDirectory);
             const task = waitForBuildPipelineToFinish();
             if (task instanceof Promise) {
-                needleLog("needle-buildinfo", "Waiting for build pipeline to finish");
+                if (process.env.DEBUG) needleLog("needle-buildinfo", "Waiting for build pipeline to finish");
                 await task.catch(() => { });
             }
             // wait for gzip
@@ -45,14 +44,15 @@ export const needleBuildInfo = (command, config, userSettings) => {
             const key = (text) => supportsColor ? needleBlue(text) : text;
             const sizeDelta = (result.totalSizeBytes || 0) - (beforeStats.totalSizeBytes || 0);
             const fileDelta = (result.fileCount || 0) - (beforeStats.fileCount || 0);
+            const sizePct = beforeStats.totalSizeBytes > 0 ? Math.round(sizeDelta / beforeStats.totalSizeBytes * 100) : 0;
             const lines = [
                 "Build pipeline finished!",
-                `${key("Before pipeline")}: ${beforeStats.fileCount} files (${formatBytes(beforeStats.totalSizeBytes)})`,
-                `${key("After pipeline")}: ${result.fileCount} files (${formatBytes(result.totalSizeBytes)})`,
-                `${key("Delta")}: ${(sizeDelta >= 0 ? "+" : "-") + formatBytes(Math.abs(sizeDelta))}, ${(fileDelta >= 0 ? "+" : "") + fileDelta} files`,
-                needleDim(`Begin collecting files in \"${result.buildDirectory}\"`),
-                needleDim(`Collected ${result.fileCount} files (${result.totalSizeInMB.toFixed(2)} MB). Writing build info to \"${result.buildInfoPath}\"`),
-                needleDim(`Build info file successfully written to \"${result.buildInfoPath}\"`),
+                `${key("Build info")}: ${formatBytes(beforeStats.totalSizeBytes)} → ${formatBytes(result.totalSizeBytes)} (${sizePct >= 0 ? "+" : ""}${sizePct}%), ${beforeStats.fileCount} → ${result.fileCount} files (${fileDelta >= 0 ? "+" : ""}${fileDelta})`,
+                ...(process.env.DEBUG ? [
+                    needleDim(`Begin collecting files in \"${result.buildDirectory}\"`),
+                    needleDim(`Collected ${result.fileCount} files (${result.totalSizeInMB.toFixed(2)} MB). Writing build info to \"${result.buildInfoPath}\"`),
+                    needleDim(`Build info file successfully written to \"${result.buildInfoPath}\"`),
+                ] : []),
             ];
             if (closedHandles > 0) lines.push(`Closed ${closedHandles} dangling network handle(s)`);
             needleLog("needle-buildinfo", lines.join("\n"), "log", { dimBody: false });

package/plugins/vite/copyfiles.js

@@ -36,7 +36,6 @@ export const needleCopyFiles = (command, config, userSettings) => {
  * @param {import('../types').userSettings} config
  */
 async function run(buildstep, config) {
-    const logLines = [needleDim(`Copy files at ${buildstep}`)];
     const copyIncludesFromEngine = config?.copyIncludesFromEngine ?? true;
     const copied = { count: 0, bytes: 0 };
 
@@ -62,11 +61,22 @@ async function run(buildstep, config) {
             outdirName = needleConfig.buildDirectory;
     }
 
+    // For the "end" step, the first log line carries a leading newline to visually
+    // separate this section from the build-pipeline output above it.
+    let firstLog = true;
+    const logLine = (msg) => {
+        needleLog(pluginName, msg, "log", {
+            dimBody: false,
+            leadingNewline: firstLog && buildstep === "end",
+        });
+        firstLog = false;
+    };
+
     if (copyIncludesFromEngine !== false) {
         // copy include from engine
         const engineIncludeDir = resolve(baseDir, 'node_modules', '@needle-tools', 'engine', 'src', 'include');
         if (existsSync(engineIncludeDir)) {
-            logLines.push(`Engine include: ${rel(engineIncludeDir)} -> ${rel(resolve(baseDir, 'include'))}`);
+            logLine(needleDim(`Engine include: ${rel(engineIncludeDir)} → ${rel(resolve(baseDir, 'include'))}`));
             const projectIncludeDir = resolve(baseDir, 'include');
             copyFilesSync(engineIncludeDir, projectIncludeDir, true, copied);
         }
@@ -94,7 +104,7 @@ async function run(buildstep, config) {
             const src = resolve(baseDir, entry);
             const dest = resolvePath(outDir, entry);
             if (existsSync(src) && dest) {
-                logLines.push(`Configured copy: ${rel(src)} -> ${rel(dest)}`);
+                logLine(`Configured copy: ${rel(src)} → ${rel(dest)}`);
                 copyFilesSync(src, dest, override, copied);
             }
         }
@@ -107,33 +117,26 @@ async function run(buildstep, config) {
         // ensure that the target directory exists and is cleared if it already exists
         // otherwise we might run into issues where the build pipeline is running for already compressed files
         if (override && existsSync(targetDir)) {
-            logLines.push(needleDim(`Clearing target directory "${rel(targetDir)}"`));
+            logLine(needleDim(`Clearing target directory "${rel(targetDir)}"`));
             rmSync(targetDir, { recursive: true, force: true });
         }
-        logLines.push(needleDim(`Assets: ${rel(assetsDir)} -> ${rel(targetDir)}`));
+        logLine(`${key("Copying assets")}: ${rel(assetsDir)} → ${rel(targetDir)}`);
         copyFilesSync(assetsDir, targetDir, override, copied);
     }
-    else logLines.push(`No assets directory found. Skipping copy of ${assetsDirName} resolved to ${rel(assetsDir)}`);
+    else logLine(`No assets directory found. Skipping copy of ${assetsDirName} resolved to ${rel(assetsDir)}`);
 
     // copy include dir
     const includeDir = resolve(baseDir, 'include');
     if (existsSync(includeDir)) {
         const targetDir = resolve(outDir, 'include');
-        logLines.push(needleDim(`Include: ${rel(includeDir)} -> ${rel(targetDir)}`));
+        logLine(needleDim(`Include: ${rel(includeDir)} → ${rel(targetDir)}`));
         copyFilesSync(includeDir, targetDir, override, copied);
     }
 
-    logLines.push(`${key("Copied files")}: ${copied.count}`);
-    logLines.push(`${key("Copied size")}: ${formatBytes(copied.bytes || 0)}`);
+    logLine(`${key("Copied files")}: ${copied.count}, ${formatBytes(copied.bytes || 0)}`);
     if (buildstep === "end") {
-        logLines.push("");
-        logLines.push("✨ Happy creating! 🌵");
+        logLine("✨ Happy creating! 🌵");
     }
-
-    needleLog(pluginName, logLines.join("\n"), "log", {
-        leadingNewline: buildstep === "end",
-        dimBody: false,
-    });
 }
 
 function formatBytes(bytes) {

package/plugins/vite/custom-element-data.js

@@ -61,13 +61,13 @@ function mergeCustomElementData(sourceData, targetData) {
  * - Copies/merges `custom-elements.json` to project root
  * - Adds `./custom-elements.json` to `.code-workspace settings.html.customData`
  * - Adds `./custom-elements.json` to `.vscode/settings.json html.customData`
- * @param {string} command
- * @param {import('../types').needleMeta | null} config
+ * @param {"build" | "serve"} _command
+ * @param {import('../types').needleMeta | null} _config
  * @param {import('../types').userSettings} userSettings
  */
-export const needleCustomElementData = (command, config, userSettings = {}) => {
+export const needleCustomElementData = (_command, _config, userSettings = {}) => {
     // Allow disabling the workspace updater
-    if (config?.noCustomElementData === true || userSettings?.noCustomElementData === true) return;
+    if (userSettings?.noCustomElementData === true) return null;
 
     return {
         name: 'needle:custom-element-data',

package/plugins/vite/dependencies.js

@@ -1,3 +1,5 @@
+import path from 'path';
+import { existsSync } from 'fs';
 import { tryGetNeedleEngineVersion, tryGetPackageVersion } from '../common/version.js';
 import { needleLog } from './logging.js';
 
@@ -7,6 +9,20 @@ import { needleLog } from './logging.js';
 export const preloadScriptPaths = [];
 
 
+/**
+ * Returns true when \`@needle-tools/engine\` is installed as a local package
+ * (i.e. it has its own nested `node_modules`). Vite's optimiser must skip such
+ * packages, otherwise it tries to pre-bundle source that was never meant to be
+ * pre-bundled and fails at dev-server start.
+ *
+ * @param {string} [root] – project root; defaults to `process.cwd()`.
+ * @returns {boolean}
+ */
+export function isLocalNeedleEngineInstalled(root = process.cwd()) {
+    const lockPath = path.resolve(root, 'node_modules', '@needle-tools/engine', 'node_modules', '.package-lock.json');
+    return existsSync(lockPath);
+}
+
 /**
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin[]}
@@ -40,10 +56,9 @@ const excludeDependencies = [
  * @param {import('vite').UserConfig} config
  */
 function handleOptimizeDeps(config) {
-    const logLines = [];
     excludeDependencies.forEach(dep => {
         if (config.optimizeDeps?.include?.includes(dep)) {
-            logLines.push(`${dep} is included in the optimizeDeps.include array. This may cause issues with the worker import.`);
+            needleLog("needle-dependencies", `${dep} is included in the optimizeDeps.include array. This may cause issues with the worker import.`, "warn", { dimBody: false });
         }
         else {
             if (!config.optimizeDeps) {
@@ -56,7 +71,7 @@ function handleOptimizeDeps(config) {
             // This needs to be excluded from optimization because otherwise the worker import fails
             // three-mesh-bvh/src/workers/generateMeshBVH.worker.js?worker
             // same for gltf-progressive
-            logLines.push(`Adding ${dep} to the optimizeDeps.exclude array to support workers.`);
+            needleLog("needle-dependencies", `Adding ${dep} to the optimizeDeps.exclude array to support workers.`);
             config.optimizeDeps.exclude.push(dep);
 
             if (!config.server) config.server = {};
@@ -67,14 +82,22 @@ function handleOptimizeDeps(config) {
             }
         }
     });
-    if (logLines.length) needleLog("needle-dependencies", logLines.join("\n"));
+    // is needle engine a local package? exclude it from vite's optimizeDeps
+    if (isLocalNeedleEngineInstalled()) {
+        config.optimizeDeps ??= {};
+        config.optimizeDeps.exclude ??= [];
+        if (!config.optimizeDeps.include?.includes('@needle-tools/engine') &&
+            !config.optimizeDeps.exclude.includes('@needle-tools/engine')) {
+            config.optimizeDeps.exclude.push('@needle-tools/engine');
+            needleLog("needle-dependencies", 'Detected local @needle-tools/engine package → will exclude it from optimization');
+        }
+    }
 }
 
 /**
  * @param {import('vite').UserConfig} config
  */
 function handleManualChunks(config) {
-    const logLines = [];
     if (!config.build) {
         config.build = {};
     }
@@ -89,7 +112,7 @@ function handleManualChunks(config) {
 
     if (Array.isArray(rollupOutput)) {
         // append the manualChunks function to the array
-        logLines.push("registering manualChunks");
+        if (process.env.DEBUG) needleLog("needle-dependencies", "registering manualChunks");
         rollupOutput.push({
             manualChunks: needleManualChunks
         })
@@ -100,38 +123,37 @@ function handleManualChunks(config) {
         if ("manualChunks" in rollupOutput) {
             allowManualChunks = false;
             // if the user has already defined manualChunks (even when set to undefined), we don't want to overwrite it
-            logLines.push("manualChunks already found in vite config - will not overwrite it");
+            needleLog("needle-dependencies", "manualChunks already found in vite config - will not overwrite it");
         }
         else if (rollupOutput.preserveModules === true) {
             allowManualChunks = false;
-            logLines.push("manualChunks can not be registered because preserveModules is true");
+            needleLog("needle-dependencies", "manualChunks can not be registered because preserveModules is true");
         }
         if (rollupOutput.inlineDynamicImports === true) {
             allowManualChunks = false;
-            logLines.push("manualChunks can not be registered because inlineDynamicImports is true");
+            needleLog("needle-dependencies", "manualChunks can not be registered because inlineDynamicImports is true");
         }
 
         if (allowManualChunks) {
-            logLines.push("registering manualChunks");
+            if (process.env.DEBUG) needleLog("needle-dependencies", "registering manualChunks");
             rollupOutput.manualChunks = needleManualChunks;
         }
 
         if (rollupOutput.chunkFileNames) {
-            logLines.push("chunkFileNames already defined");
+            needleLog("needle-dependencies", "chunkFileNames already defined");
         }
         else {
             rollupOutput.chunkFileNames = handleChunkFileNames;
         }
 
         if (rollupOutput.assetFileNames) {
-            logLines.push("assetFileNames already defined");
+            needleLog("needle-dependencies", "assetFileNames already defined");
         }
         else {
             rollupOutput.assetFileNames = assetFileNames;
         }
     }
 
-    if (logLines.length) needleLog("needle-dependencies", logLines.join("\n"));
 
     // TODO: this was a test if it allows us to remove the sync import of postprocessing due to n8ao's import
     // config.build.rollupOptions.external = (source, importer, isResolved) => {
@@ -168,13 +190,18 @@ function handleManualChunks(config) {
                 needleLog("needle-dependencies", "Error reading version " + e, "warn");
             }
         }
-        else if (chunk.name === 'three') {
-            const version = tryGetPackageVersion("three");
-            if (version) {
-                const name = `assets/three@${version}.js`;
+        else if (chunk.name === 'three' || chunk.name === 'three-examples') {
+            // 'three' may be aliased to @needle-tools/three — check both package locations
+            const version = tryGetPackageVersion("three") ?? tryGetPackageVersion("@needle-tools/three");
+            const name = version
+                ? `assets/${chunk.name}@${version}.js`
+                : `assets/${chunk.name}.js`;
+            // Only eagerly preload three (the core math/scene-graph lib).
+            // three-examples (OrbitControls, loaders, etc.) is loaded on-demand — don't preload it.
+            if (chunk.name === 'three') {
                 preloadScriptPaths.push(`./${name}`);
-                return name;
             }
+            return name;
         }
         // else if(chunk.name === 'index') {
         //     console.log(chunk);