electrobun-preact-devtools 0.0.0 → 0.1.0

package/docs/context.md

@@ -0,0 +1,92 @@
+# Overview
+
+`electrobun-preact-devtools` lets an Electrobun app run the Preact devtools UI in a separate desktop window.
+It keeps Bun in the middle, installs `window.__PREACT_DEVTOOLS__` in the inspected app window, and mounts the vendored Preact devtools UI in a standalone window.
+
+# When to Use
+
+- Your application is built with Electrobun and uses Preact.
+- You want a standalone devtools window instead of a browser extension.
+- You already use Electrobun RPC and need a composition-friendly integration.
+- You want to keep using normal app-side imports like `preact/debug` or `preact/devtools`.
+
+# When Not to Use
+
+- Your app runs in a browser and can use the normal Preact devtools extension.
+- Your windows are sandboxed and cannot use Electrobun RPC.
+- You need one devtools window to retarget across many app windows.
+- You need framework support beyond Preact.
+
+# Core Abstractions
+
+- `PreactDevtoolsHost`: the Bun-side router that tracks targets and opens devtools windows.
+- App bridge: the preload-installed `window.__PREACT_DEVTOOLS__` object in the inspected app window.
+- Devtools window: the standalone Electrobun window that renders the vendored Preact devtools UI.
+- Target: one inspected app window identified by a `targetId`.
+- Reserved message channel: `preactDevtoolsMessage`, the package-owned Electrobun RPC message name.
+
+# Data Flow / Lifecycle
+
+1. Bun creates a `PreactDevtoolsHost`.
+2. The app window is created with host-owned or host-composed RPC and is registered with a `targetId`.
+3. The app preload installs the bridge before the app imports `preact/debug` or `preact/devtools`.
+4. When the user opens devtools, the host creates a standalone devtools window and wires its RPC.
+5. The app bridge sends renderer events to Bun.
+6. Bun forwards those events to the devtools window.
+7. The devtools window updates its local store and sends UI commands back through Bun to the app bridge.
+
+# Common Tasks -> Recommended APIs
+
+- New integration with package-owned RPC:
+  Use `createPreactDevtoolsHost`, `host.createAppWindowRPC`, `composeAppWindowViewRPC`, `installPreactDevtoolsBridge`, `composeDevtoolsWindowViewRPC`, and `mountPreactDevtoolsWindow`.
+- Existing app-window RPC:
+  Use `composeAppWindowRPC` in Bun and `composeAppWindowViewRPC` in the preload.
+- Existing devtools-window RPC:
+  Use `composeDevtoolsWindowRPC` in Bun and `composeDevtoolsWindowViewRPC` in the devtools window.
+- Logging package lifecycle issues:
+  Pass `logger` to `createPreactDevtoolsHost`, `installPreactDevtoolsBridge`, or `mountPreactDevtoolsWindow`.
+
+# Recommended Patterns
+
+- Create one `PreactDevtoolsHost` for the app process.
+- Install the app bridge in preload before any Preact devtools import runs.
+- Use the composition helpers when a window already has its own Electrobun RPC handlers.
+- Treat `preactDevtoolsMessage` as reserved package transport, not application RPC.
+- Keep one devtools window per target in v1.
+
+# Patterns to Avoid
+
+- Installing the bridge after the application has already imported `preact/debug`.
+- Reusing `preactDevtoolsMessage` for unrelated application messages.
+- Expecting direct browser-to-browser communication between the app window and the devtools window.
+- Opening devtools for a target that has not been registered with the host.
+
+# Invariants and Constraints
+
+- Both the app window and the devtools window must have Electrobun RPC enabled.
+- The package owns exactly one reserved message channel per window schema.
+- Bun is the only supported relay between the inspected app window and the devtools window.
+- The vendored `preact-devtools` snapshot defines the supported upstream bridge and UI behavior.
+
+# Error Model
+
+- `installPreactDevtoolsBridge` throws if the chosen global name is already occupied by a different value.
+- `host.registerAppWindow(...)` throws if the same `targetId` is registered to a different window.
+- `host.open(targetId)` throws if the target was never registered or the host has already been disposed.
+- Composition helpers throw if consumer handlers try to claim the reserved `preactDevtoolsMessage` name.
+- Missing RPC transports do not throw immediately in browser code; the package logs a warning through the optional logger.
+
+# Terminology
+
+- Target: one inspected application window.
+- App bridge: the preload-side hook installation in the inspected window.
+- Devtools window: the standalone UI window.
+- Host: the Bun-side controller.
+- Session: the pairing between one target and one devtools window.
+
+# Non-Goals
+
+- Emulating Chrome DevTools or browser-extension panels.
+- Inspecting non-Preact applications.
+- Supporting sandboxed windows in v1.
+- Providing multi-target retargeting from one devtools window in v1.

