lens-inspector 0.1.1 → 0.2.0

package/README.md

@@ -42,6 +42,35 @@ If you want to see it working right away, open the included `LSProject/` folder
 
 ![Demo](media/demo.gif)
 
+## Features
+
+### 3D Viewport with WASD Navigation
+
+The viewer renders every SceneObject as a labeled wireframe box in a 3D viewport. Orbit with left-click drag, pan with middle-click or right-click, zoom with scroll wheel. Fly through the scene with WASD (forward/left/back/right), Q/E (down/up), and hold Shift for speed. Navigation keys use physical key positions so they work correctly on AZERTY, QWERTZ, and other keyboard layouts.
+
+### Hierarchy Panel
+
+The left panel shows a collapsible tree matching your scene structure. Each node displays a color-coded icon by component category (camera, visual, script, light, physics, audio, VFX, etc.) and a component count badge. Runtime-spawned objects appear in blue.
+
+- **Search**: type to filter nodes by name, text content, component type, or category
+- **Category chips**: click Camera, Visual, Script, Light, Physics, Audio, Anim, UI, Track, or Empty to show only that type
+- **Expand/Collapse**: click the arrow to fold tree branches without affecting 3D visibility
+- **Eye toggle**: hover a node and click the eye icon to hide or show it in the 3D viewport independently of the tree
+
+### Inspector Panel
+
+Click any node in the tree or 3D viewport to see its transform (position, scale, rotation), object properties (enabled, children count, layer, category), color, text content, and a full component list with type-specific details like mesh name, material, script asset, camera FOV, audio track, and physics mass.
+
+### MCP Component Enrichment
+
+The runtime scene graph walker detects components by probing 40+ known Lens Studio types individually (Camera, ScriptComponent, RenderMeshVisual, LightSource, etc.). When the generic `getComponentCount("Component")` returns 0 for certain LS versions or object types, the fallback catches what would otherwise show as empty nodes.
+
+For additional component detail, paste your Lens Studio MCP config JSON into the welcome screen. The viewer proxies MCP calls through the inspector server to avoid CORS, fetching the design-time scene graph and merging component data into live nodes. Copy the config from **AI Assistant > MCP** in Lens Studio.
+
+### Configurable Server
+
+Change the server address in the welcome screen if you run the inspector on a different port or machine. The setting persists in localStorage.
+
 ## Two modes
 
 **Runtime**: A Script component inside your lens walks the full scene graph using the SceneObject API, serializes the hierarchy into JSON, and sends it over WebSocket to the browser. This captures everything: both the objects you placed in the Scene Hierarchy and anything created by Scripts at runtime.
@@ -50,9 +79,23 @@ If you want to see it working right away, open the included `LSProject/` folder
 
 **Design-time**: When your lens isn't running, the viewer can fetch the static scene structure through Lens Studio's MCP server. This is useful for inspecting your Scene Hierarchy without entering preview mode.
 
+To use design-time mode:
+
+1. In Lens Studio, go to **AI Assistant > MCP > Configure Server** and set a port
+2. Click **Copy MCP Config** to get the JSON with server URL and auth token
+3. In the inspector welcome screen, paste the full MCP config JSON into the MCP Config field
+
+If your MCP server runs on a non-default port, you can also pass a token on the command line:
+
+```bash
+npx lens-inspector --mcp http://localhost:8733/mcp --mcp-token YOUR_TOKEN
+```
+
+The MCP config from Lens Studio also works with AI coding assistants like Claude. Paste it into your assistant's MCP server config to let it read and modify your scene programmatically.
+
 ## The viewer
 
-The browser shows three synchronized panels. A collapsible tree that matches the Scene Hierarchy, where you can search and click to select nodes. A 2D spatial canvas with switchable projection planes (TOP/FRONT/SIDE) that plots object positions with pan and zoom, so you can see how things are laid out relative to each other. And an inspector panel that shows transform data, component details, text content, and colors for whatever node you've selected.
+The browser shows three synchronized panels. A hierarchy tree on the left with search, category filters, and independent visibility toggles. A 3D viewport in the center with an infinite multi-level grid, axis graduations in centimeters/meters, a navigation gizmo, and WASD fly controls. And an inspector panel on the right showing transform data, component details, text content, and colors for the selected node. All three panels are resizable by dragging the borders between them.
 
 ![Front view showing spatial layout](media/03-front.png)
 
