@needle-tools/engine 5.1.0-canary.fbdfce3 → 5.1.0-experimental.03e8105

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

@@ -1,279 +0,0 @@
-// @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

@@ -1,215 +0,0 @@
-// @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

@@ -1,167 +0,0 @@
-// @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;
-    }
-}