package/examples/compose-existing-rpc.ts

@@ -0,0 +1,145 @@
+import type { BrowserWindow, RPCSchema } from 'electrobun/bun'
+import { Electroview } from 'electrobun/view'
+import {
+  composeAppWindowRPC,
+  composeDevtoolsWindowRPC,
+  createPreactDevtoolsHost,
+  type PreactDevtoolsHost,
+} from 'electrobun-preact-devtools/bun'
+import {
+  composeAppWindowViewRPC,
+  installPreactDevtoolsBridge,
+} from 'electrobun-preact-devtools/app-preload'
+import {
+  composeDevtoolsWindowViewRPC,
+  mountPreactDevtoolsWindow,
+} from 'electrobun-preact-devtools/devtools-view'
+import type {
+  WithPreactDevtoolsAppWindowRPC,
+  WithPreactDevtoolsDevtoolsWindowRPC,
+} from 'electrobun-preact-devtools/shared'
+
+export type AppWindowRPC = WithPreactDevtoolsAppWindowRPC<{
+  bun: RPCSchema<{
+    requests: {
+      openFile: {
+        params: { path: string }
+        response: string
+      }
+    }
+    messages: {
+      logAnalytics: { event: string }
+    }
+  }>
+  webview: RPCSchema<{
+    requests: {
+      getTheme: {
+        params: {}
+        response: 'light' | 'dark'
+      }
+    }
+    messages: {
+      themeChanged: { theme: 'light' | 'dark' }
+    }
+  }>
+}>
+
+export type DevtoolsWindowRPC = WithPreactDevtoolsDevtoolsWindowRPC<{
+  bun: RPCSchema<{
+    requests: {}
+    messages: {
+      trackWindowMetric: { metric: string; value: number }
+    }
+  }>
+  webview: RPCSchema<{
+    requests: {}
+    messages: {
+      setWindowChrome: { title: string }
+    }
+  }>
+}>
+
+declare const appWindow: BrowserWindow
+declare const devtoolsWindow: BrowserWindow
+declare const container: HTMLElement
+
+export const host = createPreactDevtoolsHost({
+  openWindow() {
+    return devtoolsWindow
+  },
+})
+
+export function registerExistingAppWindow(currentHost: PreactDevtoolsHost) {
+  currentHost.registerAppWindow({
+    targetId: 'main',
+    window: appWindow,
+  })
+}
+
+export function createAppWindowRPC(currentHost: PreactDevtoolsHost) {
+  return composeAppWindowRPC<AppWindowRPC>(currentHost, {
+    targetId: 'main',
+    handlers: {
+      requests: {
+        openFile: async ({ path }) => path,
+      },
+      messages: {
+        logAnalytics: ({ event }) => {
+          console.log('analytics', event)
+        },
+      },
+    },
+  })
+}
+
+export const appWindowViewRPC = composeAppWindowViewRPC<AppWindowRPC>({
+  handlers: {
+    requests: {
+      getTheme: () => 'dark',
+    },
+    messages: {
+      themeChanged: ({ theme }) => {
+        document.documentElement.dataset.theme = theme
+      },
+    },
+  },
+})
+
+export function installComposedBridge() {
+  const electroview = new Electroview({
+    rpc: appWindowViewRPC,
+  })
+
+  return installPreactDevtoolsBridge({ electroview })
+}
+
+export function createStandaloneDevtoolsRPC(currentHost: PreactDevtoolsHost) {
+  return composeDevtoolsWindowRPC<DevtoolsWindowRPC>(currentHost, {
+    targetId: 'main',
+    handlers: {
+      messages: {
+        trackWindowMetric: ({ metric, value }) => {
+          console.log(metric, value)
+        },
+      },
+    },
+  })
+}
+
+export const devtoolsWindowViewRPC = composeDevtoolsWindowViewRPC<DevtoolsWindowRPC>({
+  handlers: {
+    messages: {
+      setWindowChrome: ({ title }) => {
+        document.title = title
+      },
+    },
+  },
+})
+
+export function mountComposedDevtools() {
+  const electroview = new Electroview({
+    rpc: devtoolsWindowViewRPC,
+  })
+
+  return mountPreactDevtoolsWindow({ container, electroview })
+}

