glass-easel-devtools-extension 0.9.0

package/.eslintignore

@@ -0,0 +1,3 @@
+/node_modules
+/dist
+/pkg

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 wechat-miniprogram
+
+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,16 @@
+# glass-easel DevTools for Browsers
+
+This is the DevTools panel implementation of glass-easel-devtools for Chrome/Firefox DevTools.
+
+See [glass-easel-devtools](https://github.com/wechat-miniprogram/glass-easel-devtools) for details.
+
+## How to Build
+
+[nodejs](https://nodejs.org/en) and [pnpm](https://pnpm.io/) should be globally installed.
+
+In the project root directory (glass-easel-devtools):
+
+1. run `pnpm install` to install dependencies;
+2. run `npm run pack-extension` to build.
+
+The final product can be found in `extension/pkg` directory.

package/chrome.manifest.json

@@ -0,0 +1,28 @@
+{
+  "description": "DevTools extension for developing glass-easel applications",
+  "manifest_version": 3,
+  "name": "glass-easel DevTools",
+  "version": "0.9.0",
+  "homepage_url": "https://github.com/wechat-miniprogram/glass-easel",
+  "icons": {
+    "16": "icons/glass-easel-16.png",
+    "32": "icons/glass-easel-32.png",
+    "48": "icons/glass-easel-48.png",
+    "64": "icons/glass-easel-64.png",
+    "128": "icons/glass-easel-128.png",
+    "256": "icons/glass-easel-256.png",
+    "512": "icons/glass-easel-512.png"
+  },
+  "permissions": [
+    "activeTab",
+    "scripting",
+    "webNavigation"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "service_worker": "dist/background.js"
+  },
+  "devtools_page": "dist/devtools.html"
+}

package/firefox.manifest.json

@@ -0,0 +1,28 @@
+{
+  "description": "DevTools extension for developing glass-easel applications",
+  "manifest_version": 3,
+  "name": "glass-easel DevTools",
+  "version": "0.9.0",
+  "homepage_url": "https://github.com/wechat-miniprogram/glass-easel",
+  "icons": {
+    "16": "icons/glass-easel-16.png",
+    "32": "icons/glass-easel-32.png",
+    "48": "icons/glass-easel-48.png",
+    "64": "icons/glass-easel-64.png",
+    "128": "icons/glass-easel-128.png",
+    "256": "icons/glass-easel-256.png",
+    "512": "icons/glass-easel-512.png"
+  },
+  "permissions": [
+    "activeTab",
+    "scripting",
+    "webNavigation"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "scripts": ["dist/background.js"]
+  },
+  "devtools_page": "dist/devtools.html"
+}

package/pack.js

@@ -0,0 +1,74 @@
+/* eslint-disable import/no-extraneous-dependencies */
+
+const fs = require('fs')
+const path = require('path')
+const archiver = require('archiver')
+
+fs.mkdirSync(path.join(__dirname, 'pkg'), { recursive: true })
+
+const createZip = (outName, dirs, files) =>
+  new Promise((resolve) => {
+    const output = fs.createWriteStream(path.join(__dirname, 'pkg', outName))
+    const archive = archiver('zip', {
+      zlib: { level: 9 },
+    })
+    output.on('close', () => {
+      resolve()
+    })
+    output.on('warning', (err) => {
+      throw err
+    })
+    output.on('error', (err) => {
+      throw err
+    })
+    archive.pipe(output)
+    Object.entries(dirs).forEach(([key, value]) => {
+      archive.directory(key, value)
+    })
+    Object.entries(files).forEach(([key, value]) => {
+      archive.file(key, { name: value })
+    })
+    archive.finalize()
+  })
+
+createZip(
+  'glass-easel-devtools-chrome.zip',
+  { dist: 'dist', icons: 'icons' },
+  { 'chrome.manifest.json': 'manifest.json' },
+)
+
+createZip(
+  'glass-easel-devtools-firefox.zip',
+  { dist: 'dist', icons: 'icons' },
+  { 'firefox.manifest.json': 'manifest.json' },
+)
+
+createZip(
+  'source.zip',
+  {
+    src: 'extension/src',
+    icons: 'extension/icons',
+    '../agent/src': 'agent/src',
+    '../panel/src': 'panel/src',
+    '../panel/typings': 'panel/typings',
+  },
+  {
+    'README.md': 'README.md',
+    'package.json': 'extension/package.json',
+    'tsconfig.json': 'extension/tsconfig.json',
+    'webpack.config.js': 'extension/webpack.config.js',
+    'pack.js': 'extension/pack.js',
+    '../package.json': 'package.json',
+    '../pnpm-lock.yaml': 'pnpm-lock.yaml',
+    '../pnpm-workspace.yaml': 'pnpm-workspace.yaml',
+    '../tsconfig.json': 'tsconfig.json',
+    '../agent/package.json': 'agent/package.json',
+    '../agent/tsconfig.json': 'agent/tsconfig.json',
+    '../agent/webpack.config.js': 'agent/webpack.config.js',
+    '../agent/wxml_loader.js': 'agent/wxml_loader.js',
+    '../panel/package.json': 'panel/package.json',
+    '../panel/tsconfig.json': 'panel/tsconfig.json',
+    '../panel/webpack.config.js': 'panel/webpack.config.js',
+    '../panel/src.d.ts': 'panel/src.d.ts',
+  },
+)

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "glass-easel-devtools-extension",
+  "version": "0.9.0",
+  "main": "src/utils.ts",
+  "dependencies": {
+    "glass-easel": "^0.9.0",
+    "glass-easel-devtools-agent": "0.9.0",
+    "glass-easel-devtools-panel": "0.9.0"
+  },
+  "devDependencies": {
+    "archiver": "^7.0.1",
+    "copy-webpack-plugin": "^12.0.2"
+  },
+  "scripts": {
+    "build": "webpack --config webpack.config.js --no-devtool",
+    "dev": "webpack --config webpack.config.js --mode development --watch",
+    "debug-chrome": "ln -s -f chrome.manifest.json manifest.json",
+    "debug-firefox": "ln -s -f firefox.manifest.json manifest.json"
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,50 @@
+import { getDevTools, type protocol } from 'glass-easel-devtools-agent'
+import { type DevToolsBridge } from '../utils'
+
+export type AgentSendMessageMeta = protocol.AgentSendMessage | { kind: '_init' }
+
+if (window.top !== window) {
+  // for iframes, connect to the top frame
+  setTimeout(() => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if ((window.top as any)?.__glassEaselDevTools__) {
+      const userTopGlobal = window.top as unknown as { __glassEaselDevTools__: DevToolsBridge }
+      const userGlobal = window as unknown as { __glassEaselDevTools__?: DevToolsBridge }
+      userGlobal.__glassEaselDevTools__?._devToolsConnect(userTopGlobal.__glassEaselDevTools__)
+    }
+  }, 0)
+} else {
+  // receive the host element
+  const hostElement = document.querySelector('glass-easel-devtools')
+  if (!hostElement) throw new Error('Failed to initialize glass-easel DevTools agent')
+
+  // messaging with content script
+  const postMessage = (message: AgentSendMessageMeta) => {
+    const ev = new CustomEvent('glass-easel-devtools-agent-send', { detail: message })
+    hostElement.dispatchEvent(ev)
+  }
+  hostElement.addEventListener('glass-easel-devtools-agent-recv', (ev) => {
+    const { detail } = ev as CustomEvent<protocol.AgentRecvMessage>
+    requestListener?.(detail)
+  })
+
+  // create the real agent
+  let requestListener: ((data: protocol.AgentRecvMessage) => void) | null = null
+  const messageChannel = {
+    send(data: protocol.AgentSendMessage) {
+      postMessage(data)
+    },
+    recv(listener: (data: protocol.AgentRecvMessage) => void) {
+      requestListener = listener
+    },
+  }
+  const devTools = getDevTools(messageChannel)
+
+  setTimeout(() => {
+    const userGlobal = window as unknown as { __glassEaselDevTools__?: DevToolsBridge }
+    userGlobal.__glassEaselDevTools__?._devToolsConnect(devTools)
+  }, 0)
+
+  // send a message to indicate the agent ready
+  postMessage({ kind: '_init' })
+}

package/src/background/index.ts

@@ -0,0 +1,116 @@
+import { type AgentSendMessageMeta } from '../agent'
+import { type PanelSendMessageMeta } from '../panel'
+import { ConnectionSource } from '../utils'
+
+// inject a small user script
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+chrome.scripting.registerContentScripts([
+  {
+    id: 'glassEaselDevToolsUser',
+    world: 'MAIN',
+    matches: ['<all_urls>'],
+    allFrames: true,
+    js: ['dist/stub.js'],
+    runAt: 'document_start',
+  },
+])
+
+// inject main agent when needed
+const injectContentScript = (tabId: number) => {
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  chrome.scripting.executeScript({
+    target: {
+      tabId,
+      allFrames: false,
+    },
+    files: ['dist/content.js'],
+  })
+}
+const injectAgentScript = (tabId: number) => {
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  chrome.scripting.executeScript({
+    world: 'MAIN',
+    target: {
+      tabId,
+      allFrames: true,
+    },
+    files: ['dist/agent.js'],
+  })
+}
+
+// states
+const tabMetaMap = Object.create(null) as Record<
+  number,
+  {
+    devTools: chrome.runtime.Port
+    contentScript?: chrome.runtime.Port
+  }
+>
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name === ConnectionSource.DevToolsPanel) {
+    newDevToolsConnection(port)
+  } else if (port.name === ConnectionSource.ContentScript) {
+    newContentScriptConnection(port)
+  }
+})
+
+// connections from DevTools
+const newDevToolsConnection = (port: chrome.runtime.Port) => {
+  let tabId = 0
+  port.onMessage.addListener((message: PanelSendMessageMeta) => {
+    if (message.kind === '_init') {
+      if (tabId) delete tabMetaMap[tabId]
+      tabId = message.tabId
+      tabMetaMap[tabId] = { devTools: port }
+      injectContentScript(tabId)
+    } else if (message.kind !== '') {
+      const tabMeta = tabMetaMap[tabId]
+      if (!tabMeta) return
+      if (tabMeta.contentScript) {
+        tabMeta.contentScript.postMessage(message)
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn('Failed to send message to agent since the agent is not connected')
+      }
+    }
+  })
+  port.onDisconnect.addListener((_port) => {
+    if (tabId) delete tabMetaMap[tabId]
+  })
+}
+
+// connections from content script
+const newContentScriptConnection = (port: chrome.runtime.Port) => {
+  const tabId = port.sender?.tab?.id
+  if (tabId === undefined) return
+  const tabMeta = tabMetaMap[tabId]
+  if (!tabMeta) return
+  port.onMessage.addListener((message: AgentSendMessageMeta) => {
+    const tabMeta = tabMetaMap[tabId]
+    if (!tabMeta) return
+    if (message.kind === '_init') {
+      tabMeta.contentScript = port
+      tabMeta.devTools.postMessage({ kind: '_connected' })
+    } else {
+      tabMeta.devTools.postMessage(message)
+    }
+  })
+  port.onDisconnect.addListener((_port) => {
+    const tabMeta = tabMetaMap[tabId]
+    if (!tabMeta) return
+    tabMeta.contentScript = undefined
+  })
+  injectAgentScript(tabId)
+}
+
+// inject agent when reloaded
+chrome.webNavigation.onDOMContentLoaded.addListener((ev) => {
+  const tabId = ev.tabId
+  if (ev.frameId !== 0) return
+  const tabMeta = tabMetaMap[tabId]
+  if (!tabMeta) return
+  injectContentScript(tabId)
+})
+
+// eslint-disable-next-line no-console
+console.log('glass-easel DevTools extension started')

