@rainbow-robotics/muscat-plugin-kit 1.10.3-dev.2 → 1.10.3-dev.4

package/cli/README.md

@@ -11,7 +11,7 @@ muscat-pk new my-plugin
 
 ```bash
 muscat-pk new my-plugin [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun] [--yes]
-muscat-pk build       # ui/content.tsx -> dist/ (minified) + distributable ZIP (--no-zip to skip)
+muscat-pk build       # ui/content.tsx -> dist/ (minified) + distributable ZIP
 muscat-pk dev:ui      # preview the plugin in a mini-Muscat (preview-host)
 muscat-pk dev:back    # run the back end in a Docker container (python / cpp / ros2)
 muscat-pk dev         # dev:ui + dev:back
@@ -229,8 +229,10 @@ inside plugins.
   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
+  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running the
   `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
+  `dev --sim <model>` adds the services the model needs (log + manipulate / rby1), opens
+  common's Zenoh on the `muscat-pk` network, and starts simulators there (`cli/src/sim.mjs`).
   It keeps running between runs (`docker rm -f muscat-pk-muscat` to stop);
   `MUSCAT_PK_NO_LOCAL_MUSCAT=1` disables it.
 

package/cli/bin/muscat-pk.mjs

@@ -87,8 +87,8 @@ function formatHelp() {
     color.bold("Commands:"),
     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 a local Muscat runtime, dev:ui, and dev:back together"),
+    commandRow("build", `Build + lock deps + vendor wheels + zip ${color.dim(`(${option("--arch")} amd64|arm64|both)`)}`),
+    commandRow("dev", `Run a local Muscat runtime, dev:ui, and dev:back together ${color.dim(`(${option("--sim")} 500880|500920|RBY2|rby1-a|rby1-m|rby1-ub)`)}`),
     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")})`)}`),
@@ -96,6 +96,7 @@ function formatHelp() {
     commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")}, ${color.magenta("@rainbow-robotics/plugin-ui")} and ${color.magenta("@rainbow-robotics/preview-host")} ${color.dim(`(local-only if run from a project's local install; ${option("--global")} also updates the global CLI)`)}`),
     commandRow("uninstall", `Remove the installed ${color.cyan("muscat-pk")} CLI ${color.dim("(npm global or S3 binary)")}`),
     commandRow("sdk <list|update [version]>", "Manage the python rainbow-rb-sdk version"),
+    commandRow("sim list", `List the robot simulators for ${option("dev --sim")}`),
     commandRow("version", `Print the installed ${color.cyan("muscat-pk")} version`),
     commandRow("completion [shell]", `Print a shell completion script ${color.dim("(bash | zsh | fish | powershell)")}`),
     "",
@@ -137,6 +138,9 @@ async function main() {
         return await runUninstall(args);
       case "sdk":
         return await runSdk(args);
+      case "sim":
+        if (args[0] !== "list") throw new Error("usage: muscat-pk sim list");
+        return (await import("../src/sim.mjs")).runSimList();
       case "completion":
         return await runCompletion(args);
       case "version":

package/cli/src/build.mjs

@@ -1,6 +1,6 @@
 // muscat-pk build — bundle ui/content.tsx into dist/content.js, stage
 // manifest.json and assets/ for distribution, and zip dist/ into a
-// distributable ZIP (skip with --no-zip).
+// distributable ZIP.
 //
 // sandbox.html is generated by the CLI — plugin authors never manage it.
 // The import map always reflects the current plugin-ui entry set, so users
@@ -407,8 +407,6 @@ async function promptVersion(root) {
 }
 
 export async function runBuild(args) {
-  const noZip = args.includes("--no-zip");
-  const noLock = args.includes("--no-lock");
   const root = findPluginRoot();
   const rt = manifestRuntime(root);
 
@@ -424,19 +422,17 @@ export async function runBuild(args) {
   const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
 
   // python / rclpy: lock + wheel vendor in Ubuntu 24.04 container
-  if (!noLock) {
-    const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
-    const needsLock =
-      manifest.type === "python" ||
-      (manifest.type === "ros2" && manifest.rosClient === "rclpy");
-    if (needsLock) {
-      const { lockAndVendor } = await import("./python.mjs");
-      await lockAndVendor(pluginRoot, archs);
-    }
+  const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
+  const needsLock =
+    manifest.type === "python" ||
+    (manifest.type === "ros2" && manifest.rosClient === "rclpy");
+  if (needsLock) {
+    const { lockAndVendor } = await import("./python.mjs");
+    await lockAndVendor(pluginRoot, archs);
   }
 
   await exportRos2Build(root, archs);
   await exportCppBuild(root, distDir, archs);
   calcInstalledSize(pluginRoot);
-  if (!noZip) packZip(pluginRoot);
+  packZip(pluginRoot);
 }

package/cli/src/completion.mjs

@@ -20,6 +20,7 @@ const COMMANDS = [
   ["update", "Update muscat-pk and plugin-ui"],
   ["uninstall", "Remove the installed muscat-pk CLI"],
   ["sdk", "Manage the rainbow-rb-sdk version (python: requirements.txt, C++: CMakeLists.txt)"],
+  ["sim", "List the robot simulators for dev --sim"],
   ["version", "Print the installed muscat-pk version"],
   ["completion", "Print a shell completion script"],
   ["help", "Show help"],
@@ -28,6 +29,7 @@ const COMMANDS = [
 const SUBCOMMANDS = {
   type: ["change"],
   sdk: ["list", "update"],
+  sim: ["list"],
   completion: ["bash", "zsh", "fish", "powershell"],
 };
 

package/cli/src/dev.mjs

@@ -1,12 +1,14 @@
-// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), dev:ui, and dev:back together.
-import { spawn } from "node:child_process";
+// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), robot simulators (--sim),
+// dev:ui, and dev:back together.
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { connect as netConnect } from "node:net";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { claimDevSession, stopDevBackContainers } from "./devSession.mjs";
-import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse, robotHasMuscat } from "./muscatLocal.mjs";
+import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse, MUSCAT_CONTAINER, robotHasMuscat } from "./muscatLocal.mjs";
+import { resolveSim, startSim, stopSims } from "./sim.mjs";
 import { assertManifestPorts, assertManifestVariables, readManifest } from "./manifest.mjs";
 import { devPluginId } from "./devId.mjs";
 import {
@@ -14,6 +16,7 @@ import {
   ensureIdeVenv,
   findPluginRoot,
   log,
+  parseArgs,
   prompt,
   promptRobotConnection,
   venvPython,
@@ -129,13 +132,24 @@ export async function runDev(args = []) {
   // the robot itself — the local Muscat then publishes the zenoh port for it.
   if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
 
+  // No robot: a simulator stands in for it (--sim, else the manifest's target).
+  const sim = remoteRobot ? null : resolveSim(parseArgs(args).sim, readManifest(root));
+
   // A robot running Muscat is the gateway (:10000) and common for both the UI and the backend.
   // Otherwise the local Muscat runtime is; the backend joins its netns, so the plugin's declared
   // ports are published from it too.
   const muscat = (await robotHasMuscat(robotIp)) ? null : await ensureLocalMuscat({
     pluginPorts: portRanges,
     zenohPort: remoteRobot && !proxyEndpoint ? Number(process.env.MUSCAT_ZENOH_PORT) || null : null,
+    services: sim?.services,
+    env: sim?.env,
   }).catch((e) => { log.warn(`local Muscat: ${e.message}`); return null; });
+  if (sim && muscat !== MUSCAT_CONTAINER) {
+    log.warn(`--sim needs muscat-pk's own Muscat${muscat ? ` ('${muscat}' is running — stop it to use the simulator)` : ""}; no simulator.`);
+  } else if (sim) {
+    // dev:ui then serves the real Muscat UI against the local Muscat, like with muscat-dev.
+    if (await startSim(sim).catch((e) => log.warn(`simulator: ${e.message}`))) process.env.MUSCAT_PK_SIM = sim.name;
+  }
   if (muscat) {
     process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
   } else if (remoteRobot || (await isPortInUse(GATEWAY_PORT))) {
@@ -160,6 +174,11 @@ export async function runDev(args = []) {
     if (hostAgent && hostAgent.exitCode === null) hostAgent.kill();
     if (backend.exitCode === null) backend.kill();
     stopDevBackContainers();
+    // Only our own runtime — a muscat-dev the user started stays up.
+    if (muscat === MUSCAT_CONTAINER) {
+      stopSims();
+      spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+    }
   };
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);

package/cli/src/devBack.mjs

@@ -61,7 +61,7 @@ function muscatZenohEnv(container) {
 
 function backendNetwork(portRanges, robotGateway) {
   const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
-  if (muscat) return { run: ["--network", `container:${muscat}`], env: muscatZenohEnv(muscat), shared: true };
+  if (muscat) return { run: ["--network", `container:${muscat}`, "--ipc", "host"], env: muscatZenohEnv(muscat), shared: true };
   // The robot runs Muscat: its gateway, own netns (host network on Linux), declared ports published.
   if (robotGateway) {
     const run = usesHostNetwork() ? ["--network", "host"] : publishPortFlags(portRanges);

package/cli/src/devUi.mjs

@@ -214,7 +214,8 @@ export async function runDevUi(args = []) {
     });
   }
 
-  const localDevMuscat = await localFullMuscat(robotIp);
+  // muscat-dev, or our own Muscat with a simulator (`dev --sim`): a full local Muscat to show.
+  const localDevMuscat = !!process.env.MUSCAT_PK_SIM || (await localFullMuscat(robotIp));
   const uiHost = isRemoteRobot(robotIp) ? robotIp : localDevMuscat ? "localhost" : "";
 
   const previewRoot = findPreviewHostRoot();

package/cli/src/mcp.mjs

@@ -39,7 +39,7 @@ import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
+import { dockerUserFlags, kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
 import { PYTHON_DEV_IMAGE } from "./python.mjs";
 import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
 import { CPP_DEV_IMAGE } from "./cpp.mjs";
@@ -483,14 +483,14 @@ function introspectInDocker(probe) {
   const cache = join(cacheRoot, ver || "latest");
   // Only the SDK version in use is kept (~165MB each) — other versions don't pile up.
   for (const old of existsSync(cacheRoot) ? readdirSync(cacheRoot) : []) {
-    if (join(cacheRoot, old) !== cache) rmSync(join(cacheRoot, old), { recursive: true, force: true });
+    if (join(cacheRoot, old) !== cache) removeCache(join(cacheRoot, old));
   }
   mkdirSync(cache, { recursive: true });
   const pkg = ver ? `rainbow-rb-sdk==${ver}` : "rainbow-rb-sdk";
   const script =
     `[ -f /c/.ok ] || { pip3 install -q --break-system-packages --target /c '${pkg}' >&2 && touch /c/.ok; } && ` +
     `PYTHONPATH=/c python3 -c "$PROBE"`;
-  const r = spawnSync("docker", ["run", "--rm", "-v", `${cache}:/c`, "-e", "PROBE", PYTHON_DEV_IMAGE, "bash", "-c", script], {
+  const r = spawnSync("docker", ["run", "--rm", ...dockerUserFlags(), "-v", `${cache}:/c`, "-e", "PROBE", PYTHON_DEV_IMAGE, "bash", "-c", script], {
     encoding: "utf8",
     maxBuffer: 8 << 20,
     env: { ...process.env, PROBE: probe },
@@ -499,6 +499,20 @@ function introspectInDocker(probe) {
   return parseProbe(r);
 }
 
+// Caches written by older kits as root (Linux) can't be unlinked by the user — clear them as root in Docker.
+function removeCache(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    spawnSync("docker", ["run", "--rm", "-v", `${dir}:/c`, PYTHON_DEV_IMAGE, "find", "/c", "-mindepth", "1", "-delete"], { stdio: "ignore" });
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* left for a later run — must not block reading the SDK */
+    }
+  }
+}
+
 function parseProbe(r) {
   // Importing rainbow.rb_sdk has side effects that print to stdout (e.g. the
   // Zenoh client logs its connection endpoints), ahead of our own final

package/cli/src/muscatLocal.mjs

@@ -3,12 +3,12 @@
 // preview-host hits http://localhost:3000/common/* (baked into the nexus bundle), so program
 // preview works with no front-end change. The backend container joins its netns. We reuse any
 // Muscat already publishing :10000 (e.g. a `muscat` / `muscat-dev` container) and only otherwise
-// start our own: the S3 runtime image with just the `common` service.
+// start our own: the S3 runtime image with `common` (plus the services `--sim` needs).
 import { spawnSync } from "node:child_process";
 import { createServer } from "node:net";
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { mediaPortFlags, MEDIA_PORTS, publishPortFlags } from "./ports.mjs";
 import { canSkipImageBuild, hasBin, log, buildCacheFlags } from "./util.mjs";
 import { LOCAL_HOSTS } from "./zenohDev.mjs";
@@ -113,21 +113,40 @@ async function ensureRuntimeImage(total) {
   return image;
 }
 
-async function ensureCommonBinary(version) {
+async function ensureServiceBinary(svc, version) {
   const ARCH = dockerArch();
-  const dir = resolve(CACHE, "services", "common");
+  const dir = resolve(CACHE, "services", svc);
   const stamp = resolve(dir, ".version");
-  if (existsSync(stamp) && readFileSync(stamp, "utf8").trim() === version && existsSync(resolve(dir, `common.${ARCH}.bin`))) return dir;
-  log.step(`downloading Muscat common service ${version} (${ARCH})…`);
-  const zip = resolve(CACHE, `common-${version}.zip`);
-  writeFileSync(zip, await fetchBuffer(`${S3}/common/${version}.zip`));
-  extractZip(zip, dir, ["config.env", `common.${ARCH}.bin`]);
+  if (existsSync(stamp) && readFileSync(stamp, "utf8").trim() === version && existsSync(resolve(dir, `${svc}.${ARCH}.bin`))) return dir;
+  log.step(`downloading Muscat ${svc} service ${version} (${ARCH})…`);
+  const zip = resolve(CACHE, `${svc}-${version}.zip`);
+  writeFileSync(zip, await fetchBuffer(`${S3}/${svc}/${version}.zip`));
+  extractZip(zip, dir, ["config.env", `${svc}.${ARCH}.bin`]);
   rmSync(zip, { force: true });
-  chmodSync(resolve(dir, `common.${ARCH}.bin`), 0o755);
+  chmodSync(resolve(dir, `${svc}.${ARCH}.bin`), 0o755);
   writeFileSync(stamp, `${version}\n`);
   return dir;
 }
 
+// Sim containers live on this network and connect to common's Zenoh by container name.
+export const MUSCAT_NETWORK = "muscat-pk";
+
+function ensureNetwork() {
+  if (spawnSync("docker", ["network", "inspect", MUSCAT_NETWORK], { stdio: "ignore" }).status === 0) return;
+  spawnSync("docker", ["network", "create", "--label", "com.rainbow-robotics.muscat-pk=true", MUSCAT_NETWORK], { stdio: "ignore" });
+}
+
+// common (127.0.0.1:7447) and the services (127.0.0.1:0) listen on loopback by default; rb-ctl's
+// listen-endpoints file opens both to the network. Sims reach common as muscat-pk-muscat:7447, and
+// gossip has them dial each service back — on loopback only the sim that happened to connect first
+// answers manipulate's receive_one.
+function writeZenohListen(open) {
+  const file = resolve(CACHE, "data", "zenoh_listen_endpoints.json5");
+  if (!open) return rmSync(file, { force: true });
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `{\n  common: ["tcp/0.0.0.0:7447"],\n  service: ["tcp/0.0.0.0:0"],\n}\n`);
+}
+
 async function waitForApi(timeoutMs = 180_000) {
   const start = Date.now();
   for (;;) {
@@ -187,14 +206,23 @@ const containerLabel = (name, label) =>
 /**
  * Make sure a Muscat answers on localhost:3000 / :10000. Returns the container name,
  * or null when one can't be started (no Docker, foreign process on the ports).
- * The container is left running across runs — stop it with `docker rm -f muscat-pk-muscat`.
+ * `dev` removes it on exit; `dev:ui` alone leaves it running (`docker rm -f muscat-pk-muscat`).
  */
-export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } = {}) {
+export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null, services = [], env = {} } = {}) {
   if (process.env.MUSCAT_PK_NO_LOCAL_MUSCAT === "1") return null;
-  const portsKey = [...pluginPorts, ...(zenohPort ? [`zenoh:${zenohPort}`] : [])].join(",");
+  // Extra services (log, manipulate, rby1, ...) and env come with --sim; a different set recreates it too.
+  const svcs = ["common", ...services.filter((s) => s !== "common")];
+  const envFlags = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+  const portsKey = [
+    ...pluginPorts,
+    ...(zenohPort ? [`zenoh:${zenohPort}`] : []),
+    "ipc:host",
+    ...(services.length ? [`svc:${svcs.join("+")}`] : []),
+    ...Object.entries(env).map(([k, v]) => `${k}=${v}`),
+  ].join(",");
   const existing = hasBin("docker") ? localMuscatContainer() : null;
   if (existing === MUSCAT_CONTAINER && containerLabel(existing, PORTS_LABEL) !== portsKey) {
-    log.step(`recreating local Muscat to publish ${portsKey || "no extra"} port(s)`);
+    log.step(`recreating local Muscat for ${portsKey || "no extra ports / services"}`);
     spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
   } else if (existing) {
     if (existing !== MUSCAT_CONTAINER && portsKey)
@@ -213,11 +241,15 @@ export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } =
 
   const versions = await resolveVersions();
   const total = versions.total;
-  const commonVersion = versions.services?.common?.version;
-  if (!total || !commonVersion) throw new Error("version.json has no total / services.common.version");
+  if (!total) throw new Error("version.json has no total");
+  const missing = svcs.filter((s) => !versions.services?.[s]?.version);
+  if (missing.length) throw new Error(`version.json has no services.${missing.join(" / ")}.version`);
 
   const image = await ensureRuntimeImage(total);
-  const commonDir = await ensureCommonBinary(commonVersion);
+  const svcMounts = [];
+  for (const s of svcs) svcMounts.push("-v", `${await ensureServiceBinary(s, versions.services[s].version)}:/app/services/${s}`);
+  ensureNetwork();
+  writeZenohListen(services.length > 0);
 
   let media = true;
   for (const port of MEDIA_PORTS) if (await isPortInUse(port)) media = false;
@@ -228,12 +260,16 @@ export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } =
   const published = pluginPorts.filter((port) => !busy.includes(port));
 
   spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
-  log.step(`starting local Muscat (common ${commonVersion}) → http://localhost:${API_PORT}/common/docs`);
+  log.step(`starting local Muscat (${svcs.map((s) => `${s} ${versions.services[s].version}`).join(", ")}) → http://localhost:${API_PORT}/common/docs`);
   const r = spawnSync("docker", [
     "run", "-d", "--name", MUSCAT_CONTAINER, "--label", "com.rainbow-robotics.muscat-pk=true", "--label", `${PORTS_LABEL}=${portsKey}`,
-    "-e", "RB_ENABLED_SERVICES=common",
+    "--network", MUSCAT_NETWORK,
+    // Like the robot, where plugins run with --ipc host: zenoh SHM and plugin shm_open reach the services.
+    "--ipc", "host",
+    "-e", `RB_ENABLED_SERVICES=${svcs.join(",")}`,
     "-e", "RB_RUNTIME_ENABLE_ZENOH_BRIDGE=0",
-    "-v", `${commonDir}:/app/services/common`,
+    ...envFlags,
+    ...svcMounts,
     "-v", `${resolve(CACHE, "data")}:/app/data`,
     "-p", `127.0.0.1:${API_PORT}:${API_PORT}`,
     "-p", `127.0.0.1:${GATEWAY_PORT}:${GATEWAY_PORT}`,
@@ -245,7 +281,7 @@ export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } =
   ], { stdio: ["ignore", "ignore", "inherit"] });
   if (r.status !== 0) throw new Error("failed to start the local Muscat container.");
   await waitForApi();
-  log.step(`local Muscat ready — keeps running between runs; stop with: docker rm -f ${MUSCAT_CONTAINER}`);
+  log.step("local Muscat ready");
   if (published.length) log.step(`plugin backend ports published on 127.0.0.1: ${published.join(", ")}`);
   if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
   return MUSCAT_CONTAINER;

package/cli/src/pluginDevServer.mjs

@@ -69,7 +69,7 @@ export function mount(container, { socketUrl, pluginId, hostServices, data, onSa
   // (there may be no backend at all in dev, e.g. no robot reachable) — each rb
   // method awaits this promise internally instead.
   const wsPromise = RbWs.connect(socketUrl, pluginId);
-  const rb = createLazyRbSdk(wsPromise, hostServices, { data, onSave });
+  const rb = createLazyRbSdk(wsPromise, hostServices, { data, onSave, pluginId });
   const root = createRoot(container);
   let mounted = true;
   const render = (Component) => {

package/cli/src/sim.mjs

@@ -0,0 +1,163 @@
+// `dev --sim <model>`: robot simulators next to the local Muscat, for developing without a robot.
+// Cobot: coreSW (rainbowroboticsofficial/cobot-sim) per component, joined to common's Zenoh.
+// RB-Y1: rby1-sim + Xvfb built locally (it needs a GLFW window; there is no headless mode yet).
+import { spawnSync } from "node:child_process";
+import { canSkipImageBuild, log } from "./util.mjs";
+import { MUSCAT_NETWORK } from "./muscatLocal.mjs";
+
+const COBOT_IMAGE = "rainbowroboticsofficial/cobot-sim";
+const RBY1_IMAGE = "rainbowroboticsofficial/rby1-sim";
+const RBY1_LOCAL = "muscat-pk-rby1-sim";
+const RBY1_CONTAINER = "muscat-pk-sim-rby1";
+const SIM_LABEL = "com.rainbow-robotics.muscat-pk.sim";
+
+// ponytail: model table in code; move to S3 version.json when sims are versioned with Muscat (amr: no sim yet)
+// sim name → coreSW RB_MODEL per component, and the Muscat robot model it registers as.
+const COBOT_MODELS = {
+  "500880": { robotModel: "C500880", models: ["500880"] },
+  "500920": { robotModel: "C500920", models: ["500920"] },
+  RBY2: { robotModel: "RBY2", models: ["C500880", "C501880", "C502880"] },
+};
+const RBY1_TYPES = ["a", "m", "ub"];
+
+// rby1-sim renders MuJoCo with software GL every frame; one GL thread and a tiny screen cut it from
+// ~3.5 cores to ~1. The cap keeps a busy Mac usable; the image already skips RT-loop timeouts.
+const RBY1_DOCKERFILE = `ARG BASE=0.10.6-m_v1.3
+FROM ${RBY1_IMAGE}:\${BASE}
+RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends xvfb && rm -rf /var/lib/apt/lists/*
+ENV LP_NUM_THREADS=0 DISPLAY=:99
+CMD ["sh", "-c", "Xvfb :99 -screen 0 320x240x16 -nolisten tcp & sleep 1; exec ./app_main"]
+`;
+
+export const SIM_NAMES = [...Object.keys(COBOT_MODELS), ...RBY1_TYPES.map((t) => `rby1-${t}`)];
+
+/** `muscat-pk sim list`: "<name>\t<what runs>" per line, for scripts and the VS Code Dev picker. */
+export function runSimList() {
+  for (const [name, { robotModel, models }] of Object.entries(COBOT_MODELS))
+    console.log(`${name}\tcobot · ${robotModel}${models.length > 1 ? ` (${models.join(", ")})` : ""}`);
+  for (const t of RBY1_TYPES) console.log(`rby1-${t}\tRB-Y1 ${t.toUpperCase()}`);
+}
+
+/** "500880" | "RBY2" | "rby1-m" | "rby1-m_v1.2" → { services, env, ... } or null. */
+export function parseSim(name) {
+  if (COBOT_MODELS[name]) return { name, kind: "cobot", services: ["log", "manipulate"], env: {}, ...COBOT_MODELS[name] };
+  const m = /^rby1-(a|m|ub)(?:_(v[\d.]+))?$/.exec(name ?? "");
+  if (m) return { name, kind: "rby1", services: ["log", "rby1"], env: { RBY1_HOST: RBY1_CONTAINER }, robotModel: m[1], type: m[1], version: m[2] };
+  return null;
+}
+
+/** Only an explicit --sim <name> runs a simulator. */
+export function resolveSim(simArg, manifest) {
+  if (simArg === undefined) return null;
+  const sim = typeof simArg === "string" ? parseSim(simArg) : null;
+  if (!sim) throw new Error(`--sim takes one of: ${SIM_NAMES.join(", ")} (rby1 also takes rby1-m_v1.2)`);
+  const models = Array.isArray(manifest.targetModels) ? manifest.targetModels : null;
+  if (models && !models.includes(simArg)) log.warn(`--sim ${simArg} is not in manifest targetModels (${models.join(", ")})`);
+  return sim;
+}
+
+async function hubTags(repo) {
+  const res = await fetch(`https://hub.docker.com/v2/repositories/${repo}/tags?page_size=100&ordering=last_updated`, {
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!res.ok) throw new Error(`Docker Hub ${repo}: HTTP ${res.status}`);
+  return (await res.json()).results.map((t) => t.name);
+}
+
+// "0.10.6-m_v1.3" → [0, 10, 6, 1, 3]
+const semver = (v) => v.split(/[._v-]/).map(Number).filter((n) => !Number.isNaN(n));
+const newer = (a, b) => {
+  const [x, y] = [semver(a), semver(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  return 0;
+};
+
+// Latest published tag; offline falls back to whatever was pulled before.
+async function latestTag(repo, pattern) {
+  try {
+    const tags = (await hubTags(repo)).filter((t) => pattern.test(t));
+    if (tags.length) return tags.sort(newer).at(-1);
+  } catch (e) {
+    log.warn(`${e.message} — using a local image`);
+  }
+  const local = spawnSync("docker", ["images", repo, "--format", "{{.Tag}}"], { encoding: "utf8" }).stdout ?? "";
+  const tags = local.split("\n").map((t) => t.trim()).filter((t) => pattern.test(t));
+  if (!tags.length) throw new Error(`no ${repo} image matching ${pattern} (offline and nothing pulled yet)`);
+  return tags.sort(newer).at(-1);
+}
+
+function pull(image) {
+  if (spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" }).status === 0) return;
+  log.step(`docker pull ${image}…`);
+  if (spawnSync("docker", ["pull", image], { stdio: "inherit" }).status !== 0) throw new Error(`docker pull ${image} failed`);
+}
+
+function run(name, args) {
+  spawnSync("docker", ["rm", "-f", name], { stdio: "ignore" });
+  const r = spawnSync("docker", [
+    // --ipc host like the robot: the cobot coreSWs share one shm segment (RB_MESSAGE_SHM, a slot per model).
+    "run", "-d", "--name", name, "--network", MUSCAT_NETWORK, "--ipc", "host",
+    "--label", "com.rainbow-robotics.muscat-pk=true", "--label", `${SIM_LABEL}=true`,
+    ...args,
+  ], { stdio: ["ignore", "ignore", "inherit"] });
+  if (r.status !== 0) throw new Error(`failed to start ${name}`);
+}
+
+// The Muscat UI (robot info, components, connection state) follows the registered robot model.
+async function registerRobot(robotModel) {
+  const res = await fetch("http://127.0.0.1:3000/common/upsert-robot-info", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ robotModel }),
+  });
+  if (!res.ok) throw new Error(`upsert-robot-info ${robotModel}: HTTP ${res.status}`);
+  log.step(`robot model ${robotModel} registered in the local Muscat`);
+}
+
+/** Start the simulator containers and register the robot model; returns the container names. */
+export async function startSim(sim) {
+  const names = await startContainers(sim);
+  await registerRobot(sim.robotModel);
+  return names;
+}
+
+// Needs the local Muscat on MUSCAT_NETWORK.
+async function startContainers(sim) {
+  stopSims();
+  if (sim.kind === "cobot") {
+    const image = `${COBOT_IMAGE}:${await latestTag(COBOT_IMAGE, /^\d+\.\d+\.\d+$/)}`;
+    pull(image);
+    const names = sim.models.map((model) => `muscat-pk-sim-${model}`);
+    sim.models.forEach((model, i) => run(names[i], [
+      "--cap-add", "SYS_NICE", "--ulimit", "rtprio=99",
+      "-e", `RB_MODEL=${model}`,
+      "-e", "RB_ZENOH_CONNECT=tcp/muscat-pk-muscat:7447",
+      image,
+    ]));
+    log.step(`cobot sim ${sim.name} (${image}) → ${sim.models.join(", ")}`);
+    return names;
+  }
+
+  const pattern = sim.version ? new RegExp(`^\\d+\\.\\d+\\.\\d+-${sim.type}_${sim.version.replace(/\./g, "\\.")}$`) : new RegExp(`^\\d+\\.\\d+\\.\\d+-${sim.type}_v[\\d.]+$`);
+  const base = await latestTag(RBY1_IMAGE, pattern);
+  const image = `${RBY1_LOCAL}:${base}`;
+  if (!canSkipImageBuild(image)) {
+    log.step(`building ${image} (rby1-sim + Xvfb, first run pulls ~150MB)…`);
+    const r = spawnSync("docker", ["build", "-t", image, "--build-arg", `BASE=${base}`, "--label", "com.rainbow-robotics.muscat-pk=true", "-"], {
+      input: RBY1_DOCKERFILE,
+      stdio: ["pipe", "inherit", "inherit"],
+    });
+    if (r.status !== 0) throw new Error(`docker build ${image} failed`);
+  }
+  run(RBY1_CONTAINER, ["--cpus", process.env.MUSCAT_PK_RBY1_CPUS || "1.5", image]);
+  log.step(`rby1 sim ${base} → ${RBY1_CONTAINER}:50051`);
+  return [RBY1_CONTAINER];
+}
+
+export function stopSims() {
+  const ids = (spawnSync("docker", ["ps", "-aq", "--filter", `label=${SIM_LABEL}=true`], { encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean);
+  if (!ids.length) return;
+  // The cobot coreSWs share these under --ipc host; drop them so the next run starts from a fresh segment.
+  spawnSync("docker", ["exec", ids[0], "sh", "-c", "rm -f /dev/shm/RB_COBOT_SHM /dev/shm/RB_MESSAGE_SHM"], { stdio: "ignore" });
+  spawnSync("docker", ["rm", "-f", ...ids], { stdio: "ignore" });
+}

package/cli/src/util.mjs

@@ -144,6 +144,8 @@ const LOCAL_HOSTS = new Set(["", "localhost", "127.0.0.1", "::1"]);
  */
 export async function promptRobotConnection(args = []) {
   const parsed = parseArgs(args);
+  // A simulator stands in for the robot.
+  if (parsed.sim !== undefined) return { robotIp: "", robotToken: "" };
   const robotIp =
     parsed["robot-ip"] ??
     process.env.MUSCAT_ROBOT_HOST ??