@needle-tools/engine 4.14.0 → 4.15.0-next.f391a30

package/plugins/common/logger.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { createWriteStream, existsSync, mkdirSync, readdirSync, rmSync, statSync, write } from "fs";
 
 const filename_timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
@@ -15,57 +16,209 @@ let originalConsoleWarn = console.warn;
 let originalConsoleInfo = console.info;
 let originalConsoleDebug = console.debug;
 let didPatch = false;
+/** @type {(() => void) | null} */
 let unpatchFunction = null;
 
-export function patchConsoleLogs() {
+const buildOutputState = {
+    mode: "serve",
+    progressActive: false,
+    assetFiles: 0,
+    assetTotalKb: 0,
+    assetGzipKb: 0,
+    compressionFiles: 0,
+    compressionTotalKb: 0,
+    compressionGzipKb: 0,
+    compressionCaptureActive: false,
+};
+
+/** @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;
+}
+
+function clearBuildProgressLine() {
+    if (!process.stdout.isTTY || !buildOutputState.progressActive) return;
+    process.stdout.write("\r\x1b[2K");
+    buildOutputState.progressActive = false;
+}
+
+/** @param {string} text */
+function writeBuildProgressLine(text) {
+    if (!process.stdout.isTTY) return;
+    const maxLength = Math.max(24, (process.stdout.columns || 120) - 1);
+    const line = text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 1))}…` : text;
+    process.stdout.write(`\r\x1b[2K${line}\x1b[0K`);
+    buildOutputState.progressActive = true;
+}
+
+function resetBuildOutputState() {
+    buildOutputState.progressActive = false;
+    buildOutputState.assetFiles = 0;
+    buildOutputState.assetTotalKb = 0;
+    buildOutputState.assetGzipKb = 0;
+    buildOutputState.compressionFiles = 0;
+    buildOutputState.compressionTotalKb = 0;
+    buildOutputState.compressionGzipKb = 0;
+    buildOutputState.compressionCaptureActive = false;
+}
+
+function flushBuildOutputSummaries() {
+    if (buildOutputState.mode !== "build") return;
+    clearBuildProgressLine();
+
+    if (buildOutputState.assetFiles > 0) {
+        const msg = formatBuildInfoSummaryMessage(`✓ Bundled ${buildOutputState.assetFiles} files (${buildOutputState.assetTotalKb.toFixed(2)} kB${buildOutputState.assetGzipKb > 0 ? `, gzip ${buildOutputState.assetGzipKb.toFixed(2)} kB` : ""})`);
+        originalConsoleLog(msg);
+        captureLogMessage("server", "log", msg, null);
+    }
+
+    if (buildOutputState.compressionFiles > 0) {
+        const msg = formatBuildInfoSummaryMessage(`✓ Gzip compressed ${buildOutputState.compressionFiles} files (${buildOutputState.compressionTotalKb.toFixed(2)} kB → ${buildOutputState.compressionGzipKb.toFixed(2)} kB)`);
+        originalConsoleLog(msg);
+        captureLogMessage("server", "log", msg, null);
+    }
+
+    resetBuildOutputState();
+}
+
+function supportsColorOutput() {
+    return !!process.stdout?.isTTY && process.env.NO_COLOR !== "1";
+}
+
+/** @param {string} name @returns {string} */
+function formatNeedleHeader(name) {
+    if (!supportsColorOutput()) return `[${name}]`;
+    if (name.startsWith("needle-")) {
+        const suffix = name.substring("needle-".length);
+        return `\x1b[32m[\x1b[0m\x1b[32mneedle-\x1b[0m\x1b[1;32m${suffix}\x1b[0m\x1b[32m]\x1b[0m`;
+    }
+    if (name.startsWith("needle:")) {
+        const suffix = name.substring("needle:".length);
+        return `\x1b[32m[\x1b[0m\x1b[32mneedle:\x1b[0m\x1b[1;32m${suffix}\x1b[0m\x1b[32m]\x1b[0m`;
+    }
+    return `\x1b[32m[\x1b[0m\x1b[1;32m${name}\x1b[0m\x1b[32m]\x1b[0m`;
+}
+
+/** @param {string} body @returns {string} */
+function formatBuildInfoSummaryMessage(body) {
+    return `${formatNeedleHeader("needle-buildinfo")}\n${body}`;
+}
+
+/** @param {unknown[]} args @returns {string} */
+function normalizeConsoleArgs(args) {
+    return args.map(arg => typeof arg === "string" ? arg : stringifyLog(arg)).join(" ");
+}
+
+/** @param {unknown[]} args @returns {boolean} */
+function tryHandleBuildConsoleOutput(args) {
+    if (buildOutputState.mode !== "build") return false;
+
+    const raw = normalizeConsoleArgs(args);
+    const message = raw.replace(/\u001b\[[0-9;]*m/g, "").trim();
+    if (!message.length) return true;
+
+    if (/^transforming\s*\(/i.test(message)) {
+        writeBuildProgressLine(`⏳ ${message}`);
+        return true;
+    }
+
+    if (message.includes("[vite-plugin-compression]:algorithm=")) {
+        buildOutputState.compressionCaptureActive = true;
+        return true;
+    }
+
+    const assetMatch = message.match(/^dist\/.*?\s+([0-9.,]+)\s*kB(?:\s*[│|]\s*gzip:\s*([0-9.,]+)\s*kB)?$/i);
+    if (assetMatch) {
+        buildOutputState.assetFiles++;
+        buildOutputState.assetTotalKb += parseKb(assetMatch[1]);
+        if (assetMatch[2]) buildOutputState.assetGzipKb += parseKb(assetMatch[2]);
+        writeBuildProgressLine(`📦 Bundling assets: ${buildOutputState.assetFiles} files`);
+        return true;
+    }
+
+    if (buildOutputState.compressionCaptureActive) {
+        const compressionMatch = message.match(/^dist\/.*?\s+([0-9.]+)\s*kb\s*\/\s*gzip:\s*([0-9.]+)\s*kb$/i);
+        if (compressionMatch) {
+            buildOutputState.compressionFiles++;
+            buildOutputState.compressionTotalKb += parseKb(compressionMatch[1]);
+            buildOutputState.compressionGzipKb += parseKb(compressionMatch[2]);
+            writeBuildProgressLine(`🗜️ Compressing: ${buildOutputState.compressionFiles} files`);
+            return true;
+        }
+    }
+
+    if (message.startsWith("✓ built in")) {
+        flushBuildOutputSummaries();
+        return false;
+    }
+
+    flushBuildOutputSummaries();
+    return false;
+}
+
+/**
+ * @param {{command?: string} | undefined} [options]
+ * @returns {(() => void) | undefined}
+ */
+export function patchConsoleLogs(options = undefined) {
     if (didPatch) return unpatchFunction;
     didPatch = true;
+    buildOutputState.mode = options?.command === "build" ? "build" : "serve";
+    resetBuildOutputState();
 
     console.log = (...args) => {
+        if (tryHandleBuildConsoleOutput(args)) return;
         originalConsoleLog(...args);
         captureLogMessage("server", 'log', args, null);
     };
     console.error = (...args) => {
+        flushBuildOutputSummaries();
         originalConsoleError(...args);
         captureLogMessage("server", 'error', args, null);
     };
     console.warn = (...args) => {
+        flushBuildOutputSummaries();
         originalConsoleWarn(...args);
         captureLogMessage("server", 'warn', args, null);
     };
     console.info = (...args) => {
+        if (tryHandleBuildConsoleOutput(args)) return;
         originalConsoleInfo(...args);
         captureLogMessage("server", 'info', args, null);
     };
     console.debug = (...args) => {
+        if (tryHandleBuildConsoleOutput(args)) return;
         originalConsoleDebug(...args);
         captureLogMessage("server", 'debug', args, null);
     };
 
     // Restore original console methods
     unpatchFunction = () => {
+        flushBuildOutputSummaries();
         didPatch = false;
         console.log = originalConsoleLog;
         console.error = originalConsoleError;
         console.warn = originalConsoleWarn;
         console.info = originalConsoleInfo;
         console.debug = originalConsoleDebug;
+        buildOutputState.mode = "serve";
     }
     return unpatchFunction;
 }
 
 
 let isCapturing = false;
-/** @type {Set<string>} */
+/** @type {Set<unknown>} */
 const isCapturingLogMessage = new Set();
 
-/** @type {Array<{ process: ProcessType, key: string, log:any, timestamp:number, connectionId: string | null }>} */
+/** @type {Array<{ process: ProcessType, key: string, log:unknown, timestamp:number, connectionId: string | null }>} */
 const queue = new Array();
 
 /**
  * @param {ProcessType} process
  * @param {string} key
- * @param {any} log
+ * @param {unknown} log
  * @param {string | null} connectionId - Optional connection ID for client logs.
  * @param {number} [time] - Optional timestamp, defaults to current time.
  */
@@ -109,10 +262,10 @@ export function captureLogMessage(process, key, log, connectionId, time = Date.n
 
 /**
  * Stringifies a log message, handling circular references and formatting.
- * @param {any} log
- * @param {Set<any>} [seen]
+ * @param {unknown} log
+ * @param {Set<unknown>} [seen]
  */
-function stringifyLog(log, seen = new Set(), depth = 0) {
+function stringifyLog(log, seen = /** @type {Set<unknown>} */ (new Set()), depth = 0) {
     const isServer = typeof window === "undefined";
     const stringify_limits = {
         string: isServer ? 100_000 : 1_000,
@@ -154,8 +307,9 @@ function stringifyLog(log, seen = new Set(), depth = 0) {
         || log instanceof BigUint64Array
         || log instanceof Float64Array
     ) {
-        seen.add(log);
-        return stringifyArray(log);
+        const logArr = /** @type {ArrayLike<unknown>} */ (/** @type {unknown} */ (log));
+        seen.add(logArr);
+        return stringifyArray(logArr);
     }
     if (typeof log === "object") {
 
@@ -169,11 +323,12 @@ function stringifyLog(log, seen = new Set(), depth = 0) {
             return `<Error: ${log.message}\nStack: ${log.stack}>`;
         }
 
-        const keys = Object.keys(log);
+        const logObj = /** @type {Record<string, unknown>} */ (log);
+        const keys = Object.keys(logObj);
         let res = "{";
         for (let i = 0; i < keys.length; i++) {
             const key = keys[i];
-            let value = log[key];
+            let value = logObj[key];
             if (i >= stringify_limits.object_keys) {
                 res += `, ... <truncated ${keys.length - i} keys>`;
                 break;
@@ -208,6 +363,7 @@ function stringifyLog(log, seen = new Set(), depth = 0) {
 
     return String(log);
 
+    /** @param {ArrayLike<unknown>} arr @returns {string} */
     function stringifyArray(arr) {
         let res = "";
         for (let i = 0; i < arr.length; i++) {
@@ -340,6 +496,11 @@ function onExit() {
     filestreams.forEach((stream) => stream.end());
     filestreams.clear();
 }
+
+export function closeLogStreams() {
+    onExit();
+}
+
 const events = ['SIGTERM', 'SIGINT', 'beforeExit', 'rejectionHandled', 'uncaughtException', 'exit'];
 for (const event of events) {
     process.on(event, onExit);

package/plugins/common/needle-engine-skill.md

@@ -0,0 +1,175 @@
+---
+name: needle-engine
+description: Automatically provides Needle Engine context when working in a Needle Engine web project. Use this skill when editing TypeScript components, Vite config, GLB assets, or anything related to @needle-tools/engine.
+---
+
+# Needle Engine
+
+You are an expert in Needle Engine — a web-first 3D engine built on Three.js with a Unity/Blender-based workflow.
+
+## Key concepts
+
+**Needle Engine** ships 3D scenes from Unity (or Blender) as GLB files and renders them in the browser using Three.js. TypeScript components attached to GameObjects in Unity are serialized into the GLB and re-hydrated at runtime in the browser.
+
+### Embedding in HTML
+```html
+<!-- The <needle-engine> web component creates and manages a 3D context -->
+<needle-engine src="assets/scene.glb"></needle-engine>
+```
+Access the context programmatically: `document.querySelector("needle-engine").context`
+
+### Component lifecycle (mirrors Unity MonoBehaviour)
+```ts
+import { Behaviour, serializable, registerType } from "@needle-tools/engine";
+
+@registerType
+export class MyComponent extends Behaviour {
+  @serializable() myValue: number = 1;
+
+  awake()  {}   // called once when instantiated
+  start()  {}   // called once on first frame
+  update() {}   // called every frame
+  onEnable()  {}
+  onDisable() {}
+  onDestroy() {}
+  onBeforeRender(_frame: XRFrame | null) {}
+}
+```
+
+### Serialization
+- `@registerType` — makes the class discoverable by the GLB deserializer
+- `@serializable()` — marks a field for GLB deserialization (primitives)
+- `@serializable(Object3D)` — for Three.js object references
+- `@serializable(Texture)` — for textures (import Texture from "three")
+- `@serializable(RGBAColor)` — for colors
+
+### Accessing the scene
+```ts
+this.context.scene       // THREE.Scene
+this.context.mainCamera  // active camera (THREE.Camera)
+this.context.renderer    // THREE.WebGLRenderer
+this.context.time.frame  // current frame number
+this.context.time.deltaTime  // seconds since last frame
+this.gameObject          // the THREE.Object3D this component is on
+```
+
+### Finding components
+```ts
+this.gameObject.getComponent(MyComponent)
+this.gameObject.getComponentInChildren(MyComponent)
+this.context.scene.getComponentInChildren(MyComponent)
+
+// Global search (import as standalone functions from "@needle-tools/engine")
+import { findObjectOfType, findObjectsOfType } from "@needle-tools/engine";
+findObjectOfType(MyComponent, this.context)
+findObjectsOfType(MyComponent, this.context)
+```
+
+### Input handling
+```ts
+// Polling
+if (this.context.input.getPointerDown(0)) { /* pointer pressed */ }
+if (this.context.input.getKeyDown("Space")) { /* space pressed */ }
+
+// Event-based (NEPointerEvent works across mouse, touch, and XR controllers)
+this.gameObject.addEventListener("pointerdown", (e: NEPointerEvent) => { });
+```
+
+### Physics & raycasting
+```ts
+// Default raycasts hit visible geometry — no colliders needed
+// Uses mesh BVH (bounding volume hierarchy) for accelerated raycasting, BVH is generated on a worker
+const hits = this.context.physics.raycast();
+
+// Physics-based raycasts (require colliders, uses Rapier physics engine)
+const physicsHits = this.context.physics.raycastPhysics();
+```
+
+### Networking & multiplayer
+Needle Engine has built-in multiplayer. Add a `SyncedRoom` component to enable networking.
+
+- `@syncField()` — automatically syncs a field across all connected clients
+- Primitives (string, number, boolean) sync automatically on change
+- Complex types (arrays/objects) require reassignment to trigger sync: `this.myArray = this.myArray`
+- Key components: `SyncedRoom`, `SyncedTransform`, `PlayerSync`, `Voip`
+- Uses WebSockets + optional WebRTC peer-to-peer connections
+
+### WebXR (VR & AR)
+Needle Engine has built-in WebXR support for VR and AR across Meta Quest, Apple Vision Pro, and mobile AR.
+
+- Add the `WebXR` component to enable VR/AR sessions
+- Use `XRRig` to define the user's starting position — the user is parented to the rig during XR sessions
+- Available components: `WebXRImageTracking`, `WebXRPlaneTracking`, `XRControllerModel`, `NeedleXRSession`
+
+## Creating a new project
+
+Use `create-needle` to scaffold a new Needle Engine project:
+```bash
+npm create needle my-app            # default Vite template
+npm create needle my-app -t react   # React template
+npm create needle my-app -t vue     # Vue.js template
+```
+
+Available templates: `vite` (default), `react`, `vue`, `sveltekit`, `svelte`, `nextjs`, `react-three-fiber`.
+
+Use `npm create needle --list` to see all available templates.
+
+## Vite plugin system
+
+Needle Engine ships a set of Vite plugins via `needlePlugins(command, config, userSettings)`. Custom project plugins go in `vite.config.ts`.
+
+```ts
+import { defineConfig } from "vite";
+import { needlePlugins } from "@needle-tools/engine/vite";
+
+export default defineConfig(async ({ command }) => ({
+  plugins: [
+    ...(await needlePlugins(command, {}, {})),
+  ],
+}));
+```
+
+## Deployment
+
+Projects can be deployed to:
+- **Needle Cloud** — official hosting with automatic optimization (`npx needle-cloud deploy`)
+- **Vercel** / **Netlify** — standard web hosting
+- **itch.io** — for games and interactive experiences
+- **Any static host** — Needle Engine projects are standard Vite web apps
+
+From Unity, use built-in deployment components (e.g. `DeployToNeedleCloud`, `DeployToNetlify`).
+
+## Progressive loading (`@needle-tools/gltf-progressive`)
+
+Needle Engine includes `@needle-tools/gltf-progressive` for progressive streaming of 3D models and textures. It creates a tiny initial file with embedded low-quality proxy geometry, then streams higher-quality LODs on demand. Results in ~90% smaller initial downloads with instant display.
+
+Works standalone with any three.js project:
+```ts
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { WebGLRenderer } from "three";
+import { useNeedleProgressive } from "@needle-tools/gltf-progressive";
+
+const gltfLoader = new GLTFLoader();
+const renderer = new WebGLRenderer();
+
+// Register once — progressive loading happens automatically for all subsequent loads
+useNeedleProgressive(gltfLoader, renderer);
+
+gltfLoader.load(url, (gltf) => scene.add(gltf.scene));
+```
+
+In Needle Engine projects, progressive loading is built in and can be configured via the **Compression & LOD Settings** component in Unity.
+
+## Important URLs
+- Docs: https://engine.needle.tools/docs/
+- Samples: https://engine.needle.tools/samples/
+- GitHub: https://github.com/needle-tools/needle-engine-support
+- npm: https://www.npmjs.com/package/@needle-tools/engine
+
+## Searching the documentation
+
+Use the `needle_search` MCP tool to find relevant docs, forum posts, and community answers.
+
+## Common gotchas
+- Components must use `@registerType` or they won't be instantiated from GLB (this is handled automatically when exporting from Unity or Blender, but must be added manually for hand-written components)
+- GLB assets are in `assets/`, static files in `include/` or `public/`

package/plugins/common/worker.js

@@ -1,3 +1,4 @@
+import { needleLog } from '../vite/logging.js';
 
 
 
@@ -51,12 +52,12 @@ export function rollupFixWorkerImport(opts = { logFail: true }) {
                         regexMatchedWorkerCode = true;
                         // console.log("WORKER?", url)
                         if (url?.startsWith("/")) {
-                            console.log(`[rollup] Rewrite worker import in ${chunk.fileName}`);
+                            needleLog("rollup", `Rewrite worker import in ${chunk.fileName}`, "log", { leadingNewline: true, dimBody: false });
                             // Make url file-relative
                             const newUrl = url.replace(/^\//, "");
                             // For CORS issues we need to use importScripts: https://linear.app/needle/issue/NE-6572#comment-ea5dc65e
                             const output = `/* new-worker */ new Worker(URL.createObjectURL(new Blob(["import '" + \`\${new URL('./${newUrl}', import.meta.url).toString()}\` + "';"], { type: 'text/javascript' }))`;
-                            console.log("[rollup] Did rewrite worker output to:", output);
+                            needleLog("rollup", "Did rewrite worker output to: " + output, "log", { leadingNewline: true });
                             return output;
                             // return `new Worker(new URL("./${newUrl}", import.meta.url)`;
                         }
@@ -70,7 +71,7 @@ export function rollupFixWorkerImport(opts = { logFail: true }) {
                         }
                         if (opts?.logFail !== false) {
                             const str = `[...]${code.substring(newWorkerStartIndex, newWorkerStartIndex + 200)}[...]`
-                            console.warn(`\n[rollup] Worker import in ${chunk.fileName} was not rewritten: ${str}`);
+                            needleLog("rollup", `Worker import in ${chunk.fileName} was not rewritten: ${str}`, "warn", { leadingNewline: true, dimBody: false });
                         }
                     }
                     return res;
@@ -116,7 +117,7 @@ function fixWorkerSelfLocation(filename, code) {
                 const fixedCode = workerCode.replace("self.location", "import.meta.url");
                 code = code.substring(0, startIndex) + fixedCode + code.substring(endIndex + 1);
                 lastIndex = startIndex + fixedCode.length;
-                console.log(`[rollup] Rewrite worker 'self.location' to 'import.meta.url' in ${filename}`);
+                needleLog("rollup", `Rewrite worker 'self.location' to 'import.meta.url' in ${filename}`, "log", { leadingNewline: true, dimBody: false });
             } else {
                 lastIndex = endIndex;
             }

package/plugins/types/userconfig.d.ts

@@ -112,10 +112,48 @@ export type userSettings = {
     debugLicense?: boolean;
 
     /**
-     * Experimental: When enabled then fonts from google fonts will be downloaded and copied to the output directory
+     * When enabled, external CDN URLs are downloaded at build time and bundled locally.
+     * This creates fully self-contained deployments that work without internet access.
+     * 
+     * - `true` — enable with all features (download everything)
+     * - `"auto"` — automatically detect which features the project uses and only include those
+     * - `{ enabled: true }` — same as `true`
+     * - `{ enabled: true, features: "auto" }` — same as `"auto"`
+     * - `{ enabled: true, features: ["draco", "ktx2"] }` — only include specific features
+     * - `{ enabled: true, excludeFeatures: ["xr"] }` — include all except specific features
+     * - `{ enabled: true, features: "auto", excludeFeatures: ["skybox"] }` — auto-detect but exclude specific features
+     * 
+     * Available features:
+     * - `"draco"` — Draco mesh decoders
+     * - `"ktx2"` — KTX2/Basis texture transcoders
+     * - `"materialx"` — MaterialX WASM shader compiler
+     * - `"xr"` — WebXR input profiles (controllers/hands)
+     * - `"skybox"` — Skybox/environment textures
+     * - `"fonts"` — Google Fonts CSS + font files
+     * - `"needle-fonts"` — Needle font assets (MSDF, etc.)
+     * - `"needle-models"` — Needle models
+     * - `"needle-avatars"` — Needle avatars
+     * - `"polyhaven"` — Polyhaven HDRIs/models
+     * - `"cdn-scripts"` — Third-party scripts (QRCode.js, vConsole, HLS.js)
+     * - `"github-content"` — GitHub raw content files
+     * - `"threejs-models"` — three.js example models
+     * - `"needle-uploads"` — Needle uploads assets
      */
-    makeFilesLocal?: boolean | {
+    makeFilesLocal?: boolean | "auto" | {
         enabled: boolean;
+        /** URL patterns to exclude from making local */
+        exclude?: string[];
+        /** Target platform preset */
+        platform?: "discord" | "facebook-instant" | null;
+        /** 
+         * Feature categories to include.
+         * - `"auto"` — Automatically detect which features the project uses.
+         * - `FeatureName[]` — Explicit list. When set, ONLY these features are processed.
+         * - When omitted, ALL features are included.
+         */
+        features?: "auto" | Array<"draco" | "ktx2" | "materialx" | "xr" | "skybox" | "fonts" | "needle-fonts" | "needle-models" | "needle-avatars" | "polyhaven" | "cdn-scripts" | "github-content" | "threejs-models" | "needle-uploads">;
+        /** Feature categories to exclude. Applied after `features` (including after auto-detection). */
+        excludeFeatures?: Array<"draco" | "ktx2" | "materialx" | "xr" | "skybox" | "fonts" | "needle-fonts" | "needle-models" | "needle-avatars" | "polyhaven" | "cdn-scripts" | "github-content" | "threejs-models" | "needle-uploads">;
     }
 
     /**

package/plugins/vite/ai.js

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const pluginName = "needle-ai";
+
+/**
+ * Needle Engine Claude skill installer.
+ *
+ * Writes a Needle Engine skill to `.claude/skills/needle-engine/SKILL.md`.
+ * Claude Code auto-loads skills based on their description frontmatter, so
+ * Claude will automatically have Needle Engine context when working in the project.
+ *
+ * The skill is only written if `.claude/` already exists in the project root
+ * (i.e. the developer is already using Claude Code). Old skill files are
+ * always overwritten so the skill stays up to date with the engine version.
+ *
+ * @param {"build" | "serve"} command
+ * @param {{} | undefined | null} config
+ * @param {import('../types/index.js').userSettings} userSettings
+ * @returns {import('vite').Plugin | null}
+ */
+export const needleAI = (command, config, userSettings) => {
+    return {
+        name: pluginName,
+        enforce: "pre",
+        buildStart() {
+            installClaudeSkill();
+        },
+        configureServer() {
+            installClaudeSkill();
+        },
+    };
+};
+
+/** 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) {
+    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);
+    writeFileSync(skillPath, content, "utf8");
+    return skillPath;
+}
+
+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);
+    console.log(`[${pluginName}] Installed Needle Engine Claude skill → ${path}`);
+}

package/plugins/vite/alias.js

@@ -1,5 +1,6 @@
 import { createWriteStream, existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
 import path from 'path';
+import { needleLog } from './logging.js';
 
 const projectDir = process.cwd() + "/";
 
@@ -77,7 +78,7 @@ export const needleViteAlias = (command, config, userSettings) => {
 
     let outputDebugFile = null;
     function log(...msg) {
-        console.log(...msg);
+        needleLog("needle-alias", msg.join(" "));
         if (debug) logToFile(...msg);
     }
     function logToFile(...msg) {
@@ -91,7 +92,7 @@ export const needleViteAlias = (command, config, userSettings) => {
         const timestamp = new Date().toISOString();
         outputDebugFile.write("\n\n\n--------------------------\n");
         outputDebugFile.write(`[needle-alias] Logging to: ${outputFilePath} (${timestamp})\n`);
-        log("[needle-alias] Logging to: ", outputFilePath);
+        log("Logging to:", outputFilePath);
     }
 
 
@@ -99,7 +100,7 @@ export const needleViteAlias = (command, config, userSettings) => {
     const aliasPlugin = {
         name: "needle-alias",
         config(config) {
-            if (debug) console.log('[needle-alias] ProjectDirectory: ' + projectDir);
+            if (debug) log('ProjectDirectory: ' + projectDir);
             if (!config.resolve) config.resolve = {};
             if (!config.resolve.alias) config.resolve.alias = {};
             const aliasDict = config.resolve.alias;
@@ -119,7 +120,7 @@ export const needleViteAlias = (command, config, userSettings) => {
                 config.optimizeDeps.exclude ??= [];
                 if (!config.optimizeDeps.include?.includes('@needle-tools/engine')) {
                     config.optimizeDeps.exclude.push('@needle-tools/engine');
-                    log("[needle-alias] Detected local @needle-tools/engine package → will exclude it from optimization");
+                    log("Detected local @needle-tools/engine package → will exclude it from optimization");
                 }
             }
 
@@ -132,7 +133,7 @@ export const needleViteAlias = (command, config, userSettings) => {
                     if (typeof entry === "function") res = entry(name, 0, name);
                     testResults.push({ name, entry: res });
                 }
-                console.log('[needle-alias] Aliases: ', testResults);
+                log('Aliases: ' + JSON.stringify(testResults));
             }
         },
     }