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

package/plugins/dts-generator/dts.scan.js

@@ -0,0 +1,99 @@
+// @ts-check
+/**
+ * Scans GLB/glTF files and returns structured binding data.
+ *
+ * Combines file discovery, JSON reading, component extraction, and manifest
+ * type resolution into the `BindingEntry[]` array consumed by codegen.
+ */
+
+import { resolveEntrypointGlbs, collectSceneFiles, glbFriendlyName } from './glb.discovery.js';
+import { readGlbJsonChunk, readGltfJsonFile, readRemoteGlbJsonChunk } from './glb.reader.js';
+import { extractComponentBindings, inferTsType } from './glb.extractor.js';
+import { componentsManifest } from './manifest.types.js';
+import { needleLog } from '../vite/logging.js';
+
+const PLUGIN = "needle:dts-generator";
+
+/**
+ * @typedef {Object} BindingEntry
+ * @property {string} nodeName
+ * @property {string} nodePath  Full hierarchy path e.g. "Scene/Cube/Child_Of_Cube"
+ * @property {string} componentName
+ * @property {Record<string, string>} fieldTypes  field name → TS type string
+ * @property {boolean} isEngineComponent  true if the component exists in components.needle.json
+ * @property {string} nodeThreeType  Three.js type of the parent node (e.g. `import("three").Mesh`)
+ * @property {string} glbKey  Friendly identifier derived from the GLB name (e.g. "myScene", "MaterialXNodes")
+ * @property {string} glbSrc  Project-relative path or URL of the GLB file
+ * @property {string[]} [glbSourceFiles]  Source files (relative to project root) that reference this GLB
+ */
+
+/**
+ * Scan GLB/glTF files and return structured binding data.
+ * Uses entrypoint GLBs (from index.html, gen.js, or source files) when available,
+ * otherwise falls back to scanning all GLBs in assetsDir.
+ *
+ * @param {string} assetsDir   Absolute path to the assets directory
+ * @param {string} [projectRoot]  Absolute path to the project root (enables entrypoint detection)
+ * @param {string} [codegenDir]   Absolute path to the codegen directory
+ * @returns {Promise<BindingEntry[]>}
+ */
+export async function scanBindings(assetsDir, projectRoot, codegenDir) {
+    /** @type {Array<{path: string, type: "glb"|"gltf", remote?: boolean, key?: string}>} */
+    const files = /** @type {any} */ ((projectRoot ? resolveEntrypointGlbs(projectRoot, assetsDir, codegenDir) : null)
+        ?? collectSceneFiles(assetsDir));
+
+    needleLog(PLUGIN, `Discovered ${files.length} GLB(s):\n${files.map(f => `  ${f.path}`).join("\n")}`);
+
+    /** @type {BindingEntry[]} */
+    const entries = [];
+
+    for (const file of files) {
+        let json = /** @type {Record<string, unknown> | null} */ (null);
+        let contentDispositionFilename = /** @type {string | null} */ (null);
+
+        if (file.remote) {
+            needleLog(PLUGIN, `Fetching remote GLB: ${file.path}`);
+            const result = await readRemoteGlbJsonChunk(file.path);
+            if (!result) { needleLog(PLUGIN, `Skipped (fetch failed): ${file.path}`, "warn"); continue; }
+            json = result.json;
+            contentDispositionFilename = result.filename;
+            needleLog(PLUGIN, `Remote GLB ok — Content-Disposition: ${contentDispositionFilename ?? "(none)"}`);
+        } else {
+            json = file.type === "glb" ? readGlbJsonChunk(file.path) : readGltfJsonFile(file.path);
+        }
+        if (!json) continue;
+
+        // Derive a friendly identifier for this GLB (used as SceneData key).
+        // For local files: basename without extension.
+        // For remote: Content-Disposition filename > last non-generic URL segment.
+        const localPathForName = file.remote ? file.path : (
+            projectRoot
+                ? file.path.replace(projectRoot + "/", "").replace(projectRoot + "\\", "")
+                : file.path
+        );
+        const glbKey = glbFriendlyName(localPathForName, contentDispositionFilename);
+
+        for (const { nodeName, nodePath, componentName, fields, nodeThreeType } of extractComponentBindings(json)) {
+            /** @type {Record<string, string>} */
+            const fieldTypes = {};
+            if (componentName) {
+                const manifestFields = componentsManifest.get(componentName);
+                if (manifestFields) {
+                    for (const [k, tsType] of manifestFields) {
+                        fieldTypes[k] = tsType;
+                    }
+                } else {
+                    for (const [k, v] of Object.entries(fields)) {
+                        fieldTypes[k] = inferTsType(v);
+                    }
+                }
+            }
+            const isEngineComponent = componentName ? componentsManifest.has(componentName) : false;
+            const glbSrc = file.remote ? file.path : localPathForName;
+            const glbSourceFiles = /** @type {string[] | undefined} */ (/** @type {any} */ (file).sourceFiles);
+            entries.push({ nodeName, nodePath, componentName, fieldTypes, isEngineComponent, nodeThreeType, glbKey, glbSrc, glbSourceFiles });
+        }
+    }
+
+    return entries;
+}

