@rainbow-robotics/muscat-plugin-kit 1.10.2-dev.8 → 1.10.2-dev.9

package/cli/src/mcp.mjs

@@ -450,16 +450,24 @@ except Exception as e:
 ${script}
 `;
   if (!py) {
-    return introspectInDocker(probe) ?? { error: "Python not found on PATH. Install Python 3 to use rb-sdk introspection." };
+    return introspectInDocker(probe) ?? NO_DEV_IMAGE;
   }
   const r = spawnSync(py, ["-c", probe], { encoding: "utf8", maxBuffer: 8 << 20 });
   if (r.status !== 0) {
     return { error: `python introspection failed: ${(r.stderr || "").trim().slice(0, 500)}` };
   }
   const local = parseProbe(r);
-  return local.error && local.notInstalled ? introspectInDocker(probe) ?? local : local;
+  return local.error && local.notInstalled ? introspectInDocker(probe) ?? NO_DEV_IMAGE : local;
 }
 
+// The SDK isn't importable here (macOS has no wheels) and the image to read it in isn't built yet.
+const NO_DEV_IMAGE = {
+  error:
+    "rainbow-rb-sdk can't be read on this machine yet: it isn't importable from the plugin's .venv " +
+    `(macOS has no SDK wheels) and the ${PYTHON_DEV_IMAGE} Docker image isn't built. Run \`muscat-pk dev:back\` ` +
+    "once in a python plugin (it builds the image), then retry.",
+};
+
 // No macOS wheels: import the plugin's pinned SDK inside the python dev image (cached).
 function introspectInDocker(probe) {
   if (spawnSync("docker", ["image", "inspect", PYTHON_DEV_IMAGE], { encoding: "utf8" }).status !== 0) return null;

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1792732764037,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}
+{"generatedAt":1792736587400,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}

package/cli/templates/common/README.md

@@ -59,129 +59,6 @@ production, Muscat provides `@rainbow-robotics/plugin-ui`, React, and ReactDOM
 through the host import map; plugin UI build output imports those as host
 externals.
 
-### Styles
-
-`muscat()` automatically loads `ui/style.{css,scss,sass,less}` (or
-`ui/styles.{css,scss,sass,less}`) for every UI entry, plus
-`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific stylesheet. You
-do not need to import CSS from every `.tsx` file.
-
-The scaffold uses Tailwind's theme/utilities layers only, so plugin utilities
-are generated from files under `ui/` without applying Tailwind preflight resets
-to the host page.
-
-Built CSS selectors are scoped under the current plugin id
-(`[data-muscat-plugin-id="..."]`). CSS-in-JS libraries such as Emotion work
-normally, but global styles should be scoped by the author.
-
-#### Tailwind
-
-This template enables Tailwind in `vite.config.ts`:
-
-```ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-
-export default defineConfig({
-  plugins: [tailwindcss(), muscat()],
-});
-```
-
-The default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
-
-```css
-@layer theme, utilities;
-
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/utilities.css" layer(utilities);
-
-@source "./**/*.{ts,tsx}";
-```
-
-#### SCSS, Sass, and Less
-
-Install the preprocessor package, then create one of the auto-loaded style files.
-
-```bash
-npm i -D sass
-```
-
-```scss
-/* ui/style.scss */
-$accent: #3b82f6;
-
-.panel {
-  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
-
-  &__title {
-    color: $accent;
-  }
-}
-```
-
-For Less, install `less` and use `ui/style.less`.
-
-#### Emotion
-
-Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
-bundle them when they are installed and imported by the plugin.
-
-For `styled`, no Vite config change is needed:
-
-```bash
-npm i @emotion/react @emotion/styled
-```
-
-```tsx
-import styled from "@emotion/styled";
-
-const Panel = styled.div({
-  display: "grid",
-  gap: 12,
-});
-```
-
-For Emotion's `css` prop, pass React plugin options through `muscat()` and add
-`jsxImportSource` to `tsconfig.json`:
-
-```bash
-npm i @emotion/react @emotion/styled
-npm i -D @emotion/babel-plugin
-```
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-
-export default defineConfig({
-  plugins: [
-    tailwindcss(),
-    muscat({
-      react: {
-        jsxImportSource: "@emotion/react",
-        babel: {
-          plugins: ["@emotion/babel-plugin"],
-        },
-      },
-    }),
-  ],
-});
-```
-
-```json
-{
-  "compilerOptions": {
-    "jsxImportSource": "@emotion/react"
-  }
-}
-```
-
-Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
-inside plugins.
-
 ### useRb() hook
 
 Access the communication API between the plugin module and UI from any plugin component.
