@needle-tools/engine 5.1.0-alpha.1 → 5.1.0-alpha.3

package/plugins/dts-generator/glb.reader.js

@@ -0,0 +1,167 @@
+// @ts-check
+/**
+ * GLB / glTF JSON chunk readers — local files and remote URLs.
+ *
+ * All functions return the parsed glTF JSON object or null on failure.
+ * Remote fetches use HTTP Range requests and cache by Last-Modified header.
+ */
+
+import { openSync, readSync, closeSync, readFileSync } from 'fs';
+import { needleLog } from '../vite/logging.js';
+
+const PLUGIN = "needle:dts-generator";
+
+/**
+ * Read the JSON chunk from a binary GLB file without loading the binary blob.
+ * @param {string} filePath
+ * @returns {Record<string, unknown> | null}
+ */
+export function readGlbJsonChunk(filePath) {
+    const fd = openSync(filePath, "r");
+    try {
+        const header = Buffer.allocUnsafe(20);
+        const bytesRead = readSync(fd, header, 0, header.length, 0);
+        if (bytesRead < 20) return null;
+
+        const magic = header.readUInt32LE(0);
+        const version = header.readUInt32LE(4);
+        const chunkLength = header.readUInt32LE(12);
+        const chunkType = header.readUInt32LE(16);
+
+        if (magic !== 0x46546c67 || version !== 2) return null;
+        if (chunkType !== 0x4E4F534A) return null; // not JSON chunk
+
+        const jsonBuffer = Buffer.allocUnsafe(chunkLength);
+        const jsonBytesRead = readSync(fd, jsonBuffer, 0, chunkLength, 20);
+        if (jsonBytesRead < chunkLength) return null;
+
+        return JSON.parse(jsonBuffer.toString("utf8").replace(/\u0000+$/g, ""));
+    } catch (_e) {
+        return null;
+    } finally {
+        closeSync(fd);
+    }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Record<string, unknown> | null}
+ */
+export function readGltfJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    } catch (_e) {
+        return null;
+    }
+}
+
+/**
+ * Parse the filename from a `Content-Disposition` header value.
+ * Handles `filename="foo.glb"` and `filename*=UTF-8''foo.glb` forms.
+ * Returns null if not present or not parseable.
+ * @param {string | null} header
+ * @returns {string | null}
+ */
+export function parseContentDispositionFilename(header) {
+    if (!header) return null;
+    // RFC 5987 extended form: filename*=UTF-8''foo.glb
+    const extMatch = header.match(/filename\*\s*=\s*(?:[^']*'')?([^;]+)/i);
+    if (extMatch) {
+        try { return decodeURIComponent(extMatch[1].trim()); } catch (_e) { /* fall through */ }
+    }
+    // Plain form: filename="foo.glb" or filename=foo.glb
+    const plainMatch = header.match(/filename\s*=\s*"?([^";]+)"?/i);
+    if (plainMatch) return plainMatch[1].trim();
+    return null;
+}
+
+/** @type {Map<string, { lastModified: string, json: Record<string, unknown>, filename: string | null }>} */
+const _remoteGlbCache = new Map();
+
+/**
+ * Fetch the JSON chunk of a remote GLB.
+ * Tries an initial Range request for the header bytes; if the server already returned
+ * enough data (200 + full body, or 206 with sufficient bytes) the JSON chunk is
+ * extracted directly. Otherwise a second Range request fetches the JSON chunk.
+ * Uses `Last-Modified` header for caching — avoids re-parsing if unchanged.
+ * Also captures `Content-Disposition` filename for friendly key generation.
+ * Returns `null` on any network or parse error.
+ *
+ * @param {string} url
+ * @returns {Promise<{ json: Record<string, unknown>, filename: string | null } | null>}
+ */
+export async function readRemoteGlbJsonChunk(url) {
+    try {
+        const cached = _remoteGlbCache.get(url);
+
+        const headerRes = await fetch(url, { headers: { Range: "bytes=0-19" } });
+        if (!headerRes.ok) {
+            needleLog(PLUGIN, `Remote GLB fetch failed (${headerRes.status}): ${url}`, "warn");
+            return null;
+        }
+
+        const lastModified = headerRes.headers.get("Last-Modified") ?? "";
+        const filename = parseContentDispositionFilename(headerRes.headers.get("Content-Disposition"));
+
+        if (cached && lastModified && cached.lastModified === lastModified) {
+            // Prefer the filename we resolved during the full fetch (may have come from the JSON chunk
+            // response). Only fall back to the fresh header value if the cache has nothing.
+            return { json: cached.json, filename: cached.filename ?? filename };
+        }
+
+        const firstBytes = Buffer.from(await headerRes.arrayBuffer());
+        if (firstBytes.length < 20) return null;
+
+        const magic = firstBytes.readUInt32LE(0);
+        const version = firstBytes.readUInt32LE(4);
+        const chunkLength = firstBytes.readUInt32LE(12);
+        const chunkType = firstBytes.readUInt32LE(16);
+
+        if (magic !== 0x46546c67 || version !== 2) return null; // not a GLB
+        if (chunkType !== 0x4E4F534A) return null;              // chunk0 not JSON
+
+        let jsonBytes;
+        let resolvedFilename = filename;
+
+        if (firstBytes.length >= 20 + chunkLength) {
+            // The first response already contained the full JSON chunk (server ignored Range or returned 200).
+            jsonBytes = firstBytes.slice(20, 20 + chunkLength);
+        } else {
+            // Try a second Range request for just the JSON chunk bytes.
+            const jsonEnd = 20 + chunkLength - 1;
+            const jsonRes = await fetch(url, { headers: { Range: `bytes=20-${jsonEnd}` } });
+            if (!jsonRes.ok) {
+                needleLog(PLUGIN, `Remote GLB JSON chunk fetch failed (${jsonRes.status}): ${url}`, "warn");
+                return null;
+            }
+            const jsonResBytes = Buffer.from(await jsonRes.arrayBuffer());
+            // Server may return 200 + full body even for a Range request — slice out our window.
+            if (jsonResBytes.length >= 20 + chunkLength) {
+                jsonBytes = jsonResBytes.slice(20, 20 + chunkLength);
+            } else if (jsonResBytes.length >= chunkLength) {
+                jsonBytes = jsonResBytes.slice(0, chunkLength);
+            } else {
+                needleLog(PLUGIN, `Remote GLB unexpected response (${jsonRes.status}, ${jsonResBytes.length} bytes, expected ${chunkLength}): ${url}`, "warn");
+                return null;
+            }
+
+            const filenameFromJsonRes = parseContentDispositionFilename(jsonRes.headers.get("Content-Disposition"));
+            resolvedFilename = filename ?? filenameFromJsonRes;
+        }
+
+        if (resolvedFilename === null) {
+            try {
+                const headRes = await fetch(url, { method: "HEAD" });
+                resolvedFilename = parseContentDispositionFilename(headRes.headers.get("Content-Disposition"));
+            } catch (_e) { /* ignore — fall back to URL-based name */ }
+        }
+        const json = /** @type {Record<string, unknown>} */ (
+            JSON.parse(jsonBytes.toString("utf8").replace(/\u0000+$/g, ""))
+        );
+        _remoteGlbCache.set(url, { lastModified, json, filename: resolvedFilename });
+        return { json, filename: resolvedFilename };
+    } catch (e) {
+        needleLog(PLUGIN, `Failed to fetch remote GLB: ${url} — ${/** @type {any} */ (e)?.message ?? e}`, "warn");
+        return null;
+    }
+}

package/plugins/dts-generator/index.js

@@ -0,0 +1,36 @@
+// @ts-check
+/**
+ * Needle Engine — HTML binding DTS generator
+ *
+ * Scans all GLB/glTF files in the project's assets directory, extracts
+ * NEEDLE_components data, and emits a `needle-bindings.d.ts` virtual-module
+ * declaration so that TypeScript can type-check HTML ↔ 3D component bindings.
+ *
+ * Typical generated output:
+ *
+ *   declare module "needle-bindings" {
+ *     interface SceneData {
+ *       Sphere: {
+ *         MyBall: { speed: number; label: string; };
+ *       };
+ *     }
+ *   }
+ *
+ * How component field types are resolved:
+ *   - For built-in Needle Engine components, types are read from
+ *     `components.needle.json` which lists only @serializable fields with
+ *     their proper TypeScript types.
+ *   - For user-defined components (not in the manifest), types are inferred
+ *     from the JSON value in the GLB (number/string/boolean → typed, else → unknown).
+ *   - Known Three.js types (Color, Vector3, Object3D, …) are emitted as
+ *     `import("three").TypeName` and known Needle types (RGBAColor, AssetReference, …)
+ *     as `import("@needle-tools/engine").TypeName`.
+ *   - Truly unknown types fall back to `unknown`.
+ */
+
+export { resolveEntrypointGlbs, collectSceneFiles } from './glb.discovery.js';
+export { readGlbJsonChunk, readGltfJsonFile, readRemoteGlbJsonChunk } from './glb.reader.js';
+export { extractComponentBindings, sanitizeNodeName, inferNodeThreeType, inferTsType } from './glb.extractor.js';
+export { scanBindings } from './dts.scan.js';
+export { generateDts, generateHtmlCustomData } from './dts.codegen.js';
+export { generateBindingsDts } from './dts.writer.js';

package/plugins/dts-generator/manifest.types.js

@@ -0,0 +1,174 @@
+// @ts-check
+/**
+ * Type tables and components.needle.json manifest loader.
+ *
+ * Knows about primitive TS types, known Three.js types, known Needle Engine
+ * types, and how to resolve field types from the manifest.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Primitive TS type strings that can safely appear in an ambient declaration. */
+export const PRIMITIVE_TYPES = new Set(["number", "string", "boolean"]);
+
+/**
+ * Known Three.js types → import("three").TypeName
+ * @type {Record<string, string>}
+ */
+export const THREE_TYPES = {
+    Color: `import("three").Color`,
+    ColorRepresentation: `import("three").ColorRepresentation`,
+    Euler: `import("three").Euler`,
+    Texture: `import("three").Texture`,
+    // Materials
+    Material: `import("three").Material`,
+    MeshStandardMaterial: `import("three").MeshStandardMaterial`,
+    // Objects
+    Object3D: `import("three").Object3D`,
+    Mesh: `import("three").Mesh`,
+    SkinnedMesh: `import("three").SkinnedMesh`,
+    // Other
+    Vector2: `import("three").Vector2`,
+    Vector3: `import("three").Vector3`,
+    Vector4: `import("three").Vector4`,
+    Matrix3: `import("three").Matrix3`,
+    Matrix4: `import("three").Matrix4`,
+    Quaternion: `import("three").Quaternion`,
+    // Animation
+    AnimationClip: `import("three").AnimationClip`,
+    AnimationMixer: `import("three").AnimationMixer`,
+};
+
+/**
+ * Known Needle Engine types → import("@needle-tools/engine").TypeName
+ * @type {Record<string, string>}
+ */
+export const NEEDLE_TYPES = {
+    AssetReference: `import("@needle-tools/engine").AssetReference`,
+    EventList: `import("@needle-tools/engine").EventList`,
+    GameObject: `import("@needle-tools/engine").GameObject`,
+    LookAtConstraint: `import("@needle-tools/engine").LookAtConstraint`,
+    RGBAColor: `import("@needle-tools/engine").RGBAColor`,
+    RenderTexture: `import("@needle-tools/engine").RenderTexture`,
+    Renderer: `import("@needle-tools/engine").Renderer`,
+    Rigidbody: `import("@needle-tools/engine").Rigidbody`,
+    Sprite: `import("@needle-tools/engine").Sprite`,
+    Vec2: `import("@needle-tools/engine").Vec2`,
+};
+
+/**
+ * Map a single non-array, non-primitive type token to its TS representation.
+ * Returns null if unknown.
+ * @param {string} token
+ * @returns {string | null}
+ */
+function mapKnownType(token) {
+    if (token in THREE_TYPES) return THREE_TYPES[token];
+    if (token in NEEDLE_TYPES) return NEEDLE_TYPES[token];
+    return null;
+}
+
+/**
+ * Convert a manifest type string to a safe ambient TS type.
+ * Primitives and known Three.js/Needle types are resolved precisely.
+ * For unknown types on a manifest component, falls back to
+ * `import("@needle-tools/engine").ComponentName["fieldName"]`.
+ * Truly unresolvable types → "unknown".
+ *
+ * @param {string} typeStr
+ * @param {string} [componentName]  The manifest component class name (enables indexed-access fallback)
+ * @param {string} [fieldName]      The field name on that component
+ * @returns {string}
+ */
+export function manifestTypeToTs(typeStr, componentName, fieldName) {
+    const parts = typeStr.split(" | ").map(p => p.trim());
+    const safeParts = parts.map(p => {
+        if (p === "undefined" || p === "null") return p;
+        const arrayMatch = p.match(/^(number|string|boolean)\[\]$/);
+        if (arrayMatch) return p;
+        if (PRIMITIVE_TYPES.has(p)) return p;
+        const arrayTypeMatch = p.match(/^(\w+)\[\]$/);
+        if (arrayTypeMatch) {
+            const base = arrayTypeMatch[1];
+            const mapped = mapKnownType(base);
+            if (mapped) return `${mapped}[]`;
+        }
+        const known = mapKnownType(p);
+        if (known) return known;
+        return null;
+    });
+    if (safeParts.every(p => p !== null)) {
+        return /** @type {string[]} */ (safeParts).join(" | ");
+    }
+    if (componentName && fieldName) {
+        return `import("@needle-tools/engine").${componentName}["${fieldName}"]`;
+    }
+    return "unknown";
+}
+
+/**
+ * Load components.needle.json and build a lookup:
+ *   componentName → Map<fieldName, tsType>
+ * Inherited fields are flattened (inheritedFrom chain is resolved).
+ *
+ * @returns {Map<string, Map<string, string>>}
+ */
+export function loadComponentsManifest() {
+    /** @type {Map<string, Map<string, string>>} */
+    const manifest = new Map();
+    const manifestPath = join(__dirname, "../../components.needle.json");
+    if (!existsSync(manifestPath)) return manifest;
+    try {
+        /** @type {Array<{name: string, inheritedFrom?: string, children?: Array<{name: string, kind: string, type: string}>}>} */
+        const entries = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+        /** @type {Map<string, Map<string, string>>} */
+        const ownFields = new Map();
+        /** @type {Map<string, string>} */
+        const inheritedFrom = new Map();
+        for (const entry of entries) {
+            if (!entry.name) continue;
+            inheritedFrom.set(entry.name, entry.inheritedFrom || "");
+            /** @type {Map<string, string>} */
+            const fields = new Map();
+            if (Array.isArray(entry.children)) {
+                for (const child of entry.children) {
+                    if (child.kind === "property" && child.name && child.type) {
+                        fields.set(child.name, manifestTypeToTs(child.type, entry.name, child.name));
+                    }
+                }
+            }
+            ownFields.set(entry.name, fields);
+        }
+
+        /** @param {string} name @returns {Map<string, string>} */
+        function resolveFields(name) {
+            if (manifest.has(name)) return /** @type {Map<string, string>} */ (manifest.get(name));
+            const own = ownFields.get(name) ?? new Map();
+            const parent = inheritedFrom.get(name);
+            if (parent && ownFields.has(parent)) {
+                const parentFields = resolveFields(parent);
+                const merged = new Map([...parentFields, ...own]);
+                manifest.set(name, merged);
+                return merged;
+            }
+            manifest.set(name, own);
+            return own;
+        }
+
+        for (const name of ownFields.keys()) {
+            resolveFields(name);
+        }
+    } catch (e) {
+        console.warn("[needle:dts-generator] Failed to load components.needle.json:", (/** @type {any} */ (e))?.message ?? e);
+    }
+    return manifest;
+}
+
+/** @type {Map<string, Map<string, string>>} */
+export const componentsManifest = loadComponentsManifest();

package/plugins/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./needleConfig.js";
 export * from './userconfig.js';
-export * from "./webmanifest.js";
+export * from "./webmanifest.js";
+export * from "./needle-bindings.js";

package/plugins/types/needle-bindings.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ambient module declaration for `needle-bindings`.
+ *
+ * `SceneData` is keyed by GLB friendly name, then by the node hierarchy:
+ *   ctx.sceneData.Minimal.Camera.$object          // → THREE.Camera
+ *   ctx.sceneData.Minimal.Camera.$components.OrbitControls.autoRotate = true;
+ *   ctx.sceneData.Minimal.UI.Button.$components.Button
+ *
+ * Each node entry has:
+ *   $object      — the Three.js Object3D (typed precisely, e.g. Mesh, Camera, Light)
+ *   $components  — Needle components attached to this node
+ *   [childName]  — child nodes, recursively typed
+ *
+ * When the `needle:dts-generator` Vite plugin is active it writes
+ * `.needle/generated/needle-bindings.gen.d.ts` next to the installed package,
+ * which augments this interface with the actual bindings extracted from
+ * the project's GLB files at build time.
+ */
+
+// Pull in the project-local generated augmentation (written by needle:dts-generator).
+/// <reference path="../../.needle/generated/needle-bindings.gen.d.ts" />
+
+declare module "needle-bindings" {
+    /**
+     * Scene data keyed by GLB friendly name, then by node hierarchy.
+     * Fallback index signature allows unknown names without crashing.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface SceneData {}
+}

package/plugins/types/userconfig.d.ts

@@ -26,10 +26,17 @@ export type userSettings = {
     noCopy?: boolean;
     /** When enabled the needle-engine include directory will be copied */
     copyIncludesFromEngine?: boolean;
-    /** set to false to tree-shake rapier physics engine to the reduce bundle size */
+
+
+    /** Set to `false` to prevent the Rapier physics engine from loading.  
+     * NOTE: by default Needle Engine uses dynamic loading of the Rapier physics engine. This means that the Rapier code is only loaded when a physics component is used in the scene.
+     */
     useRapier?: boolean;
-    /** experimental */
+    /** Set to `false` to prevent postprocessing effects from loading.  
+     * NOTE: by default Needle Engine uses dynamic loading of postprocessing modules. This means that the postprocessing code is only loaded when a postprocessing effect is used in the scene.
+     */
     usePostprocessing?: boolean;
+
     noDependencyWatcher?: boolean;
     /** set to false to suppress editor-sync package installation and connection */
     dontInstallEditor?: boolean;
@@ -169,4 +176,16 @@ export type userSettings = {
 
     /** Set to true to disable the plugin that ensures VSCode workspace settings for custom-elements.json data */
     noCustomElementData?: boolean;
+
+    /**   
+     * Generate Typescript declaration files for references 3D assets in your project.  
+     * These will be available via `context.sceneData` in your code.
+     * @default enabled
+     */
+    dts?: {
+        /** When set to false, disables the generation of TypeScript declaration files. 
+         * @default true
+         */
+        enabled?: boolean;
+    }
 }

package/plugins/vite/asap.js

@@ -22,7 +22,7 @@ export async function needleAsap(command, config, userSettings) {
 
     fixMainTs();
 
-    if (command != "build") {
+    if (command === "serve") {
         return null;
     }
 
@@ -50,7 +50,7 @@ export async function needleAsap(command, config, userSettings) {
                 const tags = [];
 
                 try {
-                    generateGltfPreloadLinks(config, html, tags);
+                    generateGltfPreloadLinks(config, html, tags, viteConfig?.base);
                 }
                 catch (err) {
                     console.error("Error generating gltf preload links", err);
@@ -173,18 +173,21 @@ function fixMainTs() {
  * @param {import('vite').ResolvedConfig} _config
  * @param {import('vite').HtmlTagDescriptor[]} tags
  */
-function generateScriptPreloadLinks(_config, tags) {
+function generateScriptPreloadLinks(config, tags) {
     try {
+        const base = config.base || '/';
         const chunks = preloadScriptPaths;
         // console.log("ASAP", chunks)
         if (chunks.length > 0) {
             for (const chunk of chunks) {
+                // Apply base path so preload hrefs resolve correctly under SPA routing
+                const href = chunk.startsWith('./') ? base + chunk.slice(2) : chunk;
                 tags.push({
                     tag: 'link',
                     attrs: {
                         rel: "modulepreload",
                         as: "script",
-                        href: chunk,
+                        href: href,
                     }
                 });
             }
@@ -203,15 +206,16 @@ const codegenRegex = /\"(?<gltf>.+(.glb|.gltf)(\?.*)?)\"/gm;
 /**
  * @param {import('../types').needleConfig} config
  * @param {string} html
- * @param {import('vite').HtmlTagDescriptor[]} tags 
+ * @param {import('vite').HtmlTagDescriptor[]} tags
+ * @param {string} [base]
  **/
-function generateGltfPreloadLinks(config, html, tags) {
+function generateGltfPreloadLinks(config, html, tags, base) {
 
     // TODO: try to get the <needle-engine src> element src attribute and preload that
     const needleEngineMatches = tryParseNeedleEngineSrcAttributeFromHtml(html);
     if (needleEngineMatches?.length) {
         for (const item of needleEngineMatches) {
-            insertPreloadLink(tags, item, "model/gltf+json");
+            insertPreloadLink(tags, item, "model/gltf+json", base);
         }
     }
 
@@ -246,7 +250,7 @@ function generateGltfPreloadLinks(config, html, tags) {
                             }
                         }
                         needleLog("needle:asap", `Insert glTF preload link: ${value}`);
-                        insertPreloadLink(tags, value, "model/gltf+json");
+                        insertPreloadLink(tags, value, "model/gltf+json", base);
                     }
                 }
             }
@@ -258,9 +262,14 @@ function generateGltfPreloadLinks(config, html, tags) {
  * @param {import('vite').HtmlTagDescriptor[]} tags
  * @param {string} href
  * @param {string} type
+ * @param {string} [base]
  */
-function insertPreloadLink(tags, href, type) {
+function insertPreloadLink(tags, href, type, base) {
     if (!href) return;
+    // Apply base path so preload hrefs resolve correctly under SPA routing
+    if (base && !href.startsWith('http') && !href.startsWith('/')) {
+        href = base + (href.startsWith('./') ? href.slice(2) : href);
+    }
     tags.push({
         tag: 'link',
         attrs: {

package/plugins/vite/dependencies.js

@@ -61,6 +61,35 @@ export function needleDependencies(command, config, userSettings) {
                 }
             },
         },
+        // Vite 8's optimizer rebases `new URL(specifier, import.meta.url)` paths
+        // inside pre-bundled dependencies (PR #21434), but only handles truly relative
+        // paths (./  ../).  Bare-specifier paths like `three-mesh-bvh/src/workers/...`
+        // are treated as relative to the *source file* that contained the `new URL()`
+        // call, producing a wrong URL such as:
+        //   /node_modules/@needle-tools/engine/.../three-mesh-bvh/src/workers/generateMeshBVH.worker.js
+        // This middleware rewrites those broken URLs so the dev server finds the file at
+        // its real location in node_modules.
+        {
+            name: 'needle:worker-url-rewrite',
+            configureServer(server) {
+                const rewritePackages = ['three-mesh-bvh'];
+                server.middlewares.use((req, _res, next) => {
+                    if (req.url) {
+                        for (const pkg of rewritePackages) {
+                            const marker = `/${pkg}/`;
+                            if (req.url.includes(marker) && !req.url.startsWith(`/node_modules/${pkg}/`)) {
+                                const idx = req.url.indexOf(marker);
+                                const rewritten = '/node_modules' + req.url.slice(idx);
+                                needleLog('needle-dependencies', `Rewriting worker URL → ${rewritten}`);
+                                req.url = rewritten;
+                                break;
+                            }
+                        }
+                    }
+                    next();
+                });
+            },
+        },
     ]
 }
 

package/plugins/vite/dependency-watcher.d.ts

@@ -1,10 +1,10 @@
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | null}
  */
-export function needleDependencyWatcher(command: "build" | "serve", _config: unknown, userSettings: import("../types").userSettings): import("vite").Plugin | null;
+export function needleDependencyWatcher(_command: "build" | "serve" | undefined, _config: unknown, userSettings: import("../types").userSettings): import("vite").Plugin | null;
 export type PackageJson = {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;

package/plugins/vite/dependency-watcher.js

@@ -12,14 +12,12 @@ function log(...msg) {
 }
 
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {unknown} _config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | null}
  */
-export function needleDependencyWatcher(command, _config, userSettings) {
-    if (command === "build") return null;
-
+export function needleDependencyWatcher(_command, _config, userSettings) {
     if (userSettings?.noDependencyWatcher === true) return null;
 
     const dir = process.cwd();
@@ -28,6 +26,7 @@ export function needleDependencyWatcher(command, _config, userSettings) {
 
     return /** @type {import('vite').Plugin} */ ({
         name: 'needle-dependency-watcher',
+        apply: 'serve',
         /** @param {import('vite').ViteDevServer} server */
         configureServer(server) {
             manageClients(server);

package/plugins/vite/drop.d.ts

@@ -1,7 +1,7 @@
 /** Experimental, allow dropping files from Unity into the running scene.
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types/userconfig.js').userSettings} userSettings
  * @returns {import('vite').Plugin | null | undefined}
  */
-export function needleDrop(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types/userconfig.js").userSettings): import("vite").Plugin | null | undefined;
+export function needleDrop(_command: "build" | "serve" | undefined, config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types/userconfig.js").userSettings): import("vite").Plugin | null | undefined;

package/plugins/vite/drop.js

@@ -7,18 +7,17 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 /** Experimental, allow dropping files from Unity into the running scene.
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types/userconfig.js').userSettings} userSettings
  * @returns {import('vite').Plugin | null | undefined}
  */
-export function needleDrop(command, config, userSettings) {
-    if (command === "build") return;
-    
+export function needleDrop(_command, config, userSettings) {
     if(userSettings.useDrop !== true) return null;
 
     return {
         name: "needle:drop",
+        apply: 'serve',
         config(/** @type {{ server?: { hmr?: { port?: number } } }} */ viteConfig) {
             if(userSettings)
             if (!viteConfig.server) viteConfig.server = {};

package/plugins/vite/dts-generator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {"build" | "serve"} _command  Vite command (unused — runs in both modes)
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} _config
+ * @param {import('../types').userSettings} [_userSettings]
+ * @returns {import('vite').Plugin | null}
+ */
+export function needleDtsGenerator(_command: "build" | "serve", _config: import("../types/needleConfig").needleMeta | null | undefined, _userSettings?: import("../types").userSettings): import("vite").Plugin | null;