package/src/content/index.ts

@@ -0,0 +1,53 @@
+import { type protocol } from 'glass-easel-devtools-agent'
+import { ConnectionSource, inFirefox } from '../utils'
+
+declare function cloneInto<T>(x: T, target: Window): T
+
+const prepareDataToAgent = <T>(data: T): T => {
+  if (inFirefox()) return cloneInto(data, window)
+  return data
+}
+
+// avoid double injection
+const existingElements = document.querySelectorAll('glass-easel-devtools')
+for (let i = 0; i < existingElements.length; i += 1) {
+  const hostElement = existingElements[i]
+  hostElement.parentNode?.removeChild(hostElement)
+}
+
+// create a host node
+const hostElement = document.createElement('glass-easel-devtools')
+const hostNodeStyle = `
+  display: none;
+  position: fixed;
+  left: 0;
+  top: 0;
+  right: 0;
+  bottom: 0;
+`
+hostElement.setAttribute('style', hostNodeStyle)
+document.documentElement.appendChild(hostElement)
+
+// messaging from background to agent
+const background = chrome.runtime.connect({
+  name: ConnectionSource.ContentScript,
+})
+const sendHeartbeat = () => {
+  setTimeout(() => {
+    background.postMessage({ kind: '' })
+    sendHeartbeat()
+  }, 15000)
+}
+sendHeartbeat()
+background.onMessage.addListener((message: protocol.AgentRecvMessage) => {
+  const ev = new CustomEvent('glass-easel-devtools-agent-recv', {
+    detail: prepareDataToAgent(message),
+  })
+  hostElement.dispatchEvent(ev)
+})
+
+// messaging from agent to background
+hostElement.addEventListener('glass-easel-devtools-agent-send', (ev) => {
+  const { detail } = ev as CustomEvent<protocol.AgentSendMessage>
+  background.postMessage(detail)
+})

