Address PR 1478 review comments

Author: minggangw

electron_demo/manipulator/README.md

@@ -282,10 +282,10 @@ manipulator/
 
 ### Key Dependencies
 
-- **electron**: `^31.7.7` - Desktop application framework
-- **rclnodejs**: `^1.5.1` - ROS2 JavaScript client library (latest compatible)
-- **@electron/rebuild**: `^3.7.2` - Native module rebuilding tool
-- **three.js**: `r128` - 3D graphics library (loaded via CDN)
+- **electron**: `^40.1.0` - Desktop application framework
+- **rclnodejs**: `^1.8.1` - ROS2 JavaScript client library
+- **@electron/rebuild**: `^4.0.3` - Native module rebuilding tool
+- **three**: `^0.182.0` - 3D graphics library
 
 ### Debugging
 
@@ -305,10 +305,11 @@ manipulator/
    npm start
    ```
 
-2. **Build errors with latest Electron**
-   - This demo uses Electron 31.7.7 for rclnodejs compatibility
-   - Electron 38+ requires C++20, which rclnodejs doesn't support yet
-   - The current versions are tested and stable
+2. **Build errors with Electron**
+
+- This demo currently uses Electron 40.1.0
+- If you change Electron or other native-module dependencies, rerun `npm run rebuild`
+- The versions recorded in `package.json` and `package-lock.json` are the tested baseline for this demo
 
 3. **No ROS2 messages received**
    - Check if ROS2 daemon is running: `ros2 daemon start`

electron_demo/turtle_tf2/README.md

@@ -51,7 +51,7 @@ The turtle_tf2 demo showcases:
 ### System Requirements
 
 - **ROS2**: Humble, Iron, or Rolling distribution
-- **Node.js**: Version 18 or higher (for compatibility with latest Electron)
+- **Node.js**: Version 20.20.2 or higher
 - **turtlesim**: ROS2 turtle simulation package
 - **Electron**: For desktop application framework
 
@@ -317,46 +317,39 @@ You can observe the following behavior by:
 ### Common Issues
 
 1. **"Cannot connect to ROS2" or "librcl.so: cannot open shared object file"**
-
    - Ensure ROS2 is sourced: `source /opt/ros/$ROS_DISTRO/setup.bash`
    - **Critical**: Source ROS2 in the SAME terminal where you run `npm start`
    - Check if ROS2 daemon is running: `ros2 daemon status`
    - Verify ROS2 installation: `ros2 --version`
 
 2. **"Turtlesim not responding" or "Failed to spawn turtle2"**
-
    - Verify turtlesim is running: `ros2 run turtlesim turtlesim_node`
    - Check available topics: `ros2 topic list`
    - Ensure spawn service is available: `ros2 service list | grep spawn`
    - Try restarting turtlesim_node if spawn calls fail
 
 3. **"No transforms detected"**
-
    - Ensure demo is started: Click "Start Demo" button
    - Check TF2 tree: `ros2 run tf2_tools view_frames`
 
 4. **"Dynamic frame not visible when toggling"**
-
    - **Check if the demo is started**: Click "Start Demo" button first to initialize all broadcasters
    - **Look for an orange sphere near coordinates (2,3)**: The dynamic frame appears as an orange sphere orbiting around the red static frame
    - **Wait for circular motion**: The dynamic frame moves in a 2-unit radius circle, taking about 6 seconds for a full rotation
    - **The orange sphere is now bigger**: The dynamic frame has been made 3x larger for better visibility
    - **Check the transform list**: The dynamic frame should appear in the left panel's transform list with changing coordinates around (2±2, 3±2, 0)
 
 5. **"3D visualization not loading"**
-
    - Check browser console for WebGL errors
    - Ensure hardware acceleration is enabled
    - Try restarting the Electron application
 
 6. **"electron: not found" or native module errors**
-
    - Make sure you ran `npm run rebuild` after `npm install`
-   - Ensure Node.js version is compatible (18 or higher)
+   - Ensure Node.js version is compatible (20.20.2 or higher)
    - Try deleting `node_modules` and running `npm install && npm run rebuild` again
 
 7. **"THREE is not defined" or script loading errors**
-
    - Ensure Three.js is properly installed: `npm install three@0.155.0`
    - Check that `node_modules/three/build/three.min.js` exists
    - If issues persist, try reinstalling: `rm -rf node_modules && npm install && npm run rebuild`

lib/native_loader.js

@@ -20,6 +20,10 @@ const { execSync } = require('child_process');
 const { NativeError } = require('./errors.js');
 const bindings = require('bindings');
 const debug = require('debug')('rclnodejs');
+const {
+  detectPrebuildRuntime,
+  getTaggedPrebuildFilename,
+} = require('./prebuilds');
 const { detectUbuntuCodename } = require('./utils');
 
 let nativeModule = null;
@@ -35,6 +39,7 @@ function customFallbackLoader() {
 
   const rosDistro = process.env.ROS_DISTRO;
   const arch = process.arch;
+  const runtime = detectPrebuildRuntime();
   const ubuntuCodename = detectUbuntuCodename();
 
   // Require all three components for exact match
@@ -58,16 +63,22 @@ function customFallbackLoader() {
   }
 
   try {
-    // Look for exact match binary: {ros_distro}-{ubuntu_codename}-{arch}-rclnodejs.node
-    const exactMatchFilename = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
-    const exactMatchPath = path.join(prebuildDir, exactMatchFilename);
-
-    if (fs.existsSync(exactMatchPath)) {
-      debug(`Found exact match binary: ${exactMatchFilename}`);
-      return require(exactMatchPath);
+    const candidate = getTaggedPrebuildFilename({
+      rosDistro,
+      ubuntuCodename,
+      arch,
+      runtime,
+    });
+    const candidatePath = path.join(prebuildDir, candidate);
+
+    if (fs.existsSync(candidatePath)) {
+      debug(`Found ${runtime} prebuilt binary: ${candidate}`);
+      return require(candidatePath);
     }
 
-    debug(`No exact match found for: ${exactMatchFilename}`);
+    debug(
+      `No matching ${runtime} prebuilt binary found for ${rosDistro}-${ubuntuCodename}-${arch}`
+    );
     return null;
   } catch (e) {
     debug('Error in simplified prebuilt loader:', e.message);
@@ -110,10 +121,11 @@ function loadNativeAddon() {
   }
 
   const rosDistro = process.env.ROS_DISTRO;
+  const runtime = detectPrebuildRuntime();
   const ubuntuCodename = detectUbuntuCodename();
 
   debug(
-    `Platform: ${process.platform}, Arch: ${process.arch}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
+    `Platform: ${process.platform}, Arch: ${process.arch}, Runtime: ${runtime}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
   );
 
   // Prebuilt binaries are only supported on Linux (Ubuntu)

lib/prebuilds.js

@@ -0,0 +1,47 @@
+// Copyright (c) 2026, The Robot Web Tools Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const PREBUILD_PACKAGE_NAME = 'rclnodejs';
+const SUPPORTED_PREBUILD_RUNTIMES = new Set(['node', 'electron']);
+
+function detectPrebuildRuntime() {
+  if (process.env.npm_config_runtime === 'electron') {
+    return 'electron';
+  }
+
+  return process.versions.electron ? 'electron' : 'node';
+}
+
+function getTaggedPrebuildFilename({
+  rosDistro,
+  ubuntuCodename,
+  arch,
+  runtime,
+}) {
+  return `${rosDistro}-${ubuntuCodename}-${arch}-${runtime}-${PREBUILD_PACKAGE_NAME}.node`;
+}
+
+function getRuntimeFromGeneratedPrebuild(fileName) {
+  const runtime = fileName.split('.')[0];
+  return SUPPORTED_PREBUILD_RUNTIMES.has(runtime) ? runtime : null;
+}
+
+module.exports = {
+  detectPrebuildRuntime,
+  getRuntimeFromGeneratedPrebuild,
+  getTaggedPrebuildFilename,
+  PREBUILD_PACKAGE_NAME,
+};

package.json

@@ -34,7 +34,9 @@
     "format": "clang-format -i -style=file ./src/*.cpp ./src/*.h && npx --yes prettier --write \"{lib,rosidl_gen,rostsd_gen,rosidl_parser,types,example,test,scripts,benchmark,rostsd_gen}/**/*.{js,md,ts}\" ./*.{js,md,ts}",
     "prepare": "husky",
     "coverage": "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js",
-    "prebuild": "prebuildify --napi --strip --target 20.20.2 --target electron@23.0.0 && node scripts/tag_prebuilds.js"
+    "prebuild:node": "prebuildify --napi --strip --name node --target 20.20.2",
+    "prebuild:electron": "prebuildify --napi --strip --name electron --target electron@23.0.0",
+    "prebuild": "npm run prebuild:node && npm run prebuild:electron && node scripts/tag_prebuilds.js"
   },
   "bin": {
     "generate-ros-messages": "./scripts/generate_messages.js"

scripts/install.js

@@ -15,6 +15,10 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const {
+  detectPrebuildRuntime,
+  getTaggedPrebuildFilename,
+} = require('../lib/prebuilds');
 const { detectUbuntuCodename } = require('../lib/utils');
 
 function getRosDistro() {
@@ -24,6 +28,7 @@ function getRosDistro() {
 function checkPrebuiltBinary() {
   const platform = process.platform;
   const arch = process.arch;
+  const runtime = detectPrebuildRuntime();
 
   // Only Linux has prebuilt binaries
   if (platform !== 'linux') {
@@ -50,18 +55,24 @@ function checkPrebuiltBinary() {
     'prebuilds',
     `${platform}-${arch}`
   );
-  const expectedBinary = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
+  const expectedBinary = getTaggedPrebuildFilename({
+    rosDistro,
+    ubuntuCodename,
+    arch,
+    runtime,
+  });
+
   const binaryPath = path.join(prebuildDir, expectedBinary);
 
   if (fs.existsSync(binaryPath)) {
     console.log(`✓ Found prebuilt binary: ${expectedBinary}`);
-    console.log(`  Platform: ${platform}, Arch: ${arch}`);
+    console.log(`  Platform: ${platform}, Arch: ${arch}, Runtime: ${runtime}`);
     console.log(`  Ubuntu: ${ubuntuCodename}, ROS: ${rosDistro}`);
     return true;
   }
 
   console.log(
-    `✗ No prebuilt binary found for ${rosDistro}-${ubuntuCodename}-${arch}`
+    `✗ No ${runtime} prebuilt binary found for ${rosDistro}-${ubuntuCodename}-${arch}`
   );
 
   // List available binaries for debugging

scripts/tag_prebuilds.js

@@ -14,6 +14,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const {
+  getRuntimeFromGeneratedPrebuild,
+  getTaggedPrebuildFilename,
+} = require('../lib/prebuilds');
 const { detectUbuntuCodename } = require('../lib/utils');
 
 function tagPrebuilds() {
@@ -38,23 +42,36 @@ function tagPrebuilds() {
     return;
   }
 
-  const files = fs.readdirSync(prebuildDir).filter((f) => f.endsWith('.node'));
+  const files = fs
+    .readdirSync(prebuildDir)
+    .filter(
+      (file) => file.endsWith('.node') && getRuntimeFromGeneratedPrebuild(file)
+    );
 
   for (const file of files) {
     const filePath = path.join(prebuildDir, file);
+    const runtime = getRuntimeFromGeneratedPrebuild(file);
 
-    // Create tagged version with format: {ros_distro}-{linux-codename}-{cpu-arch}-rclnodejs.node
-    if (rosDistro && ubuntuCodename) {
-      const taggedName = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
+    // Create tagged version with format:
+    // {ros_distro}-{linux-codename}-{cpu-arch}-{runtime}-rclnodejs.node
+    if (rosDistro && ubuntuCodename && runtime) {
+      const taggedName = getTaggedPrebuildFilename({
+        rosDistro,
+        ubuntuCodename,
+        arch,
+        runtime,
+      });
       const taggedPath = path.join(prebuildDir, taggedName);
+
+      if (fs.existsSync(taggedPath)) {
+        fs.unlinkSync(taggedPath);
+      }
+
       fs.copyFileSync(filePath, taggedPath);
       console.log(`Created tagged binary: ${taggedName}`);
 
-      // Remove the original generic binary file if it's the basic rclnodejs.node
-      if (file === 'rclnodejs.node') {
-        fs.unlinkSync(filePath);
-        console.log(`Removed generic binary: ${file}`);
-      }
+      fs.unlinkSync(filePath);
+      console.log(`Removed generated binary: ${file}`);
     } else {
       console.log(
         `Skipping tagging for ${file} - missing ROS_DISTRO or Ubuntu codename`