@needle-tools/engine 5.1.0-alpha → 5.1.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "5.1.0-alpha",
+  "version": "5.1.0-alpha.2",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {
@@ -68,6 +68,7 @@
     "build:plugin-types": "tsc -p tsconfig.plugins.json && cp .plugin-types-tmp/plugins/vite/*.d.ts plugins/vite/ && cp .plugin-types-tmp/plugins/next/*.d.ts plugins/next/ && rm -rf .plugin-types-tmp",
     "build:components-data": "node plugins/publish/create-component-types.now.mjs",
     "test": "node plugins/test/test.mjs",
+    "test:vitest": "vitest run",
     "test:playwright:setup": "cd tests/playwright && npm install --prefer-offline && npx playwright install --with-deps chromium",
     "test:playwright": "npm run test:playwright:setup && npx playwright test",
     "test:playwright:fast": "npm run test:playwright:setup && npx playwright test --grep @fast",
@@ -94,6 +95,7 @@
     "lib",
     "dist",
     "plugins",
+    ".needle",
     "components.needle.json",
     "custom-elements.json"
   ],
@@ -122,12 +124,11 @@
   ],
   "dependencies": {
     "@dimforge/rapier3d-compat": "0.19.3",
-    "@needle-tools/gltf-progressive": "3.4.0-beta.3",
+    "@needle-tools/gltf-progressive": "3.5.0-rc",
     "@needle-tools/materialx": "1.6.0",
     "@needle-tools/three-animation-pointer": "1.0.7",
     "@webxr-input-profiles/motion-controllers": "1.0.0",
     "flatbuffers": "2.0.4",
-    "md5": "2.3.0",
     "n8ao": "1.10.1",
     "peerjs": "1.4.7",
     "postprocessing": "6.39.0",
@@ -173,7 +174,8 @@
     "typescript": "5.9.3",
     "typescript-eslint": "^8.0.0",
     "vite": "7",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.4"
   },
   "peerDependencies": {
     "open": "^10.1.0"

package/plugins/common/logger.js

@@ -1,7 +1,13 @@
 // @ts-check
-import { createWriteStream, existsSync, mkdirSync, readdirSync, rmSync, statSync, write } from "fs";
+import { createWriteStream, existsSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, lstatSync, write } from "fs";
 
-const filename_timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+/** Formats a Date as a local-time filename-safe string: YYYY-MM-DD_HH-MM-SS */
+function formatLocalTimestamp(date) {
+    const pad = (/** @type {number} */ n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}_${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+
+const filename_timestamp = formatLocalTimestamp(new Date());
 const debug = false;
 
 // #region public api
@@ -352,8 +358,8 @@ function stringifyLog(log, seen = /** @type {Set<unknown>} */ (new Set()), depth
     const isServer = typeof window === "undefined";
     const stringify_limits = {
         string: isServer ? 100_000 : 1_000,
-        object_keys: isServer ? 300 : 200,
-        object_depth: isServer ? 10 : 3,
+        object_keys: isServer ? 10 : 10,
+        object_depth: isServer ? 3 : 3,
         array_items: isServer ? 2_000 : 100,
     }
 
@@ -535,21 +541,27 @@ function stripAnsiColors(str) {
 /** @type {Map<string, import("fs").WriteStream>} */
 const filestreams = new Map();
 const fileLogDirectory = "node_modules/.needle/logs";
-// cleanup old log files
-if (existsSync(fileLogDirectory)) {
-    const files = readdirSync(fileLogDirectory);
-    // sort by age and keep the last 10 files
-    files.sort((a, b) => {
-        const aStat = statSync(`${fileLogDirectory}/${a}`);
-        const bStat = statSync(`${fileLogDirectory}/${b}`);
-        return aStat.mtimeMs - bStat.mtimeMs;
-    });
-    // remove all but the last 30 files
-    const filesToKeep = 30;
-    for (let i = 0; i < files.length - filesToKeep; i++) {
-        rmSync(`${fileLogDirectory}/${files[i]}`, { force: true });
+// cleanup old log files (skip symlinks like latest.*.needle.log)
+try {
+    if (existsSync(fileLogDirectory)) {
+        const files = readdirSync(fileLogDirectory).filter(f => {
+            try { return !lstatSync(`${fileLogDirectory}/${f}`).isSymbolicLink(); }
+            catch { return false; }
+        });
+        // sort by age and keep the last 30 files
+        files.sort((a, b) => {
+            try {
+                const aStat = statSync(`${fileLogDirectory}/${a}`);
+                const bStat = statSync(`${fileLogDirectory}/${b}`);
+                return aStat.mtimeMs - bStat.mtimeMs;
+            } catch { return 0; }
+        });
+        const filesToKeep = 30;
+        for (let i = 0; i < files.length - filesToKeep; i++) {
+            rmSync(`${fileLogDirectory}/${files[i]}`, { force: true });
+        }
     }
-}
+} catch { /* don't let cleanup errors prevent logging from working */ }
 
 /**
  * Appends a single log entry to the per-process rotating file log.
@@ -566,7 +578,18 @@ function writeToFile(process, log, _connectionId) {
         if (!existsSync(fileLogDirectory)) {
             mkdirSync(fileLogDirectory, { recursive: true });
         }
-        filestreams.set(filename, createWriteStream(`${fileLogDirectory}/${filename_timestamp}.${filename}`, { flags: 'a' }));
+        const timestampedName = `${filename_timestamp}.${filename}`;
+        filestreams.set(filename, createWriteStream(`${fileLogDirectory}/${timestampedName}`, { flags: 'a' }));
+
+        // Create/update "latest" symlink pointing to the current log file
+        const symlinkName = `latest.${filename}`;
+        const symlinkPath = `${fileLogDirectory}/${symlinkName}`;
+        try {
+            if (lstatSync(symlinkPath).isSymbolicLink()) unlinkSync(symlinkPath);
+        } catch { /* doesn't exist yet */ }
+        try {
+            symlinkSync(timestampedName, symlinkPath);
+        } catch { /* symlink creation failed (e.g. Windows without dev mode) */ }
     }
     const writeStream = filestreams.get(filename);
     if (!writeStream) {

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

@@ -0,0 +1,334 @@
+// @ts-check
+/**
+ * Pure string generators — no I/O.
+ *
+ * Takes `BindingEntry[]` from dts.scan.js and produces:
+ *   - `needle-bindings.gen.d.ts`  (TypeScript ambient module augmentation)
+ *   - `needle-html-data.json` (VS Code HTML custom data for data-bind-needle completions)
+ *
+ * Each scene node is emitted as a named type alias so VS Code hover shows
+ * the alias name + JSDoc summary rather than expanding the full object type:
+ *
+ *   /** `Minimal/Cube` — MeshRenderer, BoxCollider *\/
+ *   type $Minimal__Cube = { $object: THREE.Mesh; $components: { ... }; };
+ *
+ *   interface SceneData {
+ *     Minimal: { Minimal: { Cube: $Minimal__Minimal__Cube; }; }; };
+ *   }
+ */
+
+/** @typedef {import('./dts.scan.js').BindingEntry} BindingEntry */
+
+/** Append `?view` to Needle Cloud asset URLs so the link opens the viewer. @param {string} url @returns {string} */
+function addViewParam(url) {
+    if (!url.includes("cloud.needle.tools")) return url;
+    return url.includes("?") ? `${url}&view` : `${url}?view`;
+}
+
+/** @param {string} name @returns {string} */
+function propKey(name) {
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+}
+
+/**
+ * Convert a node path like "Minimal/Cube_1/Child Of Cube" to a safe type alias name.
+ * @param {string} nodePath
+ * @returns {string}
+ */
+function typeAliasName(nodePath) {
+    const safe = nodePath.replace(/[^a-zA-Z0-9]/g, "_");
+    return `$${safe}`;
+}
+
+/**
+ * @typedef {{
+ *   threeType: string,
+ *   components: Map<string, { isEngineComponent: boolean, fields: Map<string, Set<string>> }>,
+ *   children: Map<string, TreeNode>
+ * }} TreeNode
+ */
+
+/** @returns {TreeNode} */
+function makeNode() {
+    return { threeType: `import("three").Object3D`, components: new Map(), children: new Map() };
+}
+
+/**
+ * Build a tree from BindingEntry[]. Each entry's nodePath (e.g. "UI/Camera/Target")
+ * defines where in the tree the node lives.
+ *
+ * @param {BindingEntry[]} entries
+ * @returns {Map<string, TreeNode>}  Root-level nodes
+ */
+function buildTree(entries) {
+    /** @type {Map<string, TreeNode>} */
+    const roots = new Map();
+
+    for (const { nodePath, componentName, fieldTypes, isEngineComponent, nodeThreeType } of entries) {
+        const parts = nodePath.split("/").filter(Boolean);
+        if (parts.length === 0) continue;
+
+        let map = roots;
+        /** @type {TreeNode | null} */
+        let node = null;
+        for (const part of parts) {
+            if (!map.has(part)) map.set(part, makeNode());
+            node = /** @type {TreeNode} */ (map.get(part));
+            map = node.children;
+        }
+        if (!node) continue;
+
+        node.threeType = nodeThreeType;
+
+        if (componentName) {
+            if (!node.components.has(componentName)) {
+                node.components.set(componentName, { isEngineComponent, fields: new Map() });
+            }
+            const comp = /** @type {{ isEngineComponent: boolean, fields: Map<string, Set<string>> }} */ (node.components.get(componentName));
+            for (const [field, tsType] of Object.entries(fieldTypes)) {
+                if (!comp.fields.has(field)) comp.fields.set(field, new Set());
+                /** @type {Set<string>} */ (comp.fields.get(field)).add(tsType);
+            }
+        }
+    }
+
+    return roots;
+}
+
+/**
+ * Compute the human-readable summary for a node (component names or Three.js type).
+ * @param {TreeNode} node
+ * @returns {string}
+ */
+function nodeSummary(node) {
+    const threeShortType = node.threeType.replace(/import\("three"\)\./g, "THREE.");
+    const compNames = Array.from(node.components.keys()).filter(n => n !== "").sort();
+    return compNames.length > 0 ? compNames.join(", ") : threeShortType;
+}
+
+/**
+ * Recursively collect type alias declarations for all nodes in the tree.
+ * Emits one `type $Alias = { ... }` per node, with JSDoc summary.
+ *
+ * @param {string} _key
+ * @param {TreeNode} node
+ * @param {string} nodePath  Full path e.g. "Minimal/Cube"
+ * @param {string[]} aliases  Accumulator — lines pushed in bottom-up order
+ */
+function collectTypeAliases(_key, node, nodePath, aliases) {
+    // Recurse into children first (bottom-up so aliases are defined before use)
+    for (const [childKey, childNode] of Array.from(node.children.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+        collectTypeAliases(childKey, childNode, `${nodePath}/${childKey}`, aliases);
+    }
+
+    const threeShortType = node.threeType.replace(/import\("three"\)\./g, "THREE.");
+    const compEntries = Array.from(node.components.entries())
+        .filter(([n]) => n !== "")
+        .sort(([a], [b]) => a.localeCompare(b));
+    const summary = nodeSummary(node);
+
+    const alias = typeAliasName(nodePath);
+
+    // Emit as an interface so each child property can carry JSDoc
+    const lines = [];
+    lines.push(`/** \`${nodePath}\` — ${summary} */`);
+    lines.push(`interface ${alias} {`);
+    lines.push(`  $object: ${threeShortType};`);
+
+    if (compEntries.length > 0) {
+        const compParts = compEntries.map(([compName, { isEngineComponent, fields }]) => {
+            if (isEngineComponent) {
+                return `${propKey(compName)}: NE.${compName}`;
+            } else {
+                const fieldParts = [`enabled: boolean`];
+                for (const [field, types] of Array.from(fields.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+                    fieldParts.push(`${field}: ${Array.from(types).join(" | ")}`);
+                }
+                return `${propKey(compName)}: { ${fieldParts.join("; ")} }`;
+            }
+        });
+        lines.push(`  /** Needle Engine components on this node. Access via \`getComponent()\`, \`addComponent()\`, or \`findObjectOfType()\` / \`findObjectsOfType()\`. */`);
+        lines.push(`  $components: { ${compParts.join("; ")} };`);
+    }
+
+    for (const [childKey, childNode] of Array.from(node.children.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+        const childAlias = typeAliasName(`${nodePath}/${childKey}`);
+        const childSummary = nodeSummary(childNode);
+        lines.push(`  /** ${childSummary} */`);
+        lines.push(`  ${propKey(childKey)}: ${childAlias};`);
+    }
+
+    lines.push(`}`);
+
+    aliases.push(lines.join("\n"));
+}
+
+/**
+ * Recursively render a tree node as indented JSDoc lines.
+ * @param {string} key
+ * @param {TreeNode} node
+ * @param {number} depth
+ * @param {string[]} lines
+ */
+/** @param {string} threeType @returns {string} */
+function nodeEmoji(threeType) {
+    if (threeType.includes("Scene")) return "🎬";
+    if (threeType.includes("SkinnedMesh")) return "🦴";
+    if (threeType.includes("Mesh")) return "⊞";
+    if (threeType.includes("PerspectiveCamera") || threeType.includes("OrthographicCamera") || threeType.includes("Camera")) return "👁";
+    if (threeType.includes("Light")) return "💡";
+    return "";
+}
+
+function buildTreeDoc(key, node, depth, lines) {
+    const indent = "  ".repeat(depth);
+    const hasComponents = Array.from(node.components.keys()).some(n => n !== "");
+    const summary = nodeSummary(node);
+    const emoji = nodeEmoji(node.threeType);
+    const prefix = emoji ? `${emoji} ` : "";
+    // Bold + components for nodes that have something actionable; plain name for empty containers
+    const label = hasComponents ? `${prefix}**${key}** — ${summary}` : `${prefix}${key}`;
+    lines.push(` * ${indent}- ${label}`);
+    for (const [childKey, childNode] of Array.from(node.children.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+        buildTreeDoc(childKey, childNode, depth + 1, lines);
+    }
+}
+
+/**
+ * Generate the `needle-bindings.gen.d.ts` content from binding entries.
+ *
+ * @param {BindingEntry[]} entries
+ * @returns {string}
+ */
+export function generateDts(entries) {
+    /** @type {Map<string, BindingEntry[]>} */
+    const byGlb = new Map();
+    /** @type {Map<string, string>} glbKey → source path/URL */
+    const glbSrcMap = new Map();
+    /** @type {Map<string, Set<string>>} glbKey → set of source files referencing it */
+    const glbSourceFilesMap = new Map();
+    for (const entry of entries) {
+        const k = entry.glbKey;
+        if (!byGlb.has(k)) byGlb.set(k, []);
+        /** @type {BindingEntry[]} */ (byGlb.get(k)).push(entry);
+        if (entry.glbSrc && !glbSrcMap.has(k)) glbSrcMap.set(k, entry.glbSrc);
+        if (entry.glbSourceFiles?.length) {
+            if (!glbSourceFilesMap.has(k)) glbSourceFilesMap.set(k, new Set());
+            for (const sf of entry.glbSourceFiles) /** @type {Set<string>} */ (glbSourceFilesMap.get(k)).add(sf);
+        }
+    }
+
+    const header = [
+        `// Auto-generated by @needle-tools/engine — do not edit`,
+        `// Regenerated on each vite dev-server start and GLB change.`,
+        `// Augments the base "needle-bindings" declaration in @needle-tools/engine.`,
+        `import type * as NE from "../../lib/needle-engine.js";`,
+        `import type * as THREE from "three";`,
+    ];
+
+    /** @type {string[]} */
+    const aliases = [];
+    /** @type {string[]} */
+    const interfaceLines = [
+        `declare module "needle-bindings" {`,
+        `  interface SceneData {`,
+    ];
+
+    for (const [glbKey, glbEntries] of Array.from(byGlb.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+        const roots = buildTree(glbEntries);
+        if (roots.size === 0) continue;
+
+        // Collect type aliases for all nodes in this GLB
+        for (const [rootKey, rootNode] of Array.from(roots.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+            collectTypeAliases(rootKey, rootNode, `${glbKey}/${rootKey}`, aliases);
+        }
+
+        // Emit SceneData property references with hierarchy JSDoc
+        const glbSrc = glbSrcMap.get(glbKey);
+        const sourceFiles = glbSourceFilesMap.get(glbKey);
+        const treeDocLines = [` * GLB/glTF scene file`];
+        const glbSrcLink = glbSrc
+            ? (glbSrc.startsWith("http://") || glbSrc.startsWith("https://")
+                ? ` — [${glbSrc}](${addViewParam(glbSrc)})`
+                : ` — \`${glbSrc}\``)
+            : "";
+        treeDocLines.push(` * \`${glbKey}\`${glbSrcLink}`);
+        if (sourceFiles?.size) {
+            treeDocLines.push(` *`);
+            treeDocLines.push(` * **Referenced from:**`);
+            for (const sf of Array.from(sourceFiles).sort()) {
+                treeDocLines.push(` * - \`${sf}\``);
+            }
+        }
+        treeDocLines.push(` *`);
+        treeDocLines.push(` * ---`);
+        treeDocLines.push(` *`);
+        for (const [rootKey, rootNode] of Array.from(roots.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+            buildTreeDoc(rootKey, rootNode, 0, treeDocLines);
+        }
+        interfaceLines.push(`    /**\n    ${treeDocLines.join("\n    ")}\n     */`);
+        interfaceLines.push(`    $${glbKey}: {`);
+        for (const [rootKey, rootNode] of Array.from(roots.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+            const alias = typeAliasName(`${glbKey}/${rootKey}`);
+            const summary = nodeSummary(rootNode);
+            interfaceLines.push(`      /** ${summary} */`);
+            interfaceLines.push(`      ${propKey(rootKey)}: ${alias};`);
+        }
+        interfaceLines.push(`    };`);
+    }
+
+    interfaceLines.push(`  }`);
+    interfaceLines.push(`}`);
+
+    return [...header, ``, ...aliases, ``, ...interfaceLines, ``].join("\n");
+}
+
+/**
+ * Generate VS Code HTML custom data JSON for `data-bind-needle` completions.
+ *
+ * @param {BindingEntry[]} entries
+ * @returns {string}  JSON string
+ */
+export function generateHtmlCustomData(entries) {
+    const pairs = Array.from(
+        new Set(entries.filter(e => e.componentName).map(e => `${e.nodePath}/${e.componentName}`))
+    ).sort();
+
+    const values = pairs.map(pair => {
+        const slash = pair.lastIndexOf("/");
+        const nodePath = pair.slice(0, slash);
+        const compName = pair.slice(slash + 1);
+        return {
+            name: pair,
+            description: `Bind to the **${compName}** component on node \`${nodePath}\`.`,
+        };
+    });
+
+    const data = {
+        version: 1.1,
+        globalAttributes: [
+            {
+                name: "data-bind-needle",
+                description: {
+                    kind: "markdown",
+                    value: [
+                        "Binds this HTML element to a Needle Engine scene component.",
+                        "",
+                        "**Format:** `NodePath/ComponentName`",
+                        "",
+                        "The Needle Engine runtime will associate this element with the specified",
+                        "component instance in the live scene graph.",
+                        "",
+                        "**Example:**",
+                        "```html",
+                        '<div data-bind-needle="Camera/OrbitControls">',
+                        "```",
+                    ].join("\n"),
+                },
+                values,
+            },
+        ],
+    };
+
+    return JSON.stringify(data, null, 2) + "\n";
+}

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