lens-inspector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armand Sumo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# lens-inspector
+
+A browser-based scene graph inspector for Lens Studio. It shows you the full hierarchy of your scene while your effect runs, including objects that scripts create at runtime, so you can see what's actually happening instead of reconstructing state from log statements.
+
+![Live scene with node selected](media/02-selected.png)
+
+## Quick start
+
+You need [Node.js](https://nodejs.org/) installed (any recent version works).
+
+```bash
+git clone https://github.com/a-sumo/lens-inspector.git
+cd lens-inspector
+npm install
+node server.js
+```
+
+The server starts and opens the viewer in your browser automatically. You'll see a waiting screen with setup steps:
+
+![Live overview](media/01-live.png)
+
+From there:
+
+1. Copy `SceneInspector.ts` into your Lens Studio project's `Assets/` folder
+2. Attach the SceneInspector component to any SceneObject in your scene
+3. In Lens Studio, go to **Project Settings > General** and enable **Experimental APIs** (required for `ws://localhost` connections)
+4. Hit Play in Lens Studio
+
+Once Lens Studio connects, the welcome screen disappears and your scene tree appears with live updates at about 2Hz.
+
+## Demo project
+
+If you want to see it working right away, open the included `LSProject/` folder in Lens Studio. It has SceneInspector and a RuntimeSpawner script already set up. Hit Play, and blocks will start appearing in both Lens Studio and the browser viewer.
+
+https://github.com/a-sumo/lens-inspector/raw/main/media/demo.mp4
+
+## Two modes
+
+**Runtime**: A component inside your effect 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 editor and anything created by scripts at runtime.
+
+![Runtime-spawned objects appearing live](media/04-runtime.png)
+
+**Design-time**: When your effect isn't running, the viewer can fetch the static scene structure through Lens Studio's MCP server. This is useful for inspecting your hierarchy without entering preview mode.
+
+## 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 a properties panel that shows transform data, component details, text content, and colors for whatever node you've selected.
+
+![Front view showing spatial layout](media/03-front.png)
+
+![Search filter narrowing the tree](media/05-search.png)
+
+## Try it without Lens Studio
+
+An example script simulates a live scene so you can try the viewer without Lens Studio installed:
+
+```bash
+node server.js          # terminal 1
+node example.js         # terminal 2
+```
+
+The browser opens automatically. The example streams a scene with blocks, columns, and new objects spawning over time, so you can see how the tree, canvas, and properties panel respond to live changes.
+
+## Configuration
+
+The SceneInspector component exposes three inputs in Lens Studio's Inspector panel:
+
+| Input | Default | Description |
+|---|---|---|
+| `wsUrl` | `ws://localhost:8200?role=ls` | Inspector server address |
+| `updateInterval` | `15` | Frames between updates (~2Hz at 30fps) |
+| `maxDepth` | `20` | Max tree traversal depth |
+
+The server accepts these flags:
+
+```bash
+node server.js --port 9000     # custom port
+node server.js --no-open       # don't auto-open browser
+```
+
+## Architecture
+
+The entire tool is three files with about 500 lines of code total and 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
+
+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.
+
+## License
+
+MIT

package/SceneInspector.ts

@@ -0,0 +1,294 @@
+/**
+ * SceneInspector - Lens Studio component that streams the live scene graph
+ * to a browser-based viewer over WebSocket.
+ *
+ * Drop this onto any SceneObject in your project. It walks the entire scene
+ * tree every N frames and sends a JSON snapshot to the inspector server.
+ * Captures both design-time and runtime-created objects, including full
+ * component introspection for all standard LS types.
+ *
+ * Setup:
+ *   1. Attach to any SceneObject (e.g. Camera)
+ *   2. Set wsUrl to your inspector server (default: ws://localhost:8200?role=ls)
+ *   3. Run `node server.js` in the inspector directory
+ *   4. Open http://localhost:8200 in your browser
+ */
+
+// @ts-nocheck - LS types not available outside Lens Studio
+
+@component
+export class SceneInspector extends BaseScriptComponent {
+  @input
+  @hint("Inspector server WebSocket URL")
+  public wsUrl: string = "ws://localhost:8200?role=ls";
+
+  @input
+  @hint("How often to send snapshots (frames between updates)")
+  public updateInterval: number = 15; // ~2Hz at 30fps
+
+  @input
+  @hint("Max tree depth to traverse (prevents runaway recursion)")
+  public maxDepth: number = 20;
+
+  private internetModule: any = null;
+  private ws: any = null;
+  private connected: boolean = false;
+  private frameCounter: number = 0;
+
+  onAwake() {
+    this.createEvent("OnStartEvent").bind(() => {
+      this.connect();
+    });
+
+    this.createEvent("UpdateEvent").bind(() => {
+      if (!this.connected) return;
+      this.frameCounter++;
+      if (this.frameCounter >= this.updateInterval) {
+        this.frameCounter = 0;
+        this.sendSnapshot();
+      }
+    });
+
+    this.createEvent("OnDestroyEvent").bind(() => {
+      if (this.ws) try { this.ws.close(); } catch (e) {}
+    });
+  }
+
+  private connect() {
+    try {
+      this.internetModule = require("LensStudio:InternetModule") as any;
+    } catch (e) {
+      print("[SceneInspector] ERROR: Could not load InternetModule: " + e);
+      return;
+    }
+
+    print("[SceneInspector] Connecting to " + this.wsUrl);
+    var ws = this.internetModule.createWebSocket(this.wsUrl);
+    this.ws = ws;
+    var self = this;
+
+    ws.addEventListener("open", function () {
+      self.connected = true;
+      print("[SceneInspector] Connected");
+      self.sendSnapshot(); // send immediately on connect
+    });
+
+    ws.addEventListener("close", function () {
+      self.connected = false;
+      print("[SceneInspector] Disconnected, reconnecting in 3s...");
+      var delay = self.createEvent("DelayedCallbackEvent") as any;
+      delay.bind(function () { self.connect(); });
+      delay.reset(3.0);
+    });
+
+    ws.addEventListener("error", function (err: any) {
+      print("[SceneInspector] WS error: " + err);
+    });
+  }
+
+  private sendSnapshot() {
+    if (!this.ws || !this.connected) return;
+
+    var scene = global.scene;
+    var rootCount = scene.getRootObjectsCount();
+    var children: any[] = [];
+
+    for (var i = 0; i < rootCount; i++) {
+      var rootObj = scene.getRootObject(i);
+      var node = this.walkObject(rootObj, 0);
+      if (node) children.push(node);
+    }
+
+    var payload = JSON.stringify({
+      event: "scene_snapshot",
+      ts: Date.now(),
+      roots: children,
+      totalObjects: this.countNodes(children),
+    });
+
+    try {
+      this.ws.send(payload);
+    } catch (e) {
+      print("[SceneInspector] Send error: " + e);
+    }
+  }
+
+  private classifyComponent(typeName: string): string {
+    // Map LS component types to categories for the viewer
+    if (typeName.includes("Camera")) return "camera";
+    if (typeName.includes("Light") || typeName === "LightSource") return "light";
+    if (typeName.includes("RenderMeshVisual") || typeName.includes("Image") ||
+        typeName.includes("FaceMask") || typeName.includes("FaceInset") ||
+        typeName.includes("Cloth") || typeName.includes("PostEffect") ||
+        typeName.includes("Liquify") || typeName.includes("Retouch") ||
+        typeName.includes("EyeColor") || typeName.includes("Hair") ||
+        typeName.includes("SpriteVisual") || typeName.includes("ClearScreen")) return "visual";
+    if (typeName.includes("Text3D") || typeName.includes("Text")) return "text";
+    if (typeName.includes("Script") || typeName.includes("SceneInspector") ||
+        typeName.includes("RuntimeSpawner")) return "script";
+    if (typeName.includes("Audio")) return "audio";
+    if (typeName.includes("Animation") || typeName.includes("AnimationMixer") ||
+        typeName.includes("AnimationPlayer") || typeName.includes("BlendShapes")) return "animation";
+    if (typeName.includes("Body") || typeName.includes("Collider") ||
+        typeName.includes("Constraint") || typeName.includes("WorldComponent") ||
+        typeName.includes("Physics")) return "physics";
+    if (typeName.includes("VFX") || typeName.includes("Particle")) return "vfx";
+    if (typeName.includes("Interaction") || typeName.includes("Manipulate")) return "interaction";
+    if (typeName.includes("Tracking") || typeName.includes("DeviceTracking") ||
+        typeName.includes("Head") || typeName.includes("Landmarker") ||
+        typeName.includes("MarkerTracking") || typeName.includes("ObjectTracking")) return "tracking";
+    if (typeName.includes("ScreenTransform") || typeName.includes("ScreenRegion") ||
+        typeName.includes("Canvas") || typeName.includes("RectangleSetter")) return "ui";
+    if (typeName.includes("ML") || typeName.includes("SnapML")) return "ml";
+    if (typeName.includes("LookAt") || typeName.includes("PinToMesh") ||
+        typeName.includes("Hints") || typeName.includes("Skin")) return "utility";
+    return "unknown";
+  }
+
+  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();
+
+    // Gather components
+    var components: any[] = [];
+    var text: string | null = null;
+    var hasVisual = false;
+    var color: number[] | null = null;
+    var primaryCategory = "empty";
+
+    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) {}
+        }
+
+        // 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) {}
+        }
+
+        // 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;
+        }
+
+        components.push(compInfo);
+      } catch (e) {}
+    }
+
+    // Get layer info
+    var layerName = null;
+    try {
+      var layer = obj.layer;
+      if (layer) layerName = layer.toString();
+    } catch (e) {}
+
+    // Walk children
+    var childNodes: any[] = [];
+    var childCount = obj.getChildrenCount();
+    for (var ci2 = 0; ci2 < childCount; ci2++) {
+      var child = obj.getChild(ci2);
+      var childNode = this.walkObject(child, depth + 1);
+      if (childNode) childNodes.push(childNode);
+    }
+
+    return {
+      name: obj.name,
+      enabled: obj.enabled,
+      category: primaryCategory,
+      pos: [+pos.x.toFixed(3), +pos.y.toFixed(3), +pos.z.toFixed(3)],
+      scale: [+scl.x.toFixed(3), +scl.y.toFixed(3), +scl.z.toFixed(3)],
+      rot: [+rot.x.toFixed(3), +rot.y.toFixed(3), +rot.z.toFixed(3), +rot.w.toFixed(3)],
+      components,
+      text,
+      hasVisual,
+      color,
+      layer: layerName,
+      children: childNodes,
+    };
+  }
+
+  private countNodes(nodes: any[]): number {
+    var count = 0;
+    for (var i = 0; i < nodes.length; i++) {
+      count += 1 + this.countNodes(nodes[i].children || []);
+    }
+    return count;
+  }
+}