Support custom renderers (#345)

Author: thetarnav

.changeset/light-friends-film.md

@@ -0,0 +1,5 @@
+---
+"@solid-devtools/debugger": minor
+---
+
+Remove element field from SourceCodeData

.changeset/proud-dogs-end.md

@@ -0,0 +1,6 @@
+---
+"@solid-devtools/debugger": minor
+"solid-devtools": minor
+---
+
+Add setElementInterface funtion to setup to support custom renderers (closes #343)

.changeset/silent-onions-invite.md

@@ -0,0 +1,6 @@
+---
+"@solid-devtools/shared": patch
+"@solid-devtools/extension": patch
+---
+
+Move assert to shared/utils

extension/src/background.ts

@@ -6,7 +6,7 @@ It has to coordinate the communication between the different scripts based on th
 
 */
 
-import {error, log} from '@solid-devtools/shared/utils'
+import {assert, error, log} from '@solid-devtools/shared/utils'
 
 import {
     Place_Name, ConnectionName, type Port,
@@ -37,12 +37,6 @@ chrome.tabs
         }
     })
 
-function assert(condition: any, message?: string, cause?: any): asserts condition {
-    if (!condition) {
-        throw Error(message ?? 'Assertion failed', {cause})
-    }
-}
-
 function get_assert_tab_id(port: Port, place: Place_Name): Tab_Id {
     let tab_id = port.sender?.tab?.id
     assert(tab_id, `${place} has no port sender tab id.`, port)

package.json

@@ -51,7 +51,7 @@
         "vite-plugin-solid": "^2.11.6",
         "vitest": "^2.1.9"
     },
