@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.e6680fa

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

@@ -8,7 +8,63 @@
  */
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join, resolve } from 'path';
+import { join, basename, extname } from 'path';
+
+/**
+ * Generic URL path segments that carry no useful identity — fall back to
+ * the previous segment when the last segment matches one of these.
+ */
+const GENERIC_SEGMENTS = new Set(["file", "index", "scene", "assets", "glb", "gltf", "model", "download"]);
+
+/**
+ * Derive a short, human-friendly identifier from a GLB URL or local path.
+ *
+ * Rules (in priority order):
+ *  1. If `contentDispositionFilename` is provided → strip extension, use it.
+ *  2. Remote URL → walk path segments right-to-left, skip generic ones,
+ *     strip extension from first useful segment.
+ *  3. Local path → basename without extension.
+ *
+ * Result is identifier-safe: non-alphanumeric chars replaced with `_`,
+ * leading digits prefixed with `_`.
+ *
+ * @param {string} pathOrUrl
+ * @param {string | null} [contentDispositionFilename]
+ * @returns {string}
+ */
+export function glbFriendlyName(pathOrUrl, contentDispositionFilename) {
+    let raw = "";
+
+    if (contentDispositionFilename) {
+        raw = basename(contentDispositionFilename, extname(contentDispositionFilename));
+    } else if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
+        try {
+            const segments = new URL(pathOrUrl).pathname.split("/").filter(Boolean);
+            // Walk right-to-left, skip generic segments
+            for (let i = segments.length - 1; i >= 0; i--) {
+                const seg = segments[i];
+                const withoutExt = seg.replace(/\.(glb|gltf)$/i, "");
+                if (!GENERIC_SEGMENTS.has(withoutExt.toLowerCase())) {
+                    raw = withoutExt;
+                    break;
+                }
+            }
+            if (!raw) raw = segments[segments.length - 1] ?? "scene";
+        } catch (_e) {
+            raw = "scene";
+        }
+    } else {
+        raw = basename(pathOrUrl, extname(pathOrUrl));
+    }
+
+    // Make identifier-safe
+    let id = raw.replace(/[^a-zA-Z0-9]/g, "_");
+    if (/^\d/.test(id)) id = "_" + id;
+    return id || "scene";
+}
+
+/** Source file extensions that may contain `<needle-engine src="...">` markup. */
+const SOURCE_EXTENSIONS = /\.(html|svelte|tsx|jsx|vue)$/i;
 
 /**
  * Parse `<needle-engine src="...">` from HTML.
@@ -17,7 +73,7 @@ import { join, resolve } from 'path';
  * @returns {string[]}
  */
 function parseSrcAttribute(html) {
-    const re = /<needle-engine[^>]*\ssrc=["']([^"']+)["']/gi;
+    const re = /<needle-engine[\s\S]*?\ssrc=["']([^"']+)["']/gi;
     /** @type {string[]} */
     const out = [];
     let m;
@@ -54,19 +110,26 @@ function parseGenJs(src) {
 /**
  * Resolve a list of (possibly relative) GLB path strings to absolute paths.
  * Remote URLs (http/https) are passed through as-is.
+ * The `key` field preserves the original src value (relative path or URL)
+ * for use as the SceneMap key in the generated .d.ts.
  *
- * @param {string[]} paths
+ * @param {Array<{glbPath: string, sourceFile: string | null}>} pathEntries
  * @param {string} projectRoot
  * @param {string} assetsDir
- * @returns {Array<{path: string, type: "glb"|"gltf", remote?: boolean}>}
+ * @returns {Array<{path: string, type: "glb"|"gltf", remote?: boolean, key: string, sourceFiles: string[]}>}
  */
-function resolveGlbPaths(paths, projectRoot, assetsDir) {
-    /** @type {Array<{path: string, type: "glb"|"gltf", remote?: boolean}>} */
-    const out = [];
-    for (const p of paths) {
+function resolveGlbPaths(pathEntries, projectRoot, assetsDir) {
+    /** @type {Map<string, {path: string, type: "glb"|"gltf", remote?: boolean, key: string, sourceFiles: string[]}>} */
+    const byKey = new Map();
+    for (const { glbPath: p, sourceFile } of pathEntries) {
         if (p.startsWith("http://") || p.startsWith("https://")) {
             const type = p.toLowerCase().endsWith(".gltf") ? "gltf" : "glb";
-            out.push({ path: p, type, remote: true });
+            const existing = byKey.get(p);
+            if (existing) {
+                if (sourceFile) existing.sourceFiles.push(sourceFile);
+            } else {
+                byKey.set(p, { path: p, type, remote: true, key: p, sourceFiles: sourceFile ? [sourceFile] : [] });
+            }
             continue;
         }
         const clean = p.replace(/^\.\//, "").replace(/^\//, "");
@@ -77,52 +140,106 @@ function resolveGlbPaths(paths, projectRoot, assetsDir) {
         for (const candidate of candidates) {
             if (existsSync(candidate)) {
                 const type = candidate.toLowerCase().endsWith(".gltf") ? "gltf" : "glb";
-                out.push({ path: candidate, type });
+                const existing = byKey.get(clean);
+                if (existing) {
+                    if (sourceFile) existing.sourceFiles.push(sourceFile);
+                } else {
+                    byKey.set(clean, { path: candidate, type, key: clean, sourceFiles: sourceFile ? [sourceFile] : [] });
+                }
                 break;
             }
         }
     }
+    return Array.from(byKey.values());
+}
+
+/**
+ * Walk `src/` (or the project root) for source files that may contain
+ * `<needle-engine src="...">` and return GLB path + source file pairs.
+ *
+ * @param {string} projectRoot
+ * @returns {Array<{glbPath: string, sourceFile: string}>}
+ */
+function scanSourceFilesForGlbs(projectRoot) {
+    /** @type {Array<{glbPath: string, sourceFile: string}>} */
+    const out = [];
+    const srcDir = join(projectRoot, "src");
+    const searchRoot = existsSync(srcDir) ? srcDir : projectRoot;
+
+    /** @param {string} dir */
+    function walk(dir) {
+        let entries;
+        try { entries = readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Skip node_modules and hidden dirs
+                if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+                walk(fullPath);
+            } else if (SOURCE_EXTENSIONS.test(entry.name)) {
+                try {
+                    const content = readFileSync(fullPath, "utf8");
+                    const relPath = fullPath.replace(projectRoot + "/", "").replace(projectRoot + "\\", "");
+                    for (const glbPath of parseSrcAttribute(content)) {
+                        out.push({ glbPath, sourceFile: relPath });
+                    }
+                } catch (_e) { /* ignore unreadable files */ }
+            }
+        }
+    }
+
+    walk(searchRoot);
     return out;
 }
 
 /**
  * Resolve the entrypoint GLB file paths for a project.
  *
- * Priority:
- *  1. `<needle-engine src="...">` attribute in `index.html`
+ * Sources (all merged, deduplicated by key):
+ *  1. `<needle-engine src="...">` in `index.html`
  *  2. `needle_exported_files.push("...")` lines in `{codegenDir}/gen.js`
- *  3. Returns `null` — caller should fall back to `collectSceneFiles`.
+ *  3. `<needle-engine src="...">` in any `.svelte`, `.tsx`, `.jsx`, `.vue`, `.html` under `src/`
+ *
+ * Returns `null` if nothing found — caller should fall back to `collectSceneFiles`.
  *
  * @param {string} projectRoot  Absolute path to the project root
  * @param {string} assetsDir    Absolute path to the assets directory
  * @param {string} [codegenDir] Absolute path to the codegen directory
- * @returns {Array<{path: string, type: "glb"|"gltf", remote?: boolean}> | null}
+ * @returns {Array<{path: string, type: "glb"|"gltf", remote?: boolean, key: string, sourceFiles: string[]}> | null}
  */
 export function resolveEntrypointGlbs(projectRoot, assetsDir, codegenDir) {
+    /** @type {Array<{glbPath: string, sourceFile: string | null}>} */
+    const allEntries = [];
+
+    // 1. index.html
     const htmlPath = join(projectRoot, "index.html");
     if (existsSync(htmlPath)) {
         try {
-            const srcPaths = parseSrcAttribute(readFileSync(htmlPath, "utf8"));
-            if (srcPaths.length > 0) {
-                const resolved = resolveGlbPaths(srcPaths, projectRoot, assetsDir);
-                if (resolved.length > 0) return resolved;
+            for (const glbPath of parseSrcAttribute(readFileSync(htmlPath, "utf8"))) {
+                allEntries.push({ glbPath, sourceFile: "index.html" });
             }
         } catch (_e) { /* ignore */ }
     }
 
+    // 2. gen.js
     const genDir = codegenDir ?? join(projectRoot, "src", "generated");
     const genPath = join(genDir, "gen.js");
     if (existsSync(genPath)) {
         try {
-            const genPaths = parseGenJs(readFileSync(genPath, "utf8"));
-            if (genPaths.length > 0) {
-                const resolved = resolveGlbPaths(genPaths, projectRoot, assetsDir);
-                if (resolved.length > 0) return resolved;
+            const relGenPath = genPath.replace(projectRoot + "/", "").replace(projectRoot + "\\", "");
+            for (const glbPath of parseGenJs(readFileSync(genPath, "utf8"))) {
+                allEntries.push({ glbPath, sourceFile: relGenPath });
             }
         } catch (_e) { /* ignore */ }
     }
 
-    return null;
+    // 3. Source files (SvelteKit, React, Vue, etc.)
+    allEntries.push(...scanSourceFilesForGlbs(projectRoot));
+
+    if (allEntries.length === 0) return null;
+
+    const resolved = resolveGlbPaths(allEntries, projectRoot, assetsDir);
+    return resolved.length > 0 ? resolved : null;
 }
 
 /**

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

@@ -29,17 +29,44 @@ export function sanitizeNodeName(rawName, namesUsed) {
 
 /**
  * Infer the Three.js runtime type of a glTF node from its JSON properties.
- * - `mesh` present        → `import("three").Mesh`
- * - `camera` present      → `import("three").Camera`
- * - KHR_lights_punctual   → `import("three").Light`
- * - otherwise             → `import("three").Object3D`
+ * - `mesh` present with skinning  → `import("three").SkinnedMesh`
+ * - `mesh` present                → `import("three").Mesh`
+ * - `camera` present, perspective → `import("three").PerspectiveCamera`
+ * - `camera` present, orthographic→ `import("three").OrthographicCamera`
+ * - KHR_lights_punctual           → `import("three").Light`
+ * - otherwise                     → `import("three").Object3D`
  *
  * @param {Record<string, unknown>} node
+ * @param {Array<Record<string, unknown>>} cameras  Raw glTF cameras array
+ * @param {Array<Record<string, unknown>>} meshes   Raw glTF meshes array
  * @returns {string}
  */
-export function inferNodeThreeType(node) {
-    if ("mesh" in node) return `import("three").Mesh`;
-    if ("camera" in node) return `import("three").Camera`;
+export function inferNodeThreeType(node, cameras, meshes) {
+    if ("mesh" in node) {
+        const hasSkin = "skin" in node;
+        if (!hasSkin) {
+            const meshIdx = /** @type {number} */ (node.mesh);
+            const mesh = meshes[meshIdx];
+            const primitives = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(mesh?.primitives) ? mesh.primitives : []);
+            const isSkinned = primitives.some(p => {
+                const attrs = /** @type {Record<string, unknown>} */ (p?.attributes ?? {});
+                return "WEIGHTS_0" in attrs;
+            });
+            if (isSkinned) return `import("three").SkinnedMesh`;
+        } else {
+            return `import("three").SkinnedMesh`;
+        }
+        return `import("three").Mesh`;
+    }
+    if ("camera" in node) {
+        const camIdx = /** @type {number} */ (node.camera);
+        const cam = cameras[camIdx];
+        if (cam && typeof cam === "object") {
+            if (cam.type === "perspective") return `import("three").PerspectiveCamera`;
+            if (cam.type === "orthographic") return `import("three").OrthographicCamera`;
+        }
+        return `import("three").Camera`;
+    }
     if (node.extensions && /** @type {any} */ (node.extensions)["KHR_lights_punctual"] != null) return `import("three").Light`;
     return `import("three").Object3D`;
 }
@@ -123,6 +150,17 @@ function buildNodePaths(nodes, namesUsed) {
  */
 export function extractComponentBindings(json) {
     const nodes = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(json.nodes) ? json.nodes : []);
+    const cameras = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(json.cameras) ? json.cameras : []);
+    const meshes = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(json.meshes) ? json.meshes : []);
+
+    // Collect scene root node indices — these map to THREE.Scene at runtime
+    const scenes = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(json.scenes) ? json.scenes : []);
+    /** @type {Set<number>} */
+    const sceneRootNodeIndices = new Set();
+    for (const scene of scenes) {
+        const sceneNodes = Array.isArray(scene.nodes) ? /** @type {number[]} */ (scene.nodes) : [];
+        for (const idx of sceneNodes) sceneRootNodeIndices.add(idx);
+    }
     /** @type {Array<{nodeName: string, nodePath: string, componentName: string, fields: Record<string, unknown>, nodeThreeType: string}>} */
     const results = [];
     /** @type {Record<string, number>} */
@@ -138,7 +176,9 @@ export function extractComponentBindings(json) {
         if (!nodeName) continue;
 
         const nodePath = pathMap.get(i) ?? nodeName;
-        const nodeThreeType = inferNodeThreeType(/** @type {Record<string, unknown>} */ (node));
+        const nodeThreeType = sceneRootNodeIndices.has(i)
+            ? `import("three").Scene`
+            : inferNodeThreeType(/** @type {Record<string, unknown>} */ (node), cameras, meshes);
         const ext = node.extensions?.[NEEDLE_COMPONENTS_EXTENSION];
 
         if (!ext || typeof ext !== "object") {

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

@@ -7,9 +7,9 @@
  */
 
 import { openSync, readSync, closeSync, readFileSync } from 'fs';
+import { needleLog } from '../vite/logging.js';
 
-/** @type {Map<string, { lastModified: string, json: Record<string, unknown> }>} */
-const _remoteGlbCache = new Map();
+const PLUGIN = "needle:dts-generator";
 
 /**
  * Read the JSON chunk from a binary GLB file without loading the binary blob.
@@ -56,12 +56,39 @@ export function readGltfJsonFile(filePath) {
 }
 
 /**
- * Fetch only the JSON chunk of a remote GLB using two HTTP Range requests.
+ * 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.
- * Returns `null` on any network/parse error or if Range is not supported.
+ * Also captures `Content-Disposition` filename for friendly key generation.
+ * Returns `null` on any network or parse error.
  *
  * @param {string} url
- * @returns {Promise<Record<string, unknown> | null>}
+ * @returns {Promise<{ json: Record<string, unknown>, filename: string | null } | null>}
  */
 export async function readRemoteGlbJsonChunk(url) {
     try {
@@ -69,46 +96,72 @@ export async function readRemoteGlbJsonChunk(url) {
 
         const headerRes = await fetch(url, { headers: { Range: "bytes=0-19" } });
         if (!headerRes.ok) {
-            console.warn(`[needle:dts-generator] Remote GLB fetch failed (${headerRes.status}): ${url}`);
+            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) {
-            return cached.json;
+            // 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 rangeSupported = headerRes.status === 206;
-        const headerBytes = Buffer.from(await headerRes.arrayBuffer());
-        if (headerBytes.length < 20) return null;
+        const firstBytes = Buffer.from(await headerRes.arrayBuffer());
+        if (firstBytes.length < 20) return null;
 
-        const magic = headerBytes.readUInt32LE(0);
-        const version = headerBytes.readUInt32LE(4);
-        const chunkLength = headerBytes.readUInt32LE(12);
-        const chunkType = headerBytes.readUInt32LE(16);
+        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
 
-        if (!rangeSupported) {
-            console.warn(`[needle:dts-generator] Remote GLB server does not support Range requests, skipping: ${url}`);
-            return null;
+        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;
         }
 
-        const jsonEnd = 20 + chunkLength - 1;
-        const jsonRes = await fetch(url, { headers: { Range: `bytes=20-${jsonEnd}` } });
-        if (!jsonRes.ok) {
-            console.warn(`[needle:dts-generator] Remote GLB JSON chunk fetch failed (${jsonRes.status}): ${url}`);
-            return null;
+        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(Buffer.from(await jsonRes.arrayBuffer()).toString("utf8").replace(/\u0000+$/g, ""))
+            JSON.parse(jsonBytes.toString("utf8").replace(/\u0000+$/g, ""))
         );
-        _remoteGlbCache.set(url, { lastModified, json });
-        return json;
+        _remoteGlbCache.set(url, { lastModified, json, filename: resolvedFilename });
+        return { json, filename: resolvedFilename };
     } catch (e) {
-        console.warn(`[needle:dts-generator] Failed to fetch remote GLB: ${url} —`, /** @type {any} */ (e)?.message ?? e);
+        needleLog(PLUGIN, `Failed to fetch remote GLB: ${url} — ${/** @type {any} */ (e)?.message ?? e}`, "warn");
         return null;
     }
 }

package/plugins/dts-generator/index.js

@@ -8,7 +8,7 @@
  *
  * Typical generated output:
  *
- *   declare module "needle:bindings" {
+ *   declare module "needle-bindings" {
  *     interface SceneData {
  *       Sphere: {
  *         MyBall: { speed: number; label: string; };

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

@@ -1,19 +1,30 @@
 /**
- * Ambient module declaration for `needle:bindings`.
+ * Ambient module declaration for `needle-bindings`.
  *
- * The `SceneData` interface is empty by default.
- * When the `needle:dts-generator` Vite plugin is active it writes
- * `src/generated/needle-bindings.d.ts` into the user's project, which
- * augments this interface with the actual component bindings extracted
- * from the project's GLB files at build time.
+ * `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
  *
- * @example
- * import type { SceneData } from "@needle-tools/engine";
- * type MyBallData = SceneData["RedBall"]["MyBall"];
+ * 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.
  */
-declare module "needle:bindings" {
-    interface SceneData {
-        /** Fallback for nodes not present in the generated bindings — no type info, but no crash. */
-        [nodeName: string]: Record<string, unknown> | undefined;
-    }
+
+// 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

@@ -82,7 +82,10 @@ export type userSettings = {
         */
         version?: string;
 
-        /** If defined the access token will be used to run compression on Needle Cloud */
+        /** If defined the access token will be used to run compression on Needle Cloud.
+         *
+         * Expected to be a Needle Cloud access token (created in the Needle Cloud UI),
+         * NOT a JWT. Do not pass a licensing JWT here. */
         accessToken?: string | undefined;
 
         /**
@@ -176,4 +179,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: {