@@ -82,17 +125,19 @@ The SceneInspector component exposes three inputs in Lens Studio's Inspector pan
 The server accepts these flags:
 
 ```bash
-node server.js --port 9000     # custom port
-node server.js --no-open       # don't auto-open browser
+node server.js --port 9000                          # custom port
+node server.js --no-open                            # don't auto-open browser
+node server.js --mcp http://localhost:8733/mcp      # custom MCP URL
+node server.js --mcp-token YOUR_TOKEN               # MCP auth token
 ```
 
 ## Architecture
 
-The entire tool is three files with about 500 lines of code total and no build step or external framework:
+The entire tool is three files with no build step or external framework:
 
-- **SceneInspector.ts** (~180 lines): LS component that walks and serializes the scene graph
-- **server.js** (~120 lines): WebSocket relay between LS and browser, with an MCP proxy for design-time queries
-- **index.html** (single file): the entire browser viewer with zero frontend dependencies
+- **SceneInspector.ts** (~370 lines): LS component that walks and serializes the scene graph, with fallback type-specific component probing
+- **server.js** (~200 lines): WebSocket relay between LS and browser, with an MCP proxy for design-time queries and live reload
+- **index.html** (single file): the entire browser viewer with Three.js 3D viewport, hierarchy, and inspector
 
 The code is meant to be read and modified. If you want to add custom component introspection or change the viewer layout, everything is right there in plain files.
 

package/SceneInspector.ts

