@rainbow-robotics/muscat-plugin-kit 1.3.7 → 1.3.8-dev.1

package/README.md

@@ -115,7 +115,7 @@ muscat-pk build                # build dist/ and produce a distributable ZIP (sk
 | `muscat-pk storybook` | Browse the bundled rb-components Storybook |
 | `muscat-pk mcp` | Run an MCP server for AI coding agents (exposes rb-components/design-token/SDK docs) |
 | `muscat-pk update` | Update the kit + plugin-ui to the latest version |
-| `muscat-pk sdk <list\|update>` | Manage the Python `rainbow-rb-sdk` version |
+| `muscat-pk sdk <list\|update>` | Manage the `rainbow-rb-sdk` version — python: `requirements.txt`, C++ (cpp / ros2-cpp): `find_package(rb_sdk <ver> EXACT REQUIRED)` in `CMakeLists.txt` |
 | `muscat-pk version` | Print the installed CLI version (`-v` / `--version` also work) |
 | `muscat-pk completion [shell]` | Print a shell completion script (`bash` / `zsh` / `fish` / `powershell`; defaults to `$SHELL`) |
 
@@ -159,7 +159,7 @@ Move images to a machine with no internet:
 
 ```bash
 # on a machine with network
-docker save muscat-pk-python-dev muscat-pk-bridge | gzip > muscat-pk-images.tar.gz
+docker save muscat-pk-python-dev muscat-pk-runtime | gzip > muscat-pk-images.tar.gz
 
 # on the offline machine
 gunzip -c muscat-pk-images.tar.gz | docker load
@@ -198,12 +198,12 @@ The runtime monitor is strict on purpose: an undeclared port outside the plugin
 range is invisible to both the monitor and the robot's conflict check, so it
 would only surface as a collision after deployment.
 
-`muscat-pk`'s own dev plumbing (the Socket.IO bridge on `10000`, the Zenoh dev
+`muscat-pk`'s own dev plumbing (the plugin gateway on `10000`, the Zenoh dev
 peer port) is excluded from the check — it isn't the plugin's traffic.
 
-Declared ports are published to `127.0.0.1` on macOS and Windows so you can
-reach the backend from the host; native Linux uses host networking, where they
-already are.
+Under `muscat-pk dev` declared ports are published to `127.0.0.1` from the local
+Muscat container (the backend shares its network), so you can reach the backend
+from the host.
 
 ## Variables (pyfm)
 

package/cli/README.md

@@ -42,12 +42,12 @@ the backend**, whatever its number. Since a port outside `28600-28999` cannot be
 declared, it cannot be opened either — otherwise it would slip past both this
 check and the robot's install-time conflict check.
 
-The kit's own dev ports (Socket.IO bridge `10000`, the Zenoh dev peer port) are
+The kit's own dev ports (plugin gateway `10000`, the Zenoh dev peer port) are
 excluded from that check.
 
-Declared ports are published to `127.0.0.1` so the host can reach the backend on
-macOS/Windows; native Linux dev containers use host networking and already have
-them. A declared port that is already busy on the host is skipped with a warning.
+Under `muscat-pk dev` the backend shares the local Muscat container's network, so
+declared ports are published to `127.0.0.1` from that container. A declared port
+that is already busy on the host is skipped with a warning.
 
 Known robot/industrial/internal ports such as `502`, `4840`, `5170-5179`,
 `8000-8999`, `10000`, `2222`, `30004`, `34964`, `44818`, `50000-50005`,
@@ -226,7 +226,13 @@ inside plugins.
 - **`build`** bundles plugin code into ESM while externalizing
   `@rainbow-robotics/plugin-ui`, React, and ReactDOM.
 - **`dev:ui`** builds the plugin then serves it inside the bundled preview host
-  at `/plugin-dev` — a real mini-Muscat shell with no robot/back end.
+  at `/plugin-dev` — a real mini-Muscat shell. Without a robot IP it needs a Muscat
+  on `localhost:3000` for program preview: `dev` / `dev:ui` reuse any container that
+  already publishes `:10000` (`muscat`, `muscat-dev`, …) and otherwise start
+  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running only the
+  `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
+  It keeps running between runs (`docker rm -f muscat-pk-muscat` to stop);
+  `MUSCAT_PK_NO_LOCAL_MUSCAT=1` disables it.
 
 `create-muscat-plugin <dir>` is the bin alias for `muscat-pk new`.
 

