@dcl/inspector 7.7.1 → 7.7.2-12876822878.commit-75bba39

package/README.md

@@ -1,19 +1,206 @@
+# @dcl/inspector
 
-# Inspector
+A React-based scene editor interface for Decentraland, providing a modular architecture for scene editing and manipulation.
 
-## Development
+## Features
 
-Run `npm start` to spawn esbuild in `watch` mode. This serves the `public/` folder, every change triggers rebuilding the `bundle.js` and you'll need refresh the page. The server created is in `localhost:8000` by default, an initial message is printed but it probably quickly missed.
+- **Entity Hierarchy**: Tree-based scene management with component operations
+- **Component Inspector**: Specialized editors for all component types
+- **Level Editor**: 3D scene visualization with Babylon.js
+- **Asset Management**: Local assets, custom items, and asset packs support
 
-This also rebuilds the library section (data-layer) and exposes in `dist/` folder.
+## Installation
 
-### Running with data-layer
+```bash
+npm install @dcl/inspector
+```
 
-For faster development experience, we are faking the file-system for the data-layer, if you want to use your actual file-system, you can either:
+## Quick Start
 
-* Run the extension from VSCode on a scene
-* Run `npx sdk-commands start --data-layer --port 8001` in a scene & go to localhost:8000/?ws=ws://127.0.0.1:8001/data-layer
+1. Start the CLI server:
 
-## Build
+```bash
+npx @dcl/sdk-commands start --data-layer --port 8001
+```
 