-    "packageManager": "pnpm@10.6.0",
+    "packageManager": "pnpm@10.7.0",
     "engines": {
         "node": ">=22",
         "pnpm": ">=10.6.0"

packages/debugger/README.md

@@ -27,7 +27,7 @@ pnpm add @solid-devtools/debugger
 > **Warning**
 > This package changes extremely often, and is not meant to be used directly. Unless you know what you're doing, use the main package instead.
 
-### Module overview
+## Module overview
 
 The debugger is split into four submodules:
 
@@ -48,33 +48,33 @@ The debugger needs to be setup before it can be used. To do that, import the `./
 ```ts
 import '@solid-devtools/debugger/setup'
 
-import { useDebugger } from '@solid-devtools/debugger/bundled' // or from '@solid-devtools/debugger'
+import {useDebugger} from '@solid-devtools/debugger/bundled' // or from '@solid-devtools/debugger'
 
 const debug = useDebugger()
 ```
 
-### Using component locator
+## Using component locator
 
 _Debugger feature inspired by [LocatorJS](https://www.locatorjs.com)_
 
 Locator let's you locate components on the page, and go to their source code in your IDE. All you need to do is configure it by calling `setLocatorOptions` with some options.
 
 ```ts
-import { useDebugger } from '@solid-devtools/debugger' // or 'solid-devtools/setup'
+import {useDebugger} from '@solid-devtools/debugger' // or 'solid-devtools/setup'
 
 const debug = useDebugger()
 debug.setLocatorOptions()
 ```
 
 It will not allow you to highlight hovered components on the page and reveal them in the IDE or the Chrome Extension. _(depending of if the extension panel is open or not)_
 
-#### Locator Options
+### Locator Options
 
 Not passing any options will enable the locator with <kbd>Alt</kbd> as the trigger key and no `targetIDE` selected.
 
 Currently Locator allows for specifying these props:
 
-##### `targetIDE`
+#### `targetIDE`
 
 Choose in which IDE the component source code should be revealed.
 
@@ -111,7 +111,7 @@ setLocatorOptions({
 })
 ```
 
-##### `key`
+#### `key`
 
 Holding which key should enable the locator overlay? It's `"Alt"` by default — <kbd>Alt</kbd> on Windows, and <kbd>Option</kbd> or <kbd>⌥</kbd> on macOS.
 
@@ -123,14 +123,41 @@ setLocatorOptions({
 })
 ```
 
-#### Using the Locator on the page
+### Using the Locator on the page
 
 To activate the Locator module — you have to hold down the <kbd>Alt</kbd>/<kbd>Option</kbd> key and move your mouse around the page to highlight components and their different HTML Elements.
 
 Clicking the component should take you to the component source code, given that you specified the [`targetIDE`](#targetIDE) option.
 
 https://user-images.githubusercontent.com/24491503/174093606-a0d80331-021f-4d43-b0bb-e9a4041e1a26.mp4
 
+## Supporting custom renderers
+
+By default the debugger assumes you are using `"solid-js/web"` as jsx renderer and that the rendered elements are `HTMLElement`s.
+
+If you are using a custom renderer—such as Three.js, Pixi.js, or Lightning.js—you need to provide the debugger with an `ElementInterface` implementation.
+
+```ts
+import * as debug from '@solid-devtools/debugger/types'
+import {setElementInterface} from '@solid-devtools/debugger/setup' // or 'solid-devtools/setup'
+
+/** ElementInterface implementation for DOM Element */
+let element_interface: debug.ElementInterface<Element> = {
+    isElement:    obj => obj instanceof Element,
+    getElementAt: e => e.target as Element | null,
+    getName:      el => el.localName,
+    getChildren:  el => el.children,
+    getParent:    el => el.parentElement,
+    getRect:      el => el.getBoundingClientRect(),
+    getLocation:  el => {
+        let attr = debug.getLocationAttr(el)
+        return attr && debug.parseLocationString(attr) || null
+    },
+}
+
+setElementInterface(element_interface)
+```
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md).

packages/debugger/package.json

@@ -52,7 +52,6 @@
         "@nothing-but/utils": "~0.17.0",
         "@solid-devtools/shared": "workspace:^",
         "@solid-primitives/bounds": "^0.1.0",
-        "@solid-primitives/cursor": "^0.1.0",
         "@solid-primitives/event-listener": "^2.4.0",
         "@solid-primitives/keyboard": "^1.3.0",
         "@solid-primitives/platform": "^0.2.0",

packages/debugger/src/inspector/index.ts

@@ -62,6 +62,7 @@ export function createInspector(props: {
                     const encoded = encodeValue(
                         node.getValue(),
                         selected,
+                        setup.eli,
                         selected &&
                             (storeNode => node.addStoreObserver(observeStoreNode(storeNode))),
                     )
@@ -79,7 +80,7 @@ export function createInspector(props: {
                         [
                             storeProperty,
                             typeof data === 'object'
-                                ? encodeValue(data.value, true, undefined, true)
+                                ? encodeValue(data.value, true, setup.eli, undefined, true)
                                 : data ?? null,
                         ],
                     ])
@@ -163,6 +164,7 @@ export function createInspector(props: {
                 onValueUpdate:     pushValueUpdate,
                 onPropStateChange: pushPropState,
                 observedPropsMap:  propsMap,
+                eli:               setup.eli,
             })
 
             props.emit(msg('InspectedNodeDetails', result.details))

…es/debugger/src/inspector/index.test.tsx …ebugger/src/inspector/inspector.test.tsxpackages/debugger/src/inspector/index.test.tsx renamed to packages/debugger/src/inspector/inspector.test.tsx packages/debugger/src/inspector/index.test.tsx renamed to packages/debugger/src/inspector/inspector.test.tsx

@@ -4,9 +4,11 @@ import * as s from 'solid-js'
 import * as test from 'vitest'
 import {getObjectById, getSdtId, ObjectType} from '../main/id.ts'
 import setup from '../main/setup.ts'
-import {type Mapped, NodeType, PropGetterState, type Solid, ValueType} from '../types.ts'
+import {dom_element_interface, type Mapped, NodeType, PropGetterState, type Solid, ValueType} from '../types.ts'
 import {collectOwnerDetails} from './inspector.ts'
 
+const eli = dom_element_interface
+
 test.describe('collectOwnerDetails', () => {
     test.it('collects focused owner details', () => {
         s.createRoot(dispose => {
@@ -42,13 +44,10 @@ test.describe('collectOwnerDetails', () => {
             const [innerMemo] = memo.owned as [Solid.Memo, Solid.Computation]
 
             const {details, valueMap} = collectOwnerDetails(memo, {
-                observedPropsMap: new WeakMap(),
-                onPropStateChange: () => {
-                    /**/
-                },
-                onValueUpdate: () => {
-                    /**/
-                },
+                observedPropsMap:  new WeakMap(),
+                onPropStateChange: () => {/**/},
+                onValueUpdate:     () => {/**/},
+                eli:               eli,
             })
 
             test.expect(details).toEqual({
@@ -109,13 +108,10 @@ test.describe('collectOwnerDetails', () => {
             ))
 
             const {details} = collectOwnerDetails(owner, {
-                observedPropsMap: new WeakMap(),
-                onPropStateChange: () => {
-                    /**/
-                },
-                onValueUpdate: () => {
-                    /**/
-                },
+                observedPropsMap:  new WeakMap(),
+                onPropStateChange: () => {/**/},
+                onValueUpdate:     () => {/**/},
+                eli:               eli,
             })
 
             dispose()
@@ -169,13 +165,10 @@ test.describe('collectOwnerDetails', () => {
             })
 
             const {details} = collectOwnerDetails(owner, {
-                observedPropsMap: new WeakMap(),
-                onPropStateChange: () => {
-                    /**/
-                },
-                onValueUpdate: () => {
-                    /**/
-                },
+                observedPropsMap:  new WeakMap(),
+                onPropStateChange: () => {/**/},
+                onValueUpdate:     () => {/**/},
+                eli:               eli,
             })
 
             test.expect(details).toEqual({
@@ -215,11 +208,10 @@ test.describe('collectOwnerDetails', () => {
 
             const onValueUpdate = test.vi.fn()
             collectOwnerDetails(owner, {
-                observedPropsMap: new WeakMap(),
-                onPropStateChange: () => {
-                    /**/
-                },
-                onValueUpdate: onValueUpdate,
+                observedPropsMap:  new WeakMap(),
+                onPropStateChange: () => {/**/},
+                onValueUpdate:     onValueUpdate,
+                eli:               eli,
             })
 
             test.expect(onValueUpdate).not.toBeCalled()
@@ -249,11 +241,10 @@ test.describe('collectOwnerDetails', () => {
 
             const onValueUpdate = test.vi.fn()
             collectOwnerDetails(owner, {
-                observedPropsMap: new WeakMap(),
-                onPropStateChange: () => {
-                    /**/
-                },
-                onValueUpdate: onValueUpdate,
+                observedPropsMap:  new WeakMap(),
+                onPropStateChange: () => {/**/},
+                onValueUpdate:     onValueUpdate,
+                eli:               eli,
             })
 
             test.expect(onValueUpdate).not.toBeCalled()