package/cli/bin/muscat-pk.mjs

@@ -81,7 +81,7 @@ function formatHelp() {
     commandRow("new [dir]", `Scaffold a new plugin project ${color.dim("(prompts: author, email, description, type, front-package-manager)")}`),
     commandRow("type change", `Switch backend type ${color.dim("(python | cpp | ros2-python | ros2-cpp)")}`),
     commandRow("build", `Build + lock deps + vendor wheels + zip ${color.dim(`(${option("--no-zip")}: skip zip, ${option("--no-lock")}: skip python lock/vendor, ${option("--arch")} amd64|arm64|both)`)}`),
-    commandRow("dev", "Run Socket.IO bridge, dev:ui, and dev:back together"),
+    commandRow("dev", "Run a local Muscat runtime, dev:ui, and dev:back together"),
     commandRow("dev:ui", `Preview the plugin in a mini-Muscat ${color.dim("(preview-host)")}`),
     commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
     commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),

package/cli/bundle-templates.mjs

@@ -19,8 +19,6 @@ function walk(baseDir, prefix) {
 }
 walk(resolve(root, "templates") + "/", "");
 walk(resolve(root, "docker") + "/", "docker/");
-// Dockerfile.bridge 의 COPY 대상
-files["src/socketBridge.mjs"] = readFileSync(resolve(root, "src/socketBridge.mjs"), "base64");
 
 const { version } = JSON.parse(readFileSync(resolve(root, "../package.json"), "utf8"));
 

package/cli/docker/Dockerfile.cpp