package/src/devtools/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+  </head>
+  <body>
+    <!-- empty -->
+  </body>
+  <script src="devtools.js"></script>
+</html>

package/src/devtools/index.ts

@@ -0,0 +1,13 @@
+import { inFirefox } from '../utils'
+
+chrome.devtools.panels.create(
+  'glass-easel',
+  '../icons/glass-easel-grey-48.png',
+  inFirefox() ? 'panel.html' : 'dist/panel.html',
+  (_panel) => {
+    // empty
+  },
+)
+
+// eslint-disable-next-line no-console
+console.log('glass-easel DevTools extension DevTools created')

package/src/panel/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <link rel="stylesheet" href="index.css" />
+  </head>
+  <body>
+    <!-- the entry component will be loaded here -->
+  </body>
+  <script src="panel.js"></script>
+</html>

package/src/panel/index.ts

@@ -0,0 +1,53 @@
+import * as glassEasel from 'glass-easel'
+import {
+  startup,
+  restart,
+  type PanelRecvMessage,
+  type PanelSendMessage,
+} from 'glass-easel-devtools-panel'
+import { ConnectionSource } from '../utils'
+
+export type PanelSendMessageMeta = PanelSendMessage | { kind: '_init'; tabId: number }
+export type PanelRecvMessageMeta = PanelRecvMessage | { kind: '_connected' }
+
+// build connection to main service
+const background = chrome.runtime.connect({
+  name: ConnectionSource.DevToolsPanel,
+})
+const postToBackground = (msg: PanelSendMessageMeta) => {
+  background.postMessage(msg)
+}
+const sendHeartbeat = () => {
+  setTimeout(() => {
+    postToBackground({ kind: '' })
+    sendHeartbeat()
+  }, 15000)
+}
+sendHeartbeat()
+background.onMessage.addListener((message: PanelRecvMessageMeta) => {
+  if (message.kind === '_connected') {
+    restart()
+  } else {
+    listener?.(message)
+  }
+})
+postToBackground({ kind: '_init', tabId: chrome.devtools.inspectedWindow.tabId })
+
+// passing massage through channel
+let listener: ((data: PanelRecvMessage) => void) | null = null
+setTimeout(() => {
+  const hostContext = new glassEasel.CurrentWindowBackendContext()
+  const hostElement = document.body as unknown as glassEasel.GeneralBackendElement
+  const channel = {
+    send(data: PanelSendMessage) {
+      postToBackground(data)
+    },
+    recv(f: (data: PanelRecvMessage) => void) {
+      listener = f
+    },
+  }
+  startup(hostContext, hostElement, channel)
+}, 0)
+
+// eslint-disable-next-line no-console
+console.log('glass-easel DevTools extension DevTools panel created')