package/examples/minimal.ts

@@ -0,0 +1,52 @@
+import { BrowserWindow } from 'electrobun/bun'
+import { Electroview } from 'electrobun/view'
+import { createPreactDevtoolsHost } from 'electrobun-preact-devtools/bun'
+import {
+  composeAppWindowViewRPC,
+  installPreactDevtoolsBridge,
+} from 'electrobun-preact-devtools/app-preload'
+import {
+  composeDevtoolsWindowViewRPC,
+  mountPreactDevtoolsWindow,
+} from 'electrobun-preact-devtools/devtools-view'
+
+export const host = createPreactDevtoolsHost({
+  openWindow({ rpc }) {
+    return new BrowserWindow({
+      title: 'Preact Devtools',
+      url: 'views://preact-devtools/index.html',
+      rpc,
+    })
+  },
+})
+
+export const appWindow = new BrowserWindow({
+  title: 'My App',
+  url: 'views://app/index.html',
+  preload: 'views://app/preload.js',
+  rpc: host.createAppWindowRPC({ targetId: 'main' }),
+})
+
+host.registerAppWindow({
+  targetId: 'main',
+  window: appWindow,
+})
+
+export function installBridgeInAppPreload() {
+  const electroview = new Electroview({
+    rpc: composeAppWindowViewRPC({}),
+  })
+
+  return installPreactDevtoolsBridge({ electroview })
+}
+
+export function mountStandaloneDevtools(container: HTMLElement) {
+  const electroview = new Electroview({
+    rpc: composeDevtoolsWindowViewRPC({}),
+  })
+
+  return mountPreactDevtoolsWindow({
+    container,
+    electroview,
+  })
+}

package/examples/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["./"],
+  "exclude": ["../src/vendor/preact-devtools"],
+  "compilerOptions": {
+    "baseUrl": "..",
+    "ignoreDeprecations": "6.0",
+    "paths": {
+      "electrobun-preact-devtools": ["./dist/index.d.mts"],
+      "electrobun-preact-devtools/shared": ["./dist/index.d.mts"],
+      "electrobun-preact-devtools/bun": ["./dist/bun.d.mts"],
+      "electrobun-preact-devtools/app-preload": ["./dist/app-preload.d.mts"],
+      "electrobun-preact-devtools/devtools-view": ["./dist/devtools-view.d.mts"]
+    }
+  }
+}

package/package.json

@@ -1,13 +1,78 @@
 {
   "name": "electrobun-preact-devtools",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.1.0",
   "license": "MIT",
-  "type": "commonjs"
-}
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleclarson/electrobun-preact-devtools.git"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./shared": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.mts",
+      "default": "./dist/bun.mjs"
+    },
+    "./app-preload": {
+      "types": "./dist/app-preload.d.mts",
+      "default": "./dist/app-preload.mjs"
+    },
+    "./devtools-view": {
+      "types": "./dist/devtools-view.d.mts",
+      "default": "./dist/devtools-view.mjs"
+    }
+  },
+  "dependencies": {
+    "@preact/signals": "2.9.0",
+    "@preact/signals-core": "^1.14.1",
+    "errorstacks": "2.4.1"
+  },
+  "devDependencies": {
+    "@tsdown/css": "^0.21.7",
+    "@types/node": "^25.6.0",
+    "@types/three": "^0.183.1",
+    "degit": "^2.8.4",
+    "electrobun": "1.16.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "preact": "10.29.1",
+    "tsdown": "^0.21.7",
+    "tsnapi": "^0.1.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "electrobun": "*",
+    "preact": "*"
+  },
+  "peerDependenciesMeta": {
+    "electrobun": {
+      "optional": false
+    },
+    "preact": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
+    "check:examples": "tsc -p examples --noEmit",
+    "test": "vitest"
+  }
+}

package/readme.md

@@ -1 +0,0 @@
-Coming soon...