@needle-tools/engine 5.1.0-experimental.03e8105 → 5.1.0-experimental.08fa2ef

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

@@ -0,0 +1,279 @@
+// @ts-check
+/**
+ * GLB / glTF file discovery.
+ *
+ * Resolves which scene files to process — either from the project's entrypoints
+ * (index.html `<needle-engine src>` or gen.js push calls) or by recursively
+ * walking the assets directory.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+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.
+ * Handles both single strings and JSON arrays.
+ * @param {string} html
+ * @returns {string[]}
+ */
+function parseSrcAttribute(html) {
+    const re = /<needle-engine[\s\S]*?\ssrc=["']([^"']+)["']/gi;
+    /** @type {string[]} */
+    const out = [];
+    let m;
+    while ((m = re.exec(html)) !== null) {
+        const val = m[1].trim();
+        if (val.startsWith("[")) {
+            try {
+                const arr = JSON.parse(val);
+                if (Array.isArray(arr)) out.push(...arr.filter(v => typeof v === "string"));
+            } catch (_e) { /* malformed JSON, skip */ }
+        } else {
+            out.push(val);
+        }
+    }
+    return out;
+}
+
+/**
+ * Parse `needle_exported_files.push("path/to/file.glb")` lines from gen.js.
+ * @param {string} src
+ * @returns {string[]}
+ */
+function parseGenJs(src) {
+    const re = /needle_exported_files\.push\(["']([^"']+\.(?:glb|gltf))["']\)/gi;
+    /** @type {string[]} */
+    const out = [];
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        out.push(m[1]);
+    }
+    return out;
+}
+
+/**
+ * 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 {Array<{glbPath: string, sourceFile: string | null}>} pathEntries
+ * @param {string} projectRoot
+ * @param {string} assetsDir
+ * @returns {Array<{path: string, type: "glb"|"gltf", remote?: boolean, key: string, sourceFiles: string[]}>}
+ */
+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";
+            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(/^\//, "");
+        const candidates = [
+            join(projectRoot, clean),
+            join(assetsDir, clean.replace(/^assets\//, "")),
+        ];
+        for (const candidate of candidates) {
+            if (existsSync(candidate)) {
+                const type = candidate.toLowerCase().endsWith(".gltf") ? "gltf" : "glb";
+                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.
+ *
+ * Sources (all merged, deduplicated by key):
+ *  1. `<needle-engine src="...">` in `index.html`
+ *  2. `needle_exported_files.push("...")` lines in `{codegenDir}/gen.js`
+ *  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, 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 {
+            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 relGenPath = genPath.replace(projectRoot + "/", "").replace(projectRoot + "\\", "");
+            for (const glbPath of parseGenJs(readFileSync(genPath, "utf8"))) {
+                allEntries.push({ glbPath, sourceFile: relGenPath });
+            }
+        } catch (_e) { /* ignore */ }
+    }
+
+    // 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;
+}
+
+/**
+ * Recursively collect all scene GLB/glTF files in a directory.
+ * Skips LOD and image sub-glbs that aren't scene roots.
+ *
+ * @param {string} assetsDir
+ * @returns {Array<{path: string, type: "glb"|"gltf"}>}
+ */
+export function collectSceneFiles(assetsDir) {
+    if (!existsSync(assetsDir)) return [];
+
+    /** @type {Array<{path: string, type: "glb"|"gltf"}>} */
+    const out = [];
+
+    /** @param {string} dir */
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            if (/^image_\d+_.*\.glb$/i.test(entry.name)) continue;
+            if (/^mesh_lod_\d+_.*\.glb$/i.test(entry.name)) continue;
+
+            if (/\.glb$/i.test(entry.name)) {
+                out.push({ path: fullPath, type: "glb" });
+            } else if (/\.gltf$/i.test(entry.name)) {
+                out.push({ path: fullPath, type: "gltf" });
+            }
+        }
+    }
+
+    walk(assetsDir);
+    return out;
+}

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

@@ -0,0 +1,215 @@
+// @ts-check
+/**
+ * glTF node tree walker and NEEDLE_components extractor.
+ *
+ * Walks the parsed glTF JSON, sanitizes node names to match Three.js runtime
+ * behaviour, and extracts component data from the NEEDLE_components extension.
+ */
+
+const NEEDLE_COMPONENTS_EXTENSION = "NEEDLE_components";
+
+/**
+ * Replicate Three.js GLTFLoader's sanitizeNodeName + createUniqueName logic.
+ * - Whitespace → `_`
+ * - Reserved chars `[ ] . : /` → removed
+ * - Duplicate names get `_1`, `_2`, … suffix
+ *
+ * @param {string} rawName
+ * @param {Record<string, number>} namesUsed  Mutated in-place — pass the same object for all nodes in a GLB
+ * @returns {string}
+ */
+export function sanitizeNodeName(rawName, namesUsed) {
+    const sanitized = rawName.replace(/\s/g, "_").replace(/[\[\].:\/]/g, "");
+    if (sanitized in namesUsed) {
+        return sanitized + "_" + (++namesUsed[sanitized]);
+    }
+    namesUsed[sanitized] = 0;
+    return sanitized;
+}
+
+/**
+ * Infer the Three.js runtime type of a glTF node from its JSON properties.
+ * - `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, 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`;
+}
+
+/**
+ * Infer a TypeScript type string from a raw JSON value.
+ * Only primitives are typed precisely; everything else → `unknown`.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function inferTsType(value) {
+    if (value === null || value === undefined) return "unknown";
+    switch (typeof value) {
+        case "number": return "number";
+        case "string": return "string";
+        case "boolean": return "boolean";
+        default: return "unknown";
+    }
+}
+
+/**
+ * Build a map of nodeIndex → sanitized name and nodeIndex → parent index
+ * from the glTF node tree, then compute the full path for each node.
+ *
+ * @param {Array<Record<string, unknown>>} nodes  Raw glTF nodes array
+ * @param {Record<string, number>} namesUsed  Already-used name registry (shared with extraction pass)
+ * @returns {{ nameMap: Map<number, string>, pathMap: Map<number, string> }}
+ */
+function buildNodePaths(nodes, namesUsed) {
+    /** @type {Map<number, string>} nodeIndex → sanitized name */
+    const nameMap = new Map();
+    /** @type {Map<number, number>} nodeIndex → parent nodeIndex */
+    const parentMap = new Map();
+
+    // First pass: sanitize all names
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (!node || typeof node !== "object") continue;
+        const rawName = typeof node.name === "string" ? node.name : "";
+        if (!rawName) continue;
+        nameMap.set(i, sanitizeNodeName(rawName, namesUsed));
+    }
+
+    // Second pass: build parent map from children arrays
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (!node || typeof node !== "object") continue;
+        const children = Array.isArray(node.children) ? node.children : [];
+        for (const childIdx of children) {
+            parentMap.set(childIdx, i);
+        }
+    }
+
+    // Third pass: compute full path per node by walking up the parent chain
+    /** @type {Map<number, string>} nodeIndex → full path string */
+    const pathMap = new Map();
+    for (const [idx] of nameMap) {
+        const parts = [];
+        /** @type {number | undefined} */
+        let cur = idx;
+        while (cur !== undefined && nameMap.has(cur)) {
+            parts.unshift(/** @type {string} */ (nameMap.get(cur)));
+            cur = parentMap.get(cur);
+        }
+        pathMap.set(idx, parts.join("/"));
+    }
+
+    return { nameMap, pathMap };
+}
+
+/**
+ * Walk the glTF JSON and collect every node name + any NEEDLE_components extension blocks.
+ * Node names are sanitized and de-duplicated to match Three.js GLTFLoader behaviour.
+ *
+ * Nodes without NEEDLE_components are returned with an empty componentName so that
+ * callers can decide whether to emit them.
+ *
+ * @param {Record<string, unknown>} json  Parsed glTF JSON
+ * @returns {Array<{nodeName: string, nodePath: string, componentName: string, fields: Record<string, unknown>, nodeThreeType: string}>}
+ */
+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>} */
+    const namesUsed = {};
+
+    const { nameMap, pathMap } = buildNodePaths(nodes, namesUsed);
+
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (!node || typeof node !== "object") continue;
+
+        const nodeName = nameMap.get(i);
+        if (!nodeName) continue;
+
+        const nodePath = pathMap.get(i) ?? nodeName;
+        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") {
+            results.push({ nodeName, nodePath, componentName: "", fields: {}, nodeThreeType });
+            continue;
+        }
+
+        const lists = [
+            ...(Array.isArray(ext.components) ? ext.components : []),
+            ...(Array.isArray(ext.builtin_components) ? ext.builtin_components : []),
+        ];
+
+        const internalKeys = new Set([
+            "name", "type", "guid", "gameObject", "enabled",
+            "didAwake", "didStart", "transformHandle", "destroyCancellationToken",
+        ]);
+
+        for (const comp of lists) {
+            if (!comp || typeof comp !== "object") continue;
+            const componentName = typeof comp.name === "string" ? comp.name.trim() : "";
+            if (!componentName) continue;
+
+            /** @type {Record<string, unknown>} */
+            const fields = {};
+            for (const [k, v] of Object.entries(comp)) {
+                if (!internalKeys.has(k)) fields[k] = v;
+            }
+
+            results.push({ nodeName, nodePath, componentName, fields, nodeThreeType });
+        }
+    }
+
+    return results;
+}

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;
+    }
+}