package/plugins/dts-generator/dts.writer.js

@@ -0,0 +1,59 @@
+// @ts-check
+/**
+ * File writer — the only module that performs I/O writes.
+ *
+ * Orchestrates scanning, codegen, and writes the output files.
+ * Returns false if content was already up-to-date (no write performed).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { scanBindings } from './dts.scan.js';
+import { generateDts, generateHtmlCustomData } from './dts.codegen.js';
+
+/**
+ * Scan assets and write `needle-bindings.d.ts` and `needle-html-data.json`
+ * to the output directory.
+ * Returns the number of bindings written, or `false` if content was already up-to-date.
+ *
+ * @param {object} opts
+ * @param {string} opts.assetsDir      Absolute path to assets directory
+ * @param {string} opts.outputPath     Absolute path to write needle-bindings.d.ts
+ * @param {string} [opts.projectRoot]  Project root — enables entrypoint GLB detection
+ * @param {string} [opts.codegenDir]   Codegen directory — used to find gen.js and write needle-html-data.json (no binding copy written here)
+ * @returns {Promise<number | false>}
+ */
+export async function generateBindingsDts({ assetsDir, outputPath, projectRoot, codegenDir }) {
+    const entries = await scanBindings(assetsDir, projectRoot, codegenDir);
+    const content = generateDts(entries);
+    const htmlContent = generateHtmlCustomData(entries);
+
+    mkdirSync(dirname(outputPath), { recursive: true });
+
+    let dtsChanged = false;
+    try {
+        const existing = existsSync(outputPath) ? readFileSync(outputPath, "utf8") : "";
+        if (existing !== content) {
+            writeFileSync(outputPath, content, "utf8");
+            dtsChanged = true;
+        }
+    } catch (_e) {
+        writeFileSync(outputPath, content, "utf8");
+        dtsChanged = true;
+    }
+
+    const htmlDataPath = join(dirname(outputPath), "needle-html-data.json");
+    try {
+        const existingHtml = existsSync(htmlDataPath) ? readFileSync(htmlDataPath, "utf8") : "";
+        if (existingHtml !== htmlContent) {
+            writeFileSync(htmlDataPath, htmlContent, "utf8");
+        }
+    } catch (_e) {
+        writeFileSync(htmlDataPath, htmlContent, "utf8");
+    }
+
+    if (!dtsChanged) return false;
+    const nodeCount = new Set(entries.map(e => e.nodeName)).size;
+    const bindingCount = new Set(entries.filter(e => e.componentName).map(e => `${e.nodeName}/${e.componentName}`)).size;
+    return bindingCount > 0 ? bindingCount : nodeCount;
+}

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