@@ -19,7 +19,7 @@
 @component
 export class SceneInspector extends BaseScriptComponent {
   @input
-  @hint("Inspector server WebSocket URL")
+  @hint("Inspector server URL. Change port if you ran: npx lens-inspector --port XXXX")
   public wsUrl: string = "ws://localhost:8200?role=ls";
 
   @input
@@ -145,13 +145,134 @@ export class SceneInspector extends BaseScriptComponent {
     return "unknown";
   }
 
+  private processComponent(comp: any, typeName: string, components: any[]) {
+    var category = this.classifyComponent(typeName);
+    var compInfo: any = {
+      type: typeName,
+      enabled: comp.enabled !== false,
+      category: category,
+    };
+
+    // Extract text content
+    if (typeName === "Text" || typeName === "Component.Text") {
+      compInfo.text = comp.text || null;
+      if (comp.size !== undefined) compInfo.textSize = comp.size;
+    }
+    if (typeName === "Text3D" || typeName === "Component.Text3D") {
+      compInfo.text = comp.text || null;
+    }
+
+    // Extract visual info
+    if (category === "visual") {
+      try {
+        var mat = comp.mainMaterial;
+        if (mat && mat.mainPass) {
+          var bc = mat.mainPass["baseColor"];
+          if (bc) compInfo._color = [
+            Math.round(bc.x * 255),
+            Math.round(bc.y * 255),
+            Math.round(bc.z * 255),
+            Math.round(bc.w * 255),
+          ];
+          compInfo.materialName = mat.name || null;
+        }
+      } catch (e) {}
+      try {
+        if (comp.mesh) compInfo.meshName = comp.mesh.name || null;
+      } catch (e) {}
+    }
+
+    // Extract script info
+    if (category === "script") {
+      try {
+        if (comp.scriptAsset) compInfo.scriptName = comp.scriptAsset.name || null;
+      } catch (e) {}
+    }
+
+    // Extract camera info
+    if (category === "camera") {
+      try {
+        compInfo.cameraType = comp.cameraType === 1 ? "orthographic" : "perspective";
+        if (comp.fov !== undefined) compInfo.fov = comp.fov;
+        if (comp.size !== undefined) compInfo.orthoSize = comp.size;
+        if (comp.near !== undefined) compInfo.near = comp.near;
+        if (comp.far !== undefined) compInfo.far = comp.far;
+        compInfo.renderOrder = comp.renderOrder || 0;
+      } catch (e) {}
+    }
+
+    // Extract physics info
+    if (category === "physics") {
+      try {
+        if (comp.dynamic !== undefined) compInfo.dynamic = comp.dynamic;
+        if (comp.mass !== undefined) compInfo.mass = comp.mass;
+      } catch (e) {}
+    }
+
+    // Extract audio info
+    if (category === "audio") {
+      try {
+        if (comp.volume !== undefined) compInfo.volume = comp.volume;
+        if (comp.audioTrack) compInfo.trackName = comp.audioTrack.name || null;
+      } catch (e) {}
+    }
+
+    components.push(compInfo);
+  }
+
+  // Known LS component types to probe individually when generic lookup fails
+  private static KNOWN_TYPES: string[] = [
+    "Camera",
+    "ScriptComponent",
+    "RenderMeshVisual",
+    "Image",
+    "Text",
+    "Text3D",
+    "LightSource",
+    "ScreenTransform",
+    "ScreenRegionComponent",
+    "Canvas",
+    "AnimationMixer",
+    "AnimationPlayer",
+    "AudioComponent",
+    "AudioListenerComponent",
+    "VFXComponent",
+    "BodyComponent",
+    "ColliderComponent",
+    "WorldComponent",
+    "InteractionComponent",
+    "ManipulateComponent",
+    "DeviceTracking",
+    "ObjectTracking3D",
+    "MarkerTrackingComponent",
+    "Head",
+    "BlendShapes",
+    "SpriteVisual",
+    "PostEffectVisual",
+    "FaceMaskVisual",
+    "FaceInsetVisual",
+    "RectangleSetter",
+    "PinToMeshComponent",
+    "LookAtComponent",
+    "ClothVisual",
+    "HintsComponent",
+    "SkinComponent",
+    "MLComponent",
+    "RetouchVisual",
+    "EyeColorVisual",
+    "HairVisual",
+    "LiquifyVisual",
+    "ClearScreenComponent",
+    "ParticlesVisual",
+  ];
+
   private walkObject(obj: SceneObject, depth: number): any {
     if (depth > this.maxDepth) return null;
 
     var t = obj.getTransform();
-    var pos = t.getLocalPosition();
-    var scl = t.getLocalScale();
-    var rot = t.getLocalRotation();
+    var pos = t.getWorldPosition();
+    var scl = t.getWorldScale();
+    var rot = t.getWorldRotation();
 
     // Gather components
     var components: any[] = [];
@@ -160,96 +281,54 @@ export class SceneInspector extends BaseScriptComponent {
     var color: number[] | null = null;
     var primaryCategory = "empty";
 
+    // Try generic component lookup first
     var compCount = obj.getComponentCount("Component");
-    for (var ci = 0; ci < compCount; ci++) {
-      try {
-        var comp = obj.getComponentByIndex("Component", ci) as any;
-        var typeName = comp.getTypeName ? comp.getTypeName() : "Unknown";
-        var category = this.classifyComponent(typeName);
-        var compInfo: any = {
-          type: typeName,
-          enabled: comp.enabled !== false,
-          category: category,
-        };
-
-        // Extract text content
-        if (typeName === "Text" || typeName === "Component.Text") {
-          text = comp.text || null;
-          compInfo.text = text;
-          if (comp.size !== undefined) compInfo.textSize = comp.size;
-        }
-        if (typeName === "Text3D" || typeName === "Component.Text3D") {
-          text = comp.text || null;
-          compInfo.text = text;
-        }
-
-        // Extract visual info
-        if (category === "visual") {
-          hasVisual = true;
-          try {
-            var mat = comp.mainMaterial;
-            if (mat && mat.mainPass) {
-              var bc = mat.mainPass["baseColor"];
-              if (bc) color = [
-                Math.round(bc.x * 255),
-                Math.round(bc.y * 255),
-                Math.round(bc.z * 255),
-                Math.round(bc.w * 255),
-              ];
-              compInfo.materialName = mat.name || null;
-            }
-          } catch (e) {}
-          try {
-            if (comp.mesh) compInfo.meshName = comp.mesh.name || null;
-          } catch (e) {}
-        }
-
-        // Extract script info
-        if (category === "script") {
-          try {
-            if (comp.scriptAsset) compInfo.scriptName = comp.scriptAsset.name || null;
-          } catch (e) {}
-        }
-
-        // Extract camera info
-        if (category === "camera") {
-          try {
-            compInfo.cameraType = comp.cameraType === 1 ? "orthographic" : "perspective";
-            if (comp.fov !== undefined) compInfo.fov = comp.fov;
-            if (comp.size !== undefined) compInfo.orthoSize = comp.size;
-            if (comp.near !== undefined) compInfo.near = comp.near;
-            if (comp.far !== undefined) compInfo.far = comp.far;
-            compInfo.renderOrder = comp.renderOrder || 0;
-          } catch (e) {}
-        }
-
-        // Extract physics info
-        if (category === "physics") {
-          try {
-            if (comp.dynamic !== undefined) compInfo.dynamic = comp.dynamic;
-            if (comp.mass !== undefined) compInfo.mass = comp.mass;
-          } catch (e) {}
-        }
+    if (compCount > 0) {
+      for (var ci = 0; ci < compCount; ci++) {
+        try {
+          var comp = obj.getComponentByIndex("Component", ci) as any;
+          var typeName = comp.getTypeName ? comp.getTypeName() : "Unknown";
+          this.processComponent(comp, typeName, components);
+        } catch (e) {}
+      }
+    } else {
+      // Fallback: probe each known type individually.
+      // getComponentCount("Component") returns 0 in some LS versions
+      // but type-specific lookups still work.
+      for (var ti = 0; ti < SceneInspector.KNOWN_TYPES.length; ti++) {
+        var probeName = SceneInspector.KNOWN_TYPES[ti];
+        try {
+          var probeCount = obj.getComponentCount(probeName);
+          for (var pi = 0; pi < probeCount; pi++) {
+            try {
+              var probeComp = obj.getComponentByIndex(probeName, pi) as any;
+              var probeTypeName = probeComp.getTypeName ? probeComp.getTypeName() : probeName;
+              this.processComponent(probeComp, probeTypeName, components);
+            } catch (e2) {}
+          }
+        } catch (e3) {}
+      }
+    }
 
-        // Extract audio info
-        if (category === "audio") {
-          try {
-            if (comp.volume !== undefined) compInfo.volume = comp.volume;
-            if (comp.audioTrack) compInfo.trackName = comp.audioTrack.name || null;
-          } catch (e) {}
-        }
+    // Derive category and visual flags from collected components
+    for (var ci2 = 0; ci2 < components.length; ci2++) {
+      var compInfo = components[ci2];
+      var category = compInfo.category;
+      if (compInfo.text) text = compInfo.text;
+      if (category === "visual") hasVisual = true;
+      if (compInfo._color) color = compInfo._color;
 
-        // Determine primary category (first "interesting" component wins)
-        if (primaryCategory === "empty" || primaryCategory === "unknown") {
-          if (category !== "unknown") primaryCategory = category;
-        }
-        // But camera/script/visual always take priority
-        if (category === "camera" || category === "script" || category === "visual" || category === "text") {
-          if (primaryCategory !== "camera") primaryCategory = category;
-        }
+      if (primaryCategory === "empty" || primaryCategory === "unknown") {
+        if (category !== "unknown") primaryCategory = category;
+      }
+      if (category === "camera" || category === "script" || category === "visual" || category === "text") {
+        if (primaryCategory !== "camera") primaryCategory = category;
+      }
+    }
 
-        components.push(compInfo);
-      } catch (e) {}
+    // Clean internal fields
+    for (var ci3 = 0; ci3 < components.length; ci3++) {
+      delete components[ci3]._color;
     }
 
     // Get layer info
@@ -262,8 +341,8 @@ export class SceneInspector extends BaseScriptComponent {
     // Walk children
     var childNodes: any[] = [];
     var childCount = obj.getChildrenCount();
-    for (var ci2 = 0; ci2 < childCount; ci2++) {
-      var child = obj.getChild(ci2);
+    for (var ki = 0; ki < childCount; ki++) {
+      var child = obj.getChild(ki);
       var childNode = this.walkObject(child, depth + 1);
       if (childNode) childNodes.push(childNode);
     }

package/example.js

@@ -13,7 +13,7 @@
 
 import WebSocket from "ws";
 
-const URL = process.argv[2] || "ws://localhost:8200?role=ls";
+const URL = process.argv[2] || "ws://localhost:8200?role=ls&source=example";
 
 let frame = 0;
 let spawned = [];
@@ -84,6 +84,7 @@ function buildScene() {
 
   const scene = {
     event: "scene_snapshot",
+    source: "example",
     ts: Date.now(),
     roots: [
       // Perspective Camera with scripts
@@ -326,7 +327,12 @@ function connect() {
     }, 1000 / 2);
   });
 
-  ws.on("close", () => {
+  ws.on("close", (code, reason) => {
+    const msg = reason?.toString() || '';
+    if (code === 1000 && msg === 'replaced') {
+      console.log("Real Lens Studio connected. Example exiting.");
+      process.exit(0);
+    }
     console.log("Disconnected, reconnecting in 2s...");
     setTimeout(connect, 2000);
   });