@@ -232,12 +109,11 @@ if (ok) {
 }
 ```
 
-### Saving and restoring form data (`useRbFormData` / `useRbSave`)
+### Saving and restoring your program command step (`useRbFormData` / `useRbSave`)
 
-If the host embeds your plugin in a form it owns (e.g. a program step editor
-with its own Save button), it can hand your plugin previously-saved values and
-pull the current values back out when the user saves. The host — not the
-plugin — persists the data (IndexedDB, backend, etc.).
+Use these only in your `program.panel` UI, where the user edits your program
+command step: `useRbFormData` gives back the values saved in the step, and
+`useRbSave` hands the current values to Muscat when the step is saved.
 
 ```tsx
 import { useState } from "react";
@@ -1246,3 +1122,128 @@ muscat-pk sdk update     # update Python SDK to latest
 muscat-pk update         # update muscat-plugin-kit itself
 muscat-pk uninstall      # remove muscat-pk itself
 ```
+
+---
+
+## Styles
+
+`muscat()` automatically loads `ui/style.{css,scss,sass,less}` (or
+`ui/styles.{css,scss,sass,less}`) for every UI entry, plus
+`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific stylesheet. You
+do not need to import CSS from every `.tsx` file.
+
+The scaffold uses Tailwind's theme/utilities layers only, so plugin utilities
+are generated from files under `ui/` without applying Tailwind preflight resets
+to the host page.
+
+Built CSS selectors are scoped under the current plugin id
+(`[data-muscat-plugin-id="..."]`). CSS-in-JS libraries such as Emotion work
+normally, but global styles should be scoped by the author.
+
+### Tailwind
+
+This template enables Tailwind in `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss(), muscat()],
+});
+```
+
+The default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
+
+```css
+@layer theme, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@source "./**/*.{ts,tsx}";
+```
+
+### SCSS, Sass, and Less
+
+Install the preprocessor package, then create one of the auto-loaded style files.
+
+```bash
+npm i -D sass
+```
+
+```scss
+/* ui/style.scss */
+$accent: #3b82f6;
+
+.panel {
+  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
+
+  &__title {
+    color: $accent;
+  }
+}
+```
+
+For Less, install `less` and use `ui/style.less`.
+
+### Emotion
+
+Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
+bundle them when they are installed and imported by the plugin.
+
+For `styled`, no Vite config change is needed:
+
+```bash
+npm i @emotion/react @emotion/styled
+```
+
+```tsx
+import styled from "@emotion/styled";
+
+const Panel = styled.div({
+  display: "grid",
+  gap: 12,
+});
+```
+
+For Emotion's `css` prop, pass React plugin options through `muscat()` and add
+`jsxImportSource` to `tsconfig.json`:
+
+```bash
+npm i @emotion/react @emotion/styled
+npm i -D @emotion/babel-plugin
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    muscat({
+      react: {
+        jsxImportSource: "@emotion/react",
+        babel: {
+          plugins: ["@emotion/babel-plugin"],
+        },
+      },
+    }),
+  ],
+});
+```
+
+```json
+{
+  "compilerOptions": {
+    "jsxImportSource": "@emotion/react"
+  }
+}
+```
+
+Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
+inside plugins.

package/cli/templates/readme-cpp/README.md

@@ -59,129 +59,6 @@ production, Muscat provides `@rainbow-robotics/plugin-ui`, React, and ReactDOM
 through the host import map; plugin UI build output imports those as host
 externals.
 
-### Styles
-
-`muscat()` automatically loads `ui/style.{css,scss,sass,less}` (or
-`ui/styles.{css,scss,sass,less}`) for every UI entry, plus
-`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific stylesheet. You
-do not need to import CSS from every `.tsx` file.
-
-The scaffold uses Tailwind's theme/utilities layers only, so plugin utilities
-are generated from files under `ui/` without applying Tailwind preflight resets
-to the host page.
-
-Built CSS selectors are scoped under the current plugin id
-(`[data-muscat-plugin-id="..."]`). CSS-in-JS libraries such as Emotion work
-normally, but global styles should be scoped by the author.
-
-#### Tailwind
-
-This template enables Tailwind in `vite.config.ts`:
-
-```ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-
-export default defineConfig({
-  plugins: [tailwindcss(), muscat()],
-});
-```
-
-The default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
-
-```css
-@layer theme, utilities;
-
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/utilities.css" layer(utilities);
-
-@source "./**/*.{ts,tsx}";
-```
-
-#### SCSS, Sass, and Less
-
-Install the preprocessor package, then create one of the auto-loaded style files.
-
-```bash
-npm i -D sass
-```
-
-```scss
-/* ui/style.scss */
-$accent: #3b82f6;
-
-.panel {
-  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
-
-  &__title {
-    color: $accent;
-  }
-}
-```
-
-For Less, install `less` and use `ui/style.less`.
-
-#### Emotion
-
-Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
-bundle them when they are installed and imported by the plugin.
-
-For `styled`, no Vite config change is needed:
-
-```bash
-npm i @emotion/react @emotion/styled
-```
-
-```tsx
-import styled from "@emotion/styled";
-
-const Panel = styled.div({
-  display: "grid",
-  gap: 12,
-});
-```
-
-For Emotion's `css` prop, pass React plugin options through `muscat()` and add
-`jsxImportSource` to `tsconfig.json`:
-
-```bash
-npm i @emotion/react @emotion/styled
-npm i -D @emotion/babel-plugin
-```
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-
-export default defineConfig({
-  plugins: [
-    tailwindcss(),
-    muscat({
-      react: {
-        jsxImportSource: "@emotion/react",
-        babel: {
-          plugins: ["@emotion/babel-plugin"],
-        },
-      },
-    }),
-  ],
-});
-```
-
-```json
-{
-  "compilerOptions": {
-    "jsxImportSource": "@emotion/react"
-  }
-}
-```
-
-Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
-inside plugins.
-
 ### useRb() hook
 
 Access the communication API between the plugin module and UI from any plugin component.