-The `make build` in the repo root builds all the necessary for package publishment.
+2. Serve the inspector (choose one method):
+
+```bash
+# Method 1: Development server
+git clone https://github.com/decentraland/js-sdk-toolchain.git
+cd packages/@dcl/inspector
+npm start
+
+# Method 2: From node_modules
+npm install @dcl/inspector
+npx http-server node_modules/@dcl/inspector/public
+```
+
+3. Access the Inspector:
+
+```
+http://localhost:3000/?dataLayerRpcWsUrl=ws://127.0.0.1:8001/data-layer
+```
+
+Where `http://localhost:3000` is the URL of the Inspector and `ws://127.0.0.1:8001/data-layer` is the WebSocket URL of the CLI server.
+
+## Integration
+
+The Inspector supports two integration approaches:
+
+### WebSocket Integration
+
+For development environments using the CLI:
+
+```typescript
+// Connect to CLI's WebSocket server
+const inspectorUrl = `http://localhost:3000/?dataLayerRpcWsUrl=ws://127.0.0.1:8001/data-layer`
+```
+
+### IFrame Integration
+
+For web applications embedding the Inspector:
+
+```typescript
+function initRpc(iframe: HTMLIFrameElement) {
+  const transport = new MessageTransport(window, iframe.contentWindow!)
+  const storage = new StorageRPC(transport)
+
+  // Handle file operations
+  storage.handle('read_file', async ({ path }) => {
+    return fs.readFile(path)
+  })
+
+  storage.handle('write_file', async ({ path, content }) => {
+    await fs.writeFile(path, content)
+  })
+
+  // ... other handlers
+
+  return {
+    storage,
+    dispose: () => storage.dispose()
+  }
+}
+
+function InspectorComponent() {
+  const iframeRef = useRef()
+
+  const handleIframeRef = useCallback((iframe) => {
+    if (iframe) {
+      iframeRef.current = initRpc(iframe)
+    }
+  }, [])
+
+  useEffect(() => {
+    return () => iframeRef.current?.dispose()
+  }, [])
+
+  const params = new URLSearchParams({
+    dataLayerRpcParentUrl: window.location.origin
+  })
+  const inspectorUrl = `http://localhost:3000/`
+  const url = `${inspectorUrl}?${params}`
+
+  return <iframe onLoad={handleIframeRef} src={url} />
+}
+```
+
+## Configuration
+
+Configure the Inspector through URL parameters or a global object. All configuration options can be set using either method:
+
+```typescript
+type InspectorConfig = {
+  // Data Layer Configuration
+  dataLayerRpcWsUrl: string | null // ?dataLayerRpcWsUrl=ws://...
+  dataLayerRpcParentUrl: string | null // ?dataLayerRpcParentUrl=https://...
+
+  // Smart Items Configuration
+  binIndexJsUrl: string | null // ?binIndexJsUrl=https://...
+  disableSmartItems: boolean // ?disableSmartItems=true
+
+  // Content Configuration
+  contentUrl: string // ?contentUrl=https://...
+
+  // Analytics Configuration
+  segmentKey: string | null // ?segmentKey=...
+  segmentAppId: string | null // ?segmentAppId=...
+  segmentUserId: string | null // ?segmentUserId=...
+  projectId: string | null // ?projectId=...
+}
+
+// Method 1: Global configuration
+globalThis.InspectorConfig = {
+  dataLayerRpcWsUrl: 'ws://127.0.0.1:8001/data-layer',
+  contentUrl: 'https://builder-items.decentraland.org'
+}
+
+// Method 2: URL parameters
+// http://localhost:3000/?dataLayerRpcWsUrl=ws://127.0.0.1:8001/data-layer&contentUrl=https://builder-items.decentraland.org&disableSmartItems=true
+```
+
+Configuration options are resolved in the following order:
+
+1. URL parameters (highest priority)
+2. Global object
+3. Default values (lowest priority)
+
+## Testing
+
+Run all inspector tests:
+
+```bash
+make test-inspector
+```
+
+Run specific test files in watch mode:
+
+```bash
+make test-inspector FILES="--watch packages/@dcl/inspector/src/path/to/some-test.spec.ts"
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **WebSocket Connection**
+
+   - Verify CLI server is running with `--data-layer` flag
+   - Check WebSocket URL matches CLI server port
+   - Ensure no firewall blocking connection
+
+2. **File System Access**
+
+   - Check file permissions
+   - Verify CLI has necessary access rights
+   - Ensure paths are correctly formatted
+
+3. **Asset Loading**
+   - Verify `contentUrl` is correctly configured
+   - Check network access to content server
+   - Ensure asset paths are valid
+
+## Development Tips
+
+1. **Debugging**
+
+   - Use Chrome DevTools for WebSocket inspection
+   - Enable React DevTools
+   - Monitor browser console for RPC messages
+
+2. **Testing**
+   - Use in-memory implementation for unit tests
+   - Mock RPC calls for integration testing
+   - Test both WebSocket and IFrame transport
+
+## Related Architecture Decisions
+
+For a deeper understanding of the architecture and design decisions:
+
+- [ADR-281: Items in Decentraland tooling](https://adr.decentraland.org/adr/ADR-281) - Explains the Items abstraction and how it's used in the Inspector
+- [ADR-282: Decentraland Inspector](https://adr.decentraland.org/adr/ADR-282) - Details the Inspector's architecture, integration approaches, and technical decisions
+
+## License
+
+Apache 2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl/inspector",
-  "version": "7.7.1",
+  "version": "7.7.2-12876822878.commit-75bba39",
   "dependencies": {
     "@dcl/asset-packs": "^2.1.2",
     "ts-deepmerge": "^7.0.0"
@@ -11,7 +11,7 @@
     "@babylonjs/inspector": "~6.18.0",
     "@babylonjs/loaders": "~6.18.0",
     "@babylonjs/materials": "~6.18.0",
-    "@dcl/ecs": "7.7.1",
+    "@dcl/ecs": "7.7.2-12876822878.commit-75bba39",
     "@dcl/ecs-math": "2.1.0",
     "@dcl/mini-rpc": "^1.0.7",
     "@dcl/rpc": "^1.1.1",
@@ -71,5 +71,5 @@
   },
   "types": "dist/tooling-entrypoint.d.ts",
   "typings": "dist/tooling-entrypoint.d.ts",
-  "commit": "01f47021cb864d6d8e8abd32f2d5bf8dc9856e91"
+  "commit": "75bba3930f810894d7113263b2979a35c209e380"
 }