Added new DevTools

devtools/README.md

@@ -0,0 +1,98 @@
+# Three.js DevTools Extension
+
+This Chrome DevTools extension provides debugging capabilities for Three.js applications. It allows you to inspect scenes, objects, materials, and renderers.
+
+## Installation
+
+1. **Development Mode**:
+   - Open Chrome and navigate to `chrome://extensions/`
+   - Enable "Developer mode" (toggle in the top-right corner)
+   - Click "Load unpacked" and select the `devtools` directory
+   - The extension will now be available in Chrome DevTools when inspecting pages that use Three.js
+
+2. **Usage**:
+   - Open Chrome DevTools on a page using Three.js (F12 or Right-click > Inspect)
+   - Click on the "Three.js" tab in DevTools
+   - The panel will automatically detect and display Three.js scenes and renderers found on the page.
+
+## Code Flow Overview
+
+### Extension Architecture
+
+The extension follows a standard Chrome DevTools extension architecture:
+
+1. **Background Script** (`background.js`): Manages the extension lifecycle and communication ports between the panel and content script.
+2. **DevTools Script** (`devtools.js`): Creates the panel when the DevTools window opens.
+3. **Panel UI** (`panel/panel.html`, `panel/panel.js`, `panel/panel.css`): The DevTools panel interface that displays the data.
+4. **Content Script** (`content-script.js`): Injected into the web page. Relays messages between the background script and the bridge script.
+5. **Bridge Script** (`bridge.js`): Injected into the page's context by the content script. Directly interacts with the Three.js instance, detects objects, gathers data, and communicates back via the content script.
+
+### Initialization Flow
+
+1. When a page loads, `content-script.js` injects `bridge.js` into the page.
+2. `bridge.js` creates the `window.__THREE_DEVTOOLS__` global object.
+3. When the DevTools panel is opened, `panel.js` connects to `background.js` (`init`) and immediately requests the current state (`request-state`).
+4. `background.js` relays the state request to `content-script.js`, which posts it to `bridge.js`.
+5. `bridge.js` responds by sending back observed renderer data (`renderer` message) and batched scene data (`scene` message).
+6. Three.js detects `window.__THREE_DEVTOOLS__` and sends registration/observation events to the bridge script as objects are created or the library initializes.
+
+### Bridge Operation (`bridge.js`)
+
+The bridge acts as the communication layer between the Three.js instance on the page and the DevTools panel:
+
+1. **Event Management**: Creates a custom event target (`DevToolsEventTarget`) to manage communication readiness and backlog events before the panel connects.
+2. **Object Tracking**:
+   - `getObjectData()`: Extracts essential data (UUID, type, name, parent, children, etc.) from Three.js objects.
+   - Maintains a local map (`devTools.objects`) of all observed objects.
+
+3. **Initial Observation & Batching**:
+   - When Three.js sends an `observe` event (via `window.__THREE_DEVTOOLS__.dispatchEvent`):
+     - If it's a renderer, its data is collected and sent immediately via a `'renderer'` message.
+     - If it's a scene, the bridge traverses the entire scene graph, collects data for the scene and all descendants, stores them locally, and sends them to the panel in a single `'scene'` batch message.
+
+4. **State Request Handling**:
+   - When the panel sends `request-state` (on load/reload), the bridge iterates its known objects and sends back the current renderer data (`'renderer'`) and scene data (`'scene'` batch).
+
+5. **Message Handling**:
+   - Listens for messages from the panel (relayed via content script) like `request-state`.
+
+### Panel Interface (`panel/`)
+
+The panel UI provides the visual representation of the Three.js objects:
+
+1. **Tree View**: Displays hierarchical representation of scenes and objects.
+2. **Renderer Details**: Shows properties and statistics for renderers in a collapsible section.
+
+## Key Features
+
+- **Scene Hierarchy Visualization**: Browse the complete scene graph.
+- **Object Inspection**: View basic object properties (type, name).
+- **Renderer Details**: View properties, render stats, and memory usage for `WebGLRenderer` instances.
+
+## Communication Flow
+
+1. **Panel ↔ Background ↔ Content Script**: Standard extension messaging for panel initialization and state requests (`init`, `request-state`).
+2. **Three.js → Bridge**: Three.js detects `window.__THREE_DEVTOOLS__` and uses its `dispatchEvent` method (sending `'register'`, `'observe'`).
+3. **Bridge → Content Script**: Bridge uses `window.postMessage` to send data (`'register'`, `'renderer'`, `'scene'`, `'update'`) to the content script.
+4. **Content Script → Background**: Content script uses `chrome.runtime.sendMessage` to relay messages from the bridge to the background.
+5. **Background → Panel**: Background script uses the established port connection (`port.postMessage`) to send data to the panel.
+
+## Key Components
+
+- **DevToolsEventTarget**: Custom event system with backlogging for async loading.
+- **Object Observation & Batching**: Efficiently tracks and sends scene graph data.
+- **Renderer Property Display**: Shows detailed statistics for renderers.
+
+## Integration with Three.js
+
+The extension relies on Three.js having built-in support for DevTools. When Three.js detects the presence of `window.__THREE_DEVTOOLS__`, it interacts with it, primarily by dispatching events.
+
+The bridge script listens for these events, organizes the data, and provides it to the DevTools panel.
+
+## Development
+
+To modify the extension:
+
+1. Edit the relevant files in the `devtools` directory.
+2. Go to `chrome://extensions/`, find the unpacked extension, and click the reload icon.
+3. Close and reopen DevTools on the inspected page to see your changes.

devtools/background.js

@@ -0,0 +1,61 @@
+// Map tab IDs to connections
+const connections = new Map();
+
+// Listen for connections from the devtools panel
+chrome.runtime.onConnect.addListener(port => {
+	let tabId;
+
+	// Listen for messages from the devtools panel
+	port.onMessage.addListener(message => {
+		if (message.name === 'init') {
+			tabId = message.tabId;
+			connections.set(tabId, port);
+		} else if (message.name === 'request-state' && tabId) {
+			chrome.tabs.sendMessage(tabId, message);
+		} else if (tabId === undefined) {
+			console.warn('Background: Message received from panel before init:', message);
+		}
+	});
+
+	// Clean up when devtools is closed
+	port.onDisconnect.addListener(() => {
+		if (tabId) {
+			connections.delete(tabId);
+		}
+	});
+});
+
+// Listen for messages from the content script
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+	if (sender.tab) {
+		const tabId = sender.tab.id;
+		const port = connections.get(tabId);
+		if (port) {
+			// Forward the message to the devtools panel
+			try {
+				port.postMessage(message);
+				// Send immediate response to avoid "message channel closed" error
+				sendResponse({ received: true });
+			} catch (e) {
+				console.error('Error posting message to devtools:', e);
+				// If the port is broken, clean up the connection
+				connections.delete(tabId);
+			}
+		}
+	}
+	return false; // Return false to indicate synchronous handling
+});
+
+// Listen for page navigation events
+chrome.webNavigation.onCommitted.addListener(details => {
+	const { tabId, frameId } = details;
+	const port = connections.get(tabId);
+
+	if (port) {
+		port.postMessage({
+			id: 'three-devtools',
+			type: 'committed',
+			frameId: frameId
+		});
+	}
+});