@@ -232,12 +109,11 @@ if (ok) {
 }
 ```
 
-### Saving and restoring form data (`useRbFormData` / `useRbSave`)
+### Saving and restoring your program command step (`useRbFormData` / `useRbSave`)
 
-If the host embeds your plugin in a form it owns (e.g. a program step editor
-with its own Save button), it can hand your plugin previously-saved values and
-pull the current values back out when the user saves. The host — not the
-plugin — persists the data (IndexedDB, backend, etc.).
+Use these only in your `program.panel` UI, where the user edits your program
+command step: `useRbFormData` gives back the values saved in the step, and
+`useRbSave` hands the current values to Muscat when the step is saved.
 
 ```tsx
 import { useState } from "react";
@@ -1010,3 +886,128 @@ muscat-pk type change    # switch backend type
 muscat-pk update         # update muscat-plugin-kit itself
 muscat-pk uninstall      # remove muscat-pk itself
 ```
+
+---
+
+## Styles
+
+`muscat()` automatically loads `ui/style.{css,scss,sass,less}` (or
+`ui/styles.{css,scss,sass,less}`) for every UI entry, plus
+`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific stylesheet. You
+do not need to import CSS from every `.tsx` file.
+
+The scaffold uses Tailwind's theme/utilities layers only, so plugin utilities
+are generated from files under `ui/` without applying Tailwind preflight resets
+to the host page.
+
+Built CSS selectors are scoped under the current plugin id
+(`[data-muscat-plugin-id="..."]`). CSS-in-JS libraries such as Emotion work
+normally, but global styles should be scoped by the author.
+
+### Tailwind
+
+This template enables Tailwind in `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss(), muscat()],
+});
+```
+
+The default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
+
+```css
+@layer theme, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@source "./**/*.{ts,tsx}";
+```
+
+### SCSS, Sass, and Less
+
+Install the preprocessor package, then create one of the auto-loaded style files.
+
+```bash
+npm i -D sass
+```
+
+```scss
+/* ui/style.scss */
+$accent: #3b82f6;
+
+.panel {
+  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
+
+  &__title {
+    color: $accent;
+  }
+}
+```
+
+For Less, install `less` and use `ui/style.less`.
+
+### Emotion
+
+Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
+bundle them when they are installed and imported by the plugin.
+
+For `styled`, no Vite config change is needed:
+
+```bash
+npm i @emotion/react @emotion/styled
+```
+
+```tsx
+import styled from "@emotion/styled";
+
+const Panel = styled.div({
+  display: "grid",
+  gap: 12,
+});
+```
+
+For Emotion's `css` prop, pass React plugin options through `muscat()` and add
+`jsxImportSource` to `tsconfig.json`:
+
+```bash
+npm i @emotion/react @emotion/styled
+npm i -D @emotion/babel-plugin
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    muscat({
+      react: {
+        jsxImportSource: "@emotion/react",
+        babel: {
+          plugins: ["@emotion/babel-plugin"],
+        },
+      },
+    }),
+  ],
+});
+```
+
+```json
+{
+  "compilerOptions": {
+    "jsxImportSource": "@emotion/react"
+  }
+}
+```
+
+Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
+inside plugins.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "1.10.2-dev.8",
+  "version": "1.10.2-dev.9",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -52,8 +52,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rainbow-robotics/plugin-ui": "1.10.2-dev.8",
-    "@rainbow-robotics/preview-host": "1.10.2-dev.8",
+    "@rainbow-robotics/plugin-ui": "1.10.2-dev.9",
+    "@rainbow-robotics/preview-host": "1.10.2-dev.9",
     "@types/react": "^19.0.10",
     "postcss": "^8.5.8",
     "typescript": "^5.8.0",