@@ -10,34 +10,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       cmake \
     && rm -rf /var/lib/apt/lists/*
 
-# Rainbow Robotics C++ SDK for find_package(rb_sdk).
-# Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
-ARG RB_SDK_VERSION=0.1.7
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). muscat-pk passes the version pinned in the
+# project's CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); without a pin (ROS 2 rclpy, `muscat-pk mcp`
+# outside a project) the newest SDK is installed. Runtime and -dev are installed together at one version.
+ARG RB_SDK_VERSION=
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
     && install -d /etc/apt/keyrings \
     && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
     && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
-    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends "rainbow-rb-sdk${RB_SDK_VERSION:+=$RB_SDK_VERSION}" "rainbow-rb-sdk-dev${RB_SDK_VERSION:+=$RB_SDK_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
-# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
-# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
-ARG MEDIAMTX_VERSION=1.12.3
-RUN set -eux; \
-    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
-    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
-    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
-      | tar -xz -C /usr/local/bin mediamtx; \
-    mkdir -p /etc/mediamtx; \
-    printf '%s\n' \
-      'logLevel: warn' \
-      'rtsp: yes' 'rtspAddress: :8554' \
-      'webrtc: yes' 'webrtcAddress: :8889' \
-      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
-      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
-      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
-      'paths:' '  all_others:' '    source: publisher' \
-      > /etc/mediamtx/mediamtx.yml
 
 WORKDIR /plugin
 

package/cli/docker/Dockerfile.dev

@@ -9,34 +9,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3-colcon-common-extensions \
     && rm -rf /var/lib/apt/lists/*
 
-# Rainbow Robotics C++ SDK for find_package(rb_sdk).
-# Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
-ARG RB_SDK_VERSION=0.1.7
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). muscat-pk passes the version pinned in the
+# project's CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); without a pin (ROS 2 rclpy, `muscat-pk mcp`
+# outside a project) the newest SDK is installed. Runtime and -dev are installed together at one version.
+ARG RB_SDK_VERSION=
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
     && install -d /etc/apt/keyrings \
     && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
     && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
-    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends "rainbow-rb-sdk${RB_SDK_VERSION:+=$RB_SDK_VERSION}" "rainbow-rb-sdk-dev${RB_SDK_VERSION:+=$RB_SDK_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
-# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
-# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
-ARG MEDIAMTX_VERSION=1.12.3
-RUN set -eux; \
-    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
-    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
-    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
-      | tar -xz -C /usr/local/bin mediamtx; \
-    mkdir -p /etc/mediamtx; \
-    printf '%s\n' \
-      'logLevel: warn' \
-      'rtsp: yes' 'rtspAddress: :8554' \
-      'webrtc: yes' 'webrtcAddress: :8889' \
-      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
-      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
-      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
-      'paths:' '  all_others:' '    source: publisher' \
-      > /etc/mediamtx/mediamtx.yml
 
 # `docker exec` skips /ros_entrypoint.sh — source ROS for the login shells dev:back runs.
 RUN echo ". /opt/ros/${ROS_DISTRO}/setup.sh" > /etc/profile.d/ros.sh

package/cli/docker/Dockerfile.python

@@ -15,24 +15,6 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # cpp SDK shared lib must be present for the python module to load. Install the
 # rainbow cpp SDK (apt, pinned to the robot's version) here once it exists.
 
-# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
-# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
-ARG MEDIAMTX_VERSION=1.12.3
-RUN set -eux; \
-    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
-    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
-    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
-      | tar -xz -C /usr/local/bin mediamtx; \
-    mkdir -p /etc/mediamtx; \
-    printf '%s\n' \
-      'logLevel: warn' \
-      'rtsp: yes' 'rtspAddress: :8554' \
-      'webrtc: yes' 'webrtcAddress: :8889' \
-      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
-      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
-      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
-      'paths:' '  all_others:' '    source: publisher' \
-      > /etc/mediamtx/mediamtx.yml
 
 WORKDIR /plugin
 

package/cli/src/build.mjs

@@ -353,7 +353,7 @@ function packZip(pluginRoot) {
 
 /**
  * Ask which target arch(es) to build for.
- * Non-TTY (CI): auto-selects current machine arch.
+ * Non-TTY (CI): both, same as the prompt default.
  * @returns {Promise<string[]>} e.g. ['amd64'] | ['arm64'] | ['amd64','arm64']
  */
 async function promptArch(args = []) {
@@ -364,11 +364,11 @@ async function promptArch(args = []) {
     if (archFlag === "arm64" || archFlag === "aarch64") return ["arm64"];
     throw new Error(`unknown --arch value '${archFlag}' (valid: amd64, arm64, both)`);
   }
+  // Same default as the prompt: the target is the robot, not this machine
+  // (node's os.arch() is x64 under Rosetta on an arm64 Mac anyway).
   if (!process.stdin.isTTY) {
-    const { arch } = await import("node:os");
-    const machine = arch() === "arm64" ? "arm64" : "amd64";
-    log.info(`arch auto-selected (non-TTY): ${machine}`);
-    return [machine];
+    log.info("arch auto-selected (non-TTY): both");
+    return ["amd64", "arm64"];
   }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   process.stdout.write(

package/cli/src/completion.mjs

@@ -19,7 +19,7 @@ const COMMANDS = [
   ["mcp", "Start an MCP server (stdio)"],
   ["update", "Update muscat-pk and plugin-ui"],
   ["uninstall", "Remove the installed muscat-pk CLI"],
-  ["sdk", "Manage the python rainbow-rb-sdk version"],
+  ["sdk", "Manage the rainbow-rb-sdk version (python: requirements.txt, C++: CMakeLists.txt)"],
   ["version", "Print the installed muscat-pk version"],
   ["completion", "Print a shell completion script"],
   ["help", "Show help"],

package/cli/src/cpp.mjs

@@ -3,7 +3,8 @@
 // Used by dev:back (interactive dev loop) and build (export the binary into the ZIP).
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { syncCppIde } from "./cppIde.mjs";
 
 export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
 
@@ -14,9 +15,16 @@ export function assertDockerReady() {
 }
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
-export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
+export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null, root = pluginRootOrNull() } = {}) {
+  await buildImage(image, platform, root);
+  // Dev images feed the editor's SDK headers: the native one (dev) or the host-arch one (build).
+  const hostArch = process.arch === "arm64" ? "arm64" : "amd64";
+  if (root && (image === CPP_DEV_IMAGE || image === `${CPP_DEV_IMAGE}-${hostArch}`)) syncCppIde(root, image);
+}
+
+async function buildImage(image, platform, root) {
   const dockerfile = await resolveDockerfile("Dockerfile.cpp");
-  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const sdkVer = cppSdkVersion(root);
   const key = imageKey(dockerfile, sdkVer ?? "");
   if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);

package/cli/src/cppIde.mjs

@@ -0,0 +1,75 @@
+// Editor (IntelliSense) support for C++ backends. The rb_sdk headers only exist inside the dev image,
+// so a host editor flags every SDK name. Copy them to .muscat-dev/sysroot and point
+// .vscode/c_cpp_properties.json at them, using the include dirs / defines rb_sdk's CMake target exports.
+// The build never reads these copies — it runs in the image.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { cppSdkFiles, log } from "./util.mjs";
+
+const SYSROOT = ".muscat-dev/sysroot";
+const CONFIG_NAME = "Muscat";
+const COPY = ["/usr/include/rainbow", "/usr/include/eigen3", "/usr/lib/cmake/rb_sdk/rb_sdkTargets.cmake"];
+
+function imageId(image) {
+  const r = spawnSync("docker", ["image", "inspect", "-f", "{{.Id}}", image], { encoding: "utf8" });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/** Copy the SDK headers out of `image` (once per image build) and write the VS Code C/C++ config. */
+export function syncCppIde(root, image) {
+  if (!cppSdkFiles(root).length) return;
+  const id = imageId(image);
+  if (!id) return;
+  const sysroot = resolve(root, SYSROOT);
+  const stamp = resolve(sysroot, ".image-id");
+  if (!existsSync(stamp) || readFileSync(stamp, "utf8") !== id) {
+    rmSync(sysroot, { recursive: true, force: true });
+    const create = spawnSync("docker", ["create", image], { encoding: "utf8" });
+    if (create.status !== 0) return log.warn("could not copy SDK headers for the editor (docker create failed).");
+    const container = create.stdout.trim();
+    try {
+      for (const src of COPY) {
+        const dest = resolve(sysroot, src.slice(1));
+        mkdirSync(resolve(dest, ".."), { recursive: true });
+        spawnSync("docker", ["cp", `${container}:${src}`, dest], { stdio: "ignore" });
+      }
+    } finally {
+      spawnSync("docker", ["rm", container], { stdio: "ignore" });
+    }
+    writeFileSync(stamp, id);
+    log.step(`SDK headers for the editor → ${SYSROOT}`);
+  }
+  writeCppProperties(root, readTarget(sysroot));
+}
+
+// INTERFACE_INCLUDE_DIRECTORIES / INTERFACE_COMPILE_DEFINITIONS of rb_sdk::rb_sdk, mapped into the sysroot.
+function readTarget(sysroot) {
+  const file = resolve(sysroot, "usr/lib/cmake/rb_sdk/rb_sdkTargets.cmake");
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const list = (key) => (text.match(new RegExp(`${key} "([^"]*)"`))?.[1] ?? "").split(";").filter(Boolean);
+  const prefix = `\${workspaceFolder}/${SYSROOT}/usr`;
+  const includes = list("INTERFACE_INCLUDE_DIRECTORIES").map((d) => d.replace("${_IMPORT_PREFIX}", prefix));
+  return {
+    includePath: [...(includes.length ? includes : [`${prefix}/include`]), `${prefix}/include/eigen3`],
+    defines: list("INTERFACE_COMPILE_DEFINITIONS"),
+  };
+}
+
+// Keeps other configurations; ours is replaced in place or put first so VS Code picks it by default.
+function writeCppProperties(root, { includePath, defines }) {
+  const file = resolve(root, ".vscode", "c_cpp_properties.json");
+  let props = { configurations: [], version: 4 };
+  if (existsSync(file)) {
+    try {
+      props = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      return log.warn(".vscode/c_cpp_properties.json is not plain JSON — add the SDK include paths yourself.");
+    }
+  }
+  const config = { name: CONFIG_NAME, includePath: ["${workspaceFolder}/**", ...includePath], defines, cppStandard: "c++20" };
+  const configs = (props.configurations ?? []).filter((c) => c.name !== CONFIG_NAME);
+  props.configurations = [config, ...configs];
+  mkdirSync(resolve(root, ".vscode"), { recursive: true });
+  writeFileSync(file, JSON.stringify(props, null, 2) + "\n");
+}

package/cli/src/dev.mjs

@@ -1,4 +1,4 @@
-// muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
+// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), dev:ui, and dev:back together.
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { connect as netConnect } from "node:net";
@@ -6,7 +6,7 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
-import { localMuscatContainer, startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse } from "./muscatLocal.mjs";
 import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
@@ -18,7 +18,7 @@ import {
   promptRobotConnection,
   venvPython,
 } from "./util.mjs";
-import { ensureRemoteZenohEnv, isRemoteRobot, isWsl, usesHostNetwork } from "./zenohDev.mjs";
+import { ensureRemoteZenohEnv, isRemoteRobot, isWsl } from "./zenohDev.mjs";
 
 const HOST_AGENT_PATH = fileURLToPath(new URL("./host_agent.py", import.meta.url));
 const canAutoStartHostAgent = () => process.platform === "darwin" || isWsl();
@@ -99,7 +99,7 @@ async function maybeStartHostAgent(root, { robotIp, robotToken }) {
   }
 
   // advertiseHost (not host.docker.internal): a Docker Desktop container run
-  // under `dev` may share the bridge container's netns (--network container:),
+  // under `dev` shares the local Muscat container's netns (--network container:),
   // which has no host-gateway alias configured — the host's real LAN IP
   // always resolves regardless of netns mode.
   const proxyEndpoint = `${advertiseHost}:${proxyPort}`;
@@ -126,32 +126,26 @@ export async function runDev(args = []) {
   const hostAgent = await maybeStartHostAgent(root, { robotIp, robotToken });
   const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT || "";
   // No proxy (Linux, disabled, ...): fall back to the container reverse-dialing
-  // the robot itself — startBridge() then publishes the zenoh port for it.
+  // the robot itself — the local Muscat then publishes the zenoh port for it.
   if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
 
-  log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
-  const bridgeStarted = await startBridge({
-    zenohPort: remoteRobot && !proxyEndpoint && !usesHostNetwork()
-      ? Number(process.env.MUSCAT_ZENOH_PORT)
-      : null,
-    // Linux uses --network host, so the ports are already on the host.
-    pluginPorts: usesHostNetwork() ? [] : portRanges,
-  });
-
-  const muscat = bridgeStarted ? null : localMuscatContainer();
+  // Robot or not, the local Muscat runtime is the gateway (:10000), MediaMTX and common; the
+  // backend joins its netns, so the plugin's declared ports are published from it too.
+  log.step("starting local Muscat (Docker) + dev:ui + dev:back");
+  const muscat = await ensureLocalMuscat({
+    pluginPorts: portRanges,
+    zenohPort: remoteRobot && !proxyEndpoint ? Number(process.env.MUSCAT_ZENOH_PORT) || null : null,
+  }).catch((e) => { log.warn(`local Muscat: ${e.message}`); return null; });
   if (muscat) {
-    log.step(`local Muscat container '${muscat}' owns :${BRIDGE_PORT} — backend joins its network (gateway, MediaMTX)`);
+    log.step(`local Muscat container '${muscat}' owns :${GATEWAY_PORT} — backend joins its network (gateway, MediaMTX)`);
     process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
-  } else if (!bridgeStarted) {
-    log.warn(`port ${BRIDGE_PORT} is already in use — can't start Socket.IO bridge.`);
-    const answer = await prompt("  Proceed without Socket.IO bridge? [y/N]: ");
-    if (answer.toLowerCase() !== "y") return;
-    log.info("proceeding without bridge — backend will skip network sharing.");
+  } else if (await isPortInUse(GATEWAY_PORT)) {
+    // e.g. developing on the robot PC: its Muscat already serves the gateway; the backend reaches it via the host.
+    log.step(`:${GATEWAY_PORT} is already served (Muscat on this machine) — using it`);
   } else {
-    // Tell dev:back which bridge container to share a netns with, so the backend
-    // reaches the bridge at localhost:10000 (no host.docker.internal).
-    process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
-    if (bridgeStarted.media) process.env.MUSCAT_PK_MEDIA = "1";
+    log.warn(`no local Muscat on :${GATEWAY_PORT} — the plugin UI cannot reach the backend.`);
+    const answer = await prompt("  Proceed anyway? [y/N]: ");
+    if (answer.toLowerCase() !== "y") return;
   }
 
   process.env.MUSCAT_PK_MANAGED_DEV = "1";
@@ -159,7 +153,6 @@ export async function runDev(args = []) {
   const cleanup = () => {
     if (hostAgent && hostAgent.exitCode === null) hostAgent.kill();
     stopDevBackContainers();
-    if (bridgeStarted) stopBridge();
   };
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);

package/cli/src/devBack.mjs

@@ -2,7 +2,7 @@
 // Every backend runs in a warm Docker container that matches the robot
 // (Ubuntu 24.04), so dev behaves like production.
 //   python : Python 3.12 container, pip install, run main.py with watchfiles
-//            hot-reload. Shares the bridge container's netns (localhost:10000).
+//            hot-reload. Shares the local Muscat container's netns (localhost:10000).
 //   cpp    : Ubuntu + cmake container, build cpp/, run the binary, rebuild +
 //            restart on source changes.
 //   ros2   : Jazzy + Python 3.12 container, colcon build, run the node, restart
@@ -12,7 +12,8 @@ import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:
 import { isIP } from "node:net";
 import { dirname, resolve } from "node:path";
 import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
-import { ensureRemoteZenohEnv, usesHostNetwork } from "./zenohDev.mjs";
+import { ensureRemoteZenohEnv, isRemoteRobot, usesHostNetwork } from "./zenohDev.mjs";
+import { localMuscatContainer } from "./muscatLocal.mjs";
 import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
@@ -53,15 +54,22 @@ export function stopDevBackContainers() {
   }
 }
 
-// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-dev): join its
-// netns so the gateway and MediaMTX resolve like on the robot. Under `dev`: the bridge's
-// netns. Standalone dev:back: its own netns, gateway via the host.
+// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-pk-muscat, muscat-dev):
+// join its netns so the gateway and MediaMTX resolve like on the robot. Otherwise its own
+// netns, gateway via the host.
+// IS_DEV Muscat (muscat-dev): common is a zenoh-router client and opens no 7447 listener,
+// so the plugin must join the router too or `execute` queries never reach it.
+function muscatZenohEnv(container) {
+  const r = spawnSync("docker", ["inspect", "-f", "{{range .Config.Env}}{{println .}}{{end}}", container], { encoding: "utf8" });
+  return /^IS_DEV=(true|1)$/im.test(r.stdout || "")
+    ? ["-e", "ZENOH_PEER_CONNECT_ENDPOINTS=tcp/zenoh-router:7447"]
+    : [];
+}
+
 function backendNetwork(portRanges) {
   const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
-  if (muscat) return { run: ["--network", `container:${muscat}`], env: [], shared: true };
+  if (muscat) return { run: ["--network", `container:${muscat}`], env: muscatZenohEnv(muscat), shared: true };
   if (usesHostNetwork()) return { run: ["--network", "host"], env: [], shared: true };
-  const bridge = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
-  if (bridge) return { run: ["--network", `container:${bridge}`], env: [], shared: true };
   return {
     // host.docker.internal is automatic on Docker Desktop; this makes it resolve on Linux too.
     run: [...publishPortFlags(portRanges), "--add-host", "host.docker.internal:host-gateway"],
@@ -107,13 +115,6 @@ async function serveRosPeers(root, pluginId, restart) {
   });
 }
 
-// Our own MediaMTX, only when `dev` found its ports free (a local Muscat brings its own).
-function startMediaServer(container) {
-  if (process.env.MUSCAT_PK_MEDIA !== "1") return;
-  spawnSync("docker", ["exec", "-d", container, "mediamtx", "/etc/mediamtx/mediamtx.yml"], { stdio: "ignore" });
-  log.step("MediaMTX: publish rtsp://127.0.0.1:8554/<path> · play http://localhost:8889/<path>");
-}
-
 // ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
 // `muscat-pk new` already creates this up front (see new.mjs); this just
 // refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
@@ -134,8 +135,8 @@ function syncIdeVenv(root) {
 
 // ── python ────────────────────────────────────────────────────────────────────
 // Runs in a warm Ubuntu 24.04 + Python 3.12 container (matches the robot).
-// Under `muscat-pk dev`, it shares the bridge container's netns, so the SDK
-// reaches the Socket.IO bridge at the default localhost:10000.
+// Under `muscat-pk dev`, it shares the local Muscat container's netns, so the SDK
+// reaches the plugin gateway at the default localhost:10000.
 async function runPython(root, portRanges) {
   // Independent of Docker readiness — must still happen if Docker isn't
   // installed/running, since that's exactly when local IDE tooling matters most.
@@ -154,7 +155,7 @@ async function runPython(root, portRanges) {
   // Zenoh mesh, so it speaks a byte protocol to the host-side proxy instead.
   const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT ?? "";
   // Native Linux (not WSL, not Docker Desktop) has real host networking: the
-  // container shares the host's network stack, so it reaches the bridge at
+  // container shares the host's network stack, so it reaches the gateway at
   // localhost:10000 and the robot's Zenoh router / reverse-dial path directly
   // — no netns sharing, port publishing, host.docker.internal, or byte-proxy.
   const net = backendNetwork(portRanges);
@@ -195,7 +196,6 @@ async function runPython(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort] });
 
   log.step("pip install requirements + watchfiles (in container)…");
@@ -413,7 +413,7 @@ runpy.run_path("/plugin/py/main.py", run_name="__main__")
 PY`]);
 
   if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
-  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/bridge access)");
+  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/gateway access)");
   if (proxyEndpoint) log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
   else if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
   log.step("watchfiles → py/main.py (reload on any .py change in py/)");
@@ -493,7 +493,6 @@ async function runRos2(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
@@ -586,7 +585,6 @@ async function runCpp(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   const build = () => {
@@ -656,6 +654,15 @@ export async function runDevBack(args = []) {
   // Byte-proxy mode (a host-side host_agent set MUSCAT_PROXY_ENDPOINT) makes
   // the container speak the proxy protocol instead, so it needs no reverse-dial.
   if (!process.env.MUSCAT_PROXY_ENDPOINT) await ensureRemoteZenohEnv(robotIp, { log });
+  // Standalone against a local Muscat (muscat-dev, …): join its netns like `dev` does,
+  // otherwise zenoh reaches nothing and `execute` never arrives.
+  if (!process.env.MUSCAT_PK_MUSCAT_CONTAINER && !isRemoteRobot(robotIp)) {
+    const muscat = localMuscatContainer();
+    if (muscat) {
+      log.step(`local Muscat container '${muscat}' found — backend joins its network`);
+      process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
+    }
+  }
   const type = manifestRuntime(root);
   if (type === "ros2") return await runRos2(root, portRanges);
   if (type === "cpp") return await runCpp(root, portRanges);

package/cli/src/devUi.mjs

@@ -7,6 +7,8 @@ import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log, parseArgs, prompt } from "./util.mjs";
+import { ensureLocalMuscat } from "./muscatLocal.mjs";
+import { isRemoteRobot } from "./zenohDev.mjs";
 
 
 const DEV_PLUGIN_PORT = 4181;
@@ -44,7 +46,9 @@ function findPreviewHostRoot() {
   try {
     const req = createRequire(import.meta.url);
     return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
-  } catch {}
+  } catch {
+    console.log("Try the sibling and cached package locations below.")
+  }
 
   const sibling = resolve(kitRoot, "../preview-host");
   if (existsSync(resolve(sibling, "package.json"))) return sibling;
@@ -137,6 +141,7 @@ function waitForPluginDevPort(readyFile, proc, timeoutMs = 15_000) {
           const { port } = JSON.parse(readFileSync(readyFile, "utf8"));
           if (Number.isInteger(port)) return res(port);
         } catch {
+          console.log("Keep polling until the ready file contains valid JSON.")
         }
       }
       if (Date.now() - start > timeoutMs)
@@ -160,6 +165,10 @@ export async function runDevUi(args = []) {
     log.warn(`preview-host port ${requestedPort} is in use — using ${port} instead.`);
 
   if (robotIp) log.info(`MUSCAT_API_ORIGIN → http://${robotIp}:*`);
+  // No robot: the bundle talks to localhost:3000, so put a Muscat there (`dev` already did).
+  if (!isRemoteRobot(robotIp) && process.env.MUSCAT_PK_MANAGED_DEV !== "1") {
+    await ensureLocalMuscat().catch((e) => log.warn(`local Muscat: ${e.message}`));
+  }
 
   watchAssets(pluginRoot, outDir);