package/src/stub/index.ts

@@ -0,0 +1,41 @@
+/* eslint-disable class-methods-use-this */
+
+import type * as glassEasel from 'glass-easel'
+import { type DevTools, type DevToolsBridge, type InspectorDevTools } from '../utils'
+
+let devToolsTarget: DevTools | null = null
+const mountPoints = new Map<glassEasel.Element, glassEasel.MountPointEnv>()
+
+class Inspector implements InspectorDevTools {
+  addMountPoint(elem: glassEasel.Element, env: glassEasel.MountPointEnv) {
+    mountPoints.set(elem, env)
+    if (devToolsTarget) devToolsTarget.inspector?.addMountPoint(elem, env)
+  }
+
+  removeMountPoint(elem: glassEasel.Element) {
+    mountPoints.delete(elem)
+    if (devToolsTarget) devToolsTarget.inspector?.removeMountPoint(elem)
+  }
+}
+
+const glassEaselDevTools = {
+  inspector: new Inspector(),
+  _devToolsConnect(target: DevTools) {
+    if (devToolsTarget) {
+      this._devToolsDisconnect()
+    }
+    devToolsTarget = target
+    mountPoints.forEach((env, elem) => target.inspector?.addMountPoint(elem, env))
+  },
+  _devToolsDisconnect() {
+    if (!devToolsTarget) return
+    const target = devToolsTarget
+    devToolsTarget = null
+    mountPoints.forEach((_, elem) => target.inspector?.removeMountPoint(elem))
+  },
+}
+
+const userGlobal = window as unknown as { __glassEaselDevTools__?: DevToolsBridge }
+if (userGlobal.__glassEaselDevTools__ === undefined) {
+  userGlobal.__glassEaselDevTools__ = glassEaselDevTools
+}

package/src/utils.ts

@@ -0,0 +1,28 @@
+import type * as glassEasel from 'glass-easel'
+
+export const enum ExtensionEnv {
+  Chrome,
+  Firefox,
+}
+
+export const EXTENSION_ENV = navigator.userAgent.includes(' Firefox/')
+  ? ExtensionEnv.Firefox
+  : ExtensionEnv.Chrome
+
+export const inChrome = (): boolean => EXTENSION_ENV === ExtensionEnv.Chrome
+
+export const inFirefox = (): boolean => EXTENSION_ENV === ExtensionEnv.Firefox
+
+export type DevTools = glassEasel.DevTools
+
+export interface DevToolsBridge extends DevTools {
+  _devToolsConnect(target: DevTools): void
+  _devToolsDisconnect(): void
+}
+
+export type InspectorDevTools = glassEasel.InspectorDevTools
+
+export const enum ConnectionSource {
+  DevToolsPanel = 'DevToolsPanel',
+  ContentScript = 'ContentScript',
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+    "extends": "../tsconfig.json",
+    "include": [
+        "src/**/*.ts"
+    ]
+}

package/webpack.config.js

@@ -0,0 +1,76 @@
+/* eslint-disable import/no-extraneous-dependencies */
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const path = require('path')
+const CopyPlugin = require('copy-webpack-plugin')
+
+const config = (input, output, copyRes) => {
+  const mainFields = {
+    mode: 'production',
+    entry: '[INPUT]',
+    output: {
+      filename: '[OUTPUT]',
+      path: path.join(__dirname, 'dist'),
+      module: false,
+      iife: true,
+    },
+    devtool: 'inline-source-map',
+    resolve: {
+      extensions: ['.ts', '.js'],
+    },
+    module: {
+      rules: [
+        {
+          test: /\.ts$/,
+          loader: 'ts-loader',
+          exclude: /node_modules/,
+        },
+      ],
+    },
+    watchOptions: {
+      aggregateTimeout: 500,
+    },
+    performance: {
+      hints: false,
+      maxEntrypointSize: 4 * 1024 * 1024,
+      maxAssetSize: 4 * 1024 * 1024,
+    },
+    plugins: [],
+  }
+  mainFields.entry = input
+  mainFields.output.filename = output
+  if (copyRes) {
+    mainFields.plugins.push(new CopyPlugin(copyRes))
+  }
+  return mainFields
+}
+
+module.exports = [
+  config('./src/agent/index.ts', 'agent.js'),
+  config('./src/background/index.ts', 'background.js'),
+  config('./src/content/index.ts', 'content.js'),
+  config('./src/devtools/index.ts', 'devtools.js', {
+    patterns: [
+      {
+        from: 'src/devtools/index.html',
+        to: 'devtools.html',
+        toType: 'file',
+      },
+    ],
+  }),
+  config('./src/panel/index.ts', 'panel.js', {
+    patterns: [
+      {
+        from: '**/*.+(jpg|jpeg|png|gif|css)',
+        to: '',
+        context: 'node_modules/glass-easel-devtools-panel/dist/',
+      },
+      {
+        from: 'src/panel/index.html',
+        to: 'panel.html',
+        toType: 'file',
+      },
+    ],
+  }),
+  config('./src/stub/index.ts', 'stub.js'),
+]