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

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

@@ -3,81 +3,284 @@
  * Pure string generators — no I/O.
  *
  * Takes `BindingEntry[]` from dts.scan.js and produces:
- *   - `needle-bindings.d.ts`  (TypeScript ambient module augmentation)
+ *   - `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}"`;
 }
 
 /**
- * Generate the `needle-bindings.d.ts` content from binding entries.
+ * 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) {
-    // Build: nodeName → { nodePath, components: Map<componentName, { isEngineComponent, fields }> }
-    /** @type {Map<string, { nodePath: string, nodeThreeType: string, components: Map<string, { isEngineComponent: boolean, fields: Map<string, Set<string>> }> }>} */
-    const byNode = new Map();
-
-    for (const { nodeName, nodePath, componentName, fieldTypes, isEngineComponent, nodeThreeType } of entries) {
-        const nodeKey = nodeName || "_";
-        if (!byNode.has(nodeKey)) byNode.set(nodeKey, { nodePath: nodePath ?? nodeKey, nodeThreeType, components: new Map() });
-        const nodeEntry = /** @type {{ nodePath: string, nodeThreeType: string, components: Map<string, { isEngineComponent: boolean, fields: Map<string, Set<string>> }> }} */ (byNode.get(nodeKey));
-        const byComp = nodeEntry.components;
-
-        if (!byComp.has(componentName)) byComp.set(componentName, { isEngineComponent, fields: new Map() });
-        const entry = /** @type {{ isEngineComponent: boolean, fields: Map<string, Set<string>> }} */ (byComp.get(componentName));
-
-        for (const [field, tsType] of Object.entries(fieldTypes)) {
-            if (!entry.fields.has(field)) entry.fields.set(field, new Set());
-            /** @type {Set<string>} */ (entry.fields.get(field)).add(tsType);
+    /** @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 lines = [
+    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.`,
-        `declare module "needle:bindings" {`,
+        `// 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 [nodeKey, { nodePath, nodeThreeType, components }] of Array.from(byNode.entries()).sort(([a], [b]) => a.localeCompare(b))) {
-        const compEntries = Array.from(components.entries()).filter(([n]) => n !== "").sort(([a], [b]) => a.localeCompare(b));
-
-        if (compEntries.length === 0) {
-            // Node-only entry — skip, nothing useful to emit without components
-        } else {
-            lines.push(`    /** @path ${nodePath} */`);
-            lines.push(`    ${propKey(nodeKey)}: {`);
-            lines.push(`      $node: ${nodeThreeType};`);
-            for (const [compName, { isEngineComponent, fields }] of compEntries) {
-                if (isEngineComponent) {
-                    lines.push(`      ${propKey(compName)}: import("@needle-tools/engine").${compName};`);
-                } else {
-                    lines.push(`      ${propKey(compName)}: {`);
-                    lines.push(`        enabled: boolean;`);
-                    for (const [field, types] of Array.from(fields.entries()).sort(([a], [b]) => a.localeCompare(b))) {
-                        lines.push(`        ${field}: ${Array.from(types).join(" | ")};`);
-                    }
-                    lines.push(`      };`);
-                }
+    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}\``);
             }
-            lines.push(`    };`);
         }
+        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(`    };`);
     }
 
-    lines.push(`  }`);
-    lines.push(`}`);
-    lines.push(``);
+    interfaceLines.push(`  }`);
+    interfaceLines.push(`}`);
 
-    return lines.join("\n");
+    return [...header, ``, ...aliases, ``, ...interfaceLines, ``].join("\n");
 }
 
 /**
@@ -88,14 +291,16 @@ export function generateDts(entries) {
  */
 export function generateHtmlCustomData(entries) {
     const pairs = Array.from(
-        new Set(entries.filter(e => e.componentName).map(e => `${e.nodeName}/${e.componentName}`))
+        new Set(entries.filter(e => e.componentName).map(e => `${e.nodePath}/${e.componentName}`))
     ).sort();
 
     const values = pairs.map(pair => {
-        const [nodeName, compName] = pair.split("/");
+        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 \`${nodeName}\`.`,
+            description: `Bind to the **${compName}** component on node \`${nodePath}\`.`,
         };
     });
 
@@ -109,7 +314,7 @@ export function generateHtmlCustomData(entries) {
                     value: [
                         "Binds this HTML element to a Needle Engine scene component.",
                         "",
-                        "**Format:** `NodeName/ComponentName`",
+                        "**Format:** `NodePath/ComponentName`",
                         "",
                         "The Needle Engine runtime will associate this element with the specified",
                         "component instance in the live scene graph.",

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

@@ -6,10 +6,13 @@
  * type resolution into the `BindingEntry[]` array consumed by codegen.
  */
 
-import { resolveEntrypointGlbs, collectSceneFiles } from './glb.discovery.js';
+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
@@ -19,11 +22,14 @@ import { componentsManifest } from './manifest.types.js';
  * @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 or gen.js) when available,
+ * 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
@@ -32,21 +38,41 @@ import { componentsManifest } from './manifest.types.js';
  * @returns {Promise<BindingEntry[]>}
  */
 export async function scanBindings(assetsDir, projectRoot, codegenDir) {
-    /** @type {Array<{path: string, type: "glb"|"gltf", remote?: boolean}>} */
+    /** @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) {
-        const json = file.remote
-            ? await readRemoteGlbJsonChunk(file.path)
-            : file.type === "glb"
-                ? readGlbJsonChunk(file.path)
-                : readGltfJsonFile(file.path);
+        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 = {};
@@ -63,7 +89,9 @@ export async function scanBindings(assetsDir, projectRoot, codegenDir) {
                 }
             }
             const isEngineComponent = componentName ? componentsManifest.has(componentName) : false;
-            entries.push({ nodeName, nodePath, componentName, fieldTypes, isEngineComponent, nodeThreeType });
+            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 });
         }
     }
 

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

@@ -20,7 +20,7 @@ import { generateDts, generateHtmlCustomData } from './dts.codegen.js';
  * @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
+ * @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 }) {