npm - @rainbow-robotics/muscat-plugin-kit - Versions diffs - 1.10.1-dev.1 → 1.10.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (205) hide show

package/cli/templates/common/README.md CHANGED Viewed

@@ -1,1231 +1,1231 @@
-# __PLUGIN_NAME__
-A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
-## Quick start
-```bash
-muscat-pk dev        # UI preview + backend together
-muscat-pk dev:ui     # UI preview only
-muscat-pk dev:back   # backend only (Python watchfiles / ROS2 Docker)
-muscat-pk build      # build + distributable ZIP
-```
----
-## Project structure
-```
-__PLUGIN_DIR__/
-├─ ui/
-│   ├─ content.tsx      # plugin UI entry point
-│   └─ style.css        # plugin styles auto-loaded by muscat()
-├─ py/
-│   └─ main.py          # Python backend entry point
-├─ assets/
-│   └─ icon.svg         # icon referenced from manifest
-├─ manifest.json        # metadata, contribution points, runtime config
-├─ README.md            # this file (copied to dist/ on build)
-└─ requirements.txt     # Python deps (auto-pinned to latest on build)
-```
-> ROS2 plugins additionally include a `ros2_ws/` directory.
----
-## Frontend (`ui/content.tsx`)
-### JavaScript dependencies
-`muscat-pk build` runs this plugin project's own Vite build. Vite resolves
-imports from installed `node_modules`; it does not care whether a package is
-listed under `dependencies` or `devDependencies`, but the package must be
-installed.
-Do not run a production-only install such as `npm install --omit=dev` before
-building the plugin UI, because build tools like `vite`, `typescript`,
-`tailwindcss`, `@tailwindcss/vite`, `sass`, or `less` are usually
-`devDependencies`.
-The scaffold keeps this split:
-| package kind | examples | why |
-|---|---|---|
-| `dependencies` | `@rainbow-robotics/plugin-ui`, UI libraries imported by plugin source | Author-facing APIs used by `ui/*.tsx` |
-| `devDependencies` | `vite`, `typescript`, `tailwindcss`, `@tailwindcss/vite`, `sass`, `less` | Build/dev tools needed before `dist/*.js` is produced |
-The built plugin ZIP does not include `package.json` or `node_modules`. For
-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.
-```tsx
-import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
-function App() {
-  const rb = useRb();
-}
-```
-### rb API
-| Method                                                                                                             | Description                                                                                                                                                |
-| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rb.pub(topic, payload)`                                                                                           | Publish a message to a topic                                                                                                                               |
-| `rb.sub(topic, handler)`                                                                                           | Subscribe to a topic — returns `{ undeclare() }`                                                                                                           |
-| `rb.action(topic, payload?)`                                                                                       | Send a request and await a reply                                                                                                                           |
-| `rb.serve(topic, handler)`                                                                                         | Handle incoming requests from the backend                                                                                                                  |
-| `rb.toast({ title?, message, type?, actionLabel?, handleActionClick?, closeOnActionClick?, duration?, onClose? })` | Show a host toast notification. `message` accepts a string or `ReactElement`. `type` can be `"info"`, `"danger"`, `"warning"`, `"caution"`, or `"success"` |
-| `rb.alert({ title?, message, buttonText? })`                                                                       | Show a host alert dialog. Resolves when the dialog is closed                                                                                               |
-| `rb.confirm({ title?, message, buttonText? })`                                                                     | Show a host confirmation dialog. `buttonText` accepts `{ yes, no }`. Resolves to `true` or `false`                                                         |
-| `rb.prompt({ title?, message, value?, placeholder?, buttonText? })`                                                | Show a host prompt dialog. `buttonText` accepts `{ yes, no }`. Resolves to the entered string or `undefined`                                               |
-Topic names passed to `pub`, `sub`, `action`, and `serve` are isolated per plugin.
-All methods support Generic Types:
-```tsx
-const status = await rb.action<{ ok: boolean }, { id: number }>(
-  "get-status",
-  { id: 1 },
-);
-const sub = await rb.sub<{ value: number }>("sensor/data", (data) => {
-  console.log(data.value);
-});
-sub.undeclare(); // cleanup
-const ok = await rb.confirm({
-  title: "Run",
-  message: "Start the backend action?",
-});
-if (ok) {
-  await rb.action("run");
-}
-```
-### Saving and restoring form data (`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.).
-```tsx
-import { useState } from "react";
-import { useRbFormData, useRbSave } from "@rainbow-robotics/plugin-ui/react";
-type GripArgs = { targetName: string; width: number };
-const DEFAULTS: GripArgs = { targetName: "", width: 20 };
-export default function App() {
-  // Previously-saved values, or undefined for a brand-new instance.
-  const saved = useRbFormData<GripArgs>();
-  const [args, setArgs] = useState<GripArgs>({ ...DEFAULTS, ...saved });
-  // Registers a getter the host calls when its Save button is clicked.
-  // Always returns the CURRENT values — re-registering on every render keeps
-  // the closure fresh, which useRbSave already handles for you.
-  useRbSave(() => ({
-    args,
-    summary: `${args.targetName || "target"} · ${args.width}mm`,
-  }));
-  return (/* ...form UI reading/writing `args`... */);
-}
-```
-The value returned from `useRbSave` must be JSON-serialisable — the host
-persists it as-is. Not every host embeds plugins in a save/restore form; if
-yours doesn't, you can skip these hooks entirely.
-### UI components
-Import Muscat components from `@rainbow-robotics/plugin-ui/react` and export a
-React component as the default export. The host mounts that component directly
-and provides `useRb()` through context.
-```tsx
-import { useState } from "react";
-import { RBLabelButton, RBSlider, RBSwitch } from "@rainbow-robotics/plugin-ui/react";
-import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
-export default function App() {
-  const rb = useRb();
-  const [width, setWidth] = useState(20);
-  const [enabled, setEnabled] = useState(true);
-  return (
-    <div className="flex flex-col gap-4">
-      <RBSlider
-        value={[width]}
-        min={0}
-        max={100}
-        onValueChange={(values: number[]) => setWidth(values[0] ?? 0)}
-      />
-      <RBSwitch checked={enabled} onCheckedChange={setEnabled} />
-      <RBLabelButton
-        disabled={!enabled}
-        onClick={() => rb.action("grip", { width })}
-      >
-        Grip
-      </RBLabelButton>
-    </div>
-  );
-}
-```
----
-## Developing directly on the robot PC
-If you're running `muscat-pk dev` **on the robot PC itself**, Muscat already serves the
-plugin gateway on port 10000. The CLI sees that, does not start its own local Muscat, and
-your plugin backend connects to the robot's gateway — exactly what you want when
-developing on the robot.
----
-## Backend runtimes
-`manifest.json` chooses one backend runtime. `muscat-pk dev` runs backend code in
-a Docker container matching the robot environment. Backend code should contain
-plugin logic only; it should not start its own copy of the plugin gateway.
-### Which backend pattern? (depends on the contribution point)
-**How you control the robot depends on what your plugin contributes** (see
-`manifest.json` → `contributes[].point`). Don't mix these up:
-| Contribution point | What it is | Backend pattern |
-| --- | --- | --- |
-| `program.panel` (with `commandInfo`) | Defines a **custom command** the plugin adds to the Program page's rule-based sequence builder. The operator places it into the program tree like any built-in command (Move J, Point, Wait, …); it runs when the program reaches that step. | **`PluginProgramContext`** — integrated with the program's stop/pause and variables. See _Program command backend_ below. |
-| `toolbar` / `lnb` / `move.panel` | A live UI panel/popover the operator interacts with directly | Call the robot **SDK directly** (`RBManipulateSDK`, `RBAmrSDK`) from `py/main.py`, or `rb.action(...)` → your backend → SDK. **Not** a program step — there is no stop/pause/variable context. |
-Rule of thumb: use `PluginProgramContext` **only** for a `program.panel` command
-that runs as part of a program. To move the robot live from a toolbar/move panel,
-use the SDK — a program-step context does not apply.
-### Frontend-only (`none`)
-Use this when the plugin only has UI and calls host services:
-```json
-{ "runtime": { "type": "none" } }
-```
-### Python
-Python plugins use `py/main.py` and can communicate with the UI through
-`rainbow.rb_sdk.RBPluginCall`.
-```python
-import time
-from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK, RBPluginCall
-plugin = RBPluginCall()
-plugin.publish("state", {"ready": True})
-@plugin.subscribe("event")
-def on_ui_event(payload=None):
-    print(payload)
-@plugin.serve("tool/echo")
-def echo(payload=None):
-    return {"echo": payload}
-def call_frontend():
-    res = plugin.call("tool/ping", payload={"hello": "plugin"})
-    print(res)
-def move_j_example():
-    amr = RBAmrSDK()
-    manipulate = RBManipulateSDK()
-    return manipulate.move.call_move_j(
-        robot_model="C500920",
-        target={"tar_values": [0, 0, 0, 0, 0, 0], "tar_frame": 0, "tar_unit": 0},
-    )
-if __name__ == "__main__":
-    while True:
-        time.sleep(1)
-```
-#### External endpoints (`plugin.router`)
-`plugin.serve` / `plugin.subscribe` / `plugin.publish` are **internal only** (plugin
-UI ↔ backend, plugin ↔ plugin). To expose an endpoint to the outside world —
-REST, Socket.IO, TCP, MQTT, WebRTC — use `plugin.router`. Declaring one is a
-single decorator; the running Muscat (`common`) picks it up without a restart,
-and it disappears when the plugin stops or is removed.
-> Requires a robot running `rainbow-rb-sdk` **0.0.9.dev5 or newer** (the SDK is
-> provided by the plugin container at runtime). On older robots `plugin.router`
-> does not exist and raises `AttributeError`.
-```python
-from rainbow.rb_sdk import RBPluginCall
-from rainbow.rb_sdk.plugin import PluginRouteError
-plugin = RBPluginCall()  # plugin_id comes from env RB_PLUGIN_ID
-@plugin.router.on("/hello")                                  # all 5 transports
-def hello(payload: dict, meta: dict):
-    return {"msg": f"hi {payload.get('name')}"}              # return value = response body
-@plugin.router.on("/admin", explicit_routes=["api"])         # REST only
-def admin(payload, meta):
-    if not (meta.get("principal") or {}).get("is_admin"):
-        raise PluginRouteError(403, "admin only")            # becomes the external status
-    ...
-@plugin.router.subscribe("/cmd", explicit_events=["tcp"])    # receive external TCP publish
-def on_cmd(payload: dict):
-    ...
-plugin.router.emit("/state", {"busy": True})                 # push to external subscribers
-```
-| API | Meaning | External address |
-| --- | --- | --- |
-| `router.on(path, explicit_routes=None)` | request/response handler | `common/plugin/{plugin_id}/{path}` (REST is always `POST`) |
-| `router.subscribe(topic, explicit_events=None)` | receive external publishes | external side publishes to `common/plugin/{plugin_id}/{topic}` |
-| `router.emit(topic, payload)` | plugin → external push | external side subscribes to `common/plugin/{plugin_id}/{topic}` |
-- The `plugin_id` prefix is added by the SDK — write only the path in plugin code.
-- Paths may have several segments (`/tool/echo`). Declaring the same path twice raises `ValueError`.
-- Transport names: `api | socket | tcp | mqtt | webrtc`. `subscribe` accepts only `tcp | mqtt | webrtc`. Unknown names raise `ValueError`.
-- `explicit_routes` / `explicit_events` of `None` means every transport. A request on a transport not listed gets 404.
-Handler contract:
-- Signature `(payload, meta)`, `(payload)` or `()` — only the arguments you declare are injected. Sync and async both work.
-- `payload`: what the caller sent (for REST: JSON body merged with query params). The shape is up to the plugin.
-- `meta`: `{"transport": "api"|"socket"|"tcp"|"mqtt"|"webrtc", "principal": dict | None}`. When the robot's login policy is on, `principal` holds the token subject. **Role checks are the plugin's job** — inspect `meta["principal"]` yourself.
-- The return value is the response body (must be JSON-serialisable). `None` → empty response.
-- Status codes: `raise PluginRouteError(code, message)`. Any other exception → 500 with `str(exc)` as the message.
-- `subscribe` handlers take `(payload)` only and return nothing.
-#### Calling plugin endpoints from outside
-| Transport | How |
-| --- | --- |
-| REST | `POST /common/plugin/{plugin_id}/{path}` (through the api-gateway), JSON body |
-| Socket.IO | emit event `common/plugin/{plugin_id}/{path}`, response arrives in the ack |
-| TCP | topic `common/plugin/{plugin_id}/{path}` request / publish |
-| MQTT | request: `common/plugin/{plugin_id}/{path}/__req__`, publish: `common/plugin/{plugin_id}/{topic}` |
-| WebRTC | data channel topic `common/plugin/{plugin_id}/{path}` |
-Auth: when the robot's login policy is on, a token is **required** (any role — GUEST passes). When it is off, calls go straight through. REST uses the same Bearer token as the other Muscat APIs.
-```bash
-curl -s -X POST http://<robot>/common/plugin/my-plugin/hello \
-  -H 'Content-Type: application/json' -d '{"name":"kim"}'
-```
-| Situation | Status |
-| --- | --- |
-| No plugin declares that path / plugin is down / transport not allowed | 404 |
-| Plugin did not answer within 10 s | 504 |
-| `common` ↔ gateway not connected | 503 |
-| Handler raised | 500 (`PluginRouteError` → its `code`) |
-Known limits:
-- A plugin path named `install` cannot be called over REST (`POST /common/plugin/{id}/install` is taken by the registry install route first). Socket/TCP are unaffected.
-- Swagger shows one catch-all route, not per-plugin paths.
-- The MQTT broker echoes to the sender: a plugin that `emit`s and `subscribe`s the same topic receives its own push over `mqtt`. Drop `mqtt` from `explicit_events` or use separate topics. (TCP is filtered by `sender_id`.)
-- `on` and `subscribe` may share a name — they live in separate tables.
-During `muscat-pk dev` the local Muscat runtime takes the `router.*` registrations
-on its gateway (port `10000`), and its `common` (port `3000`) routes
-`common/plugin/...` to them like on the robot — try
-`curl http://localhost:3000/common/plugin/<plugin-id>/<path>`. After restarting the plugin process,
-external calls may return 504 for up to about a minute (until the gateway notices
-the old socket is gone), then 404 — that is expected.
-#### Program command backend (`program.panel`)
-A `program.panel` contribution defines a **custom command** your plugin adds to
-the Muscat **Program page**, where the operator builds a robot program as a
-rule-based sequence (a program tree). Your command appears alongside the
-built-ins (Move J, Point, Wait, …); the operator places it into the tree, and
-each time the program executes that step the host calls your backend through
-`PluginProgramContext` — receiving the step args, checking for stop/pause,
-reading/writing program variables, and signalling completion. This pattern is
-**only** for `program.panel`; a toolbar/move-panel plugin uses the SDK directly
-instead (see the table above).
-```python
-"""
-Plugin backend main.py example (program.panel command).
-manifest.json:
-  "runtime": {"type": "python", "entry": "main.py"},
-  "contributes": [{
-    "point": "program.panel",
-    "ui": "program",
-    "label": {"en": "My Plugin Step"},
-    "commandInfo": {
-      "name": "My Plugin Step",
-      "icon": "assets/icon.svg",
-      "funcName": "rb_program_sdk.plugin_execute",
-      "args": {"message": "hello"}   # plugin-author-defined args
-    }
-  }]
-The host invokes commandInfo.funcName (rb_program_sdk.plugin_execute) with
-args.plugin_id + your args when the program reaches this step.
-"""
-import asyncio
-from rainbow.rb_sdk import PluginProgramContext
-ctx = PluginProgramContext(plugin_id="my-plugin")
-@ctx.on_execute
-async def handle(args: dict) -> None:
-    """Called once when my Step executes. Variable writes apply to the
-    running program immediately + broadcast to other robots' main tasks."""
-    count = await ctx.get_variable("counter")          # read an existing program variable
-    await ctx.set_variable("counter", count + 1)       # update an existing variable — allowed
-    await ctx.set_variable("RBP_TEST", 1)              # NEW variables must start with RBP_
-    for i in range(100):
-        await ctx.check_stop()   # auto-scoped to this Step's robot model
-        await asyncio.sleep(0.5)
-    await ctx.done()
-async def background_monitor() -> None:
-    """Resident task outside any Step. If no program is running,
-    get returns None and set is silently ignored — always safe to call."""
-    while True:
-        await asyncio.sleep(1.0)
-        # targets every running main task (no robot_model param — always broadcast)
-        await ctx.set_variable("RBP_TEST", 3)
-        # get options
-        v1 = await ctx.get_variable("counter")                           # first value found in the whole tree
-        v2 = await ctx.get_variable("counter", robot_model="C500920")    # a specific robot
-        v3 = await ctx.get_variable("RBP_TEST", plugin_id="my-plugin")   # the value my-plugin last wrote
-        if ctx.executor_state("C500920") == "paused":
-            print("C500920 program is paused")
-async def main() -> None:
-    asyncio.create_task(background_monitor())
-    await ctx.start()  # stays resident
-asyncio.run(main())
-```
-#### Program variables & executor state (`PluginProgramContext`)
-`rainbow.rb_sdk.PluginProgramContext` lets the plugin process interact with the
-running program (PyFM): read/write program variables and observe execution
-state — inside a Step handler or from a resident task, at any time.
-- The `on_execute` handler is called **only when PyFM executes this plugin's
-  Step**. One Step execution = one handler call, and the Step does not finish
-  until you call `ctx.done()` — always call it.
-- The plugin process itself stays resident after `ctx.start()`; executor state
-  queries and variable access below keep working whether or not a Step is
-  executing.
-#### Variable naming rules (important)
-PyFM variables are a **program-wide shared namespace**. One rule:
-- **Modifying an existing variable** — the name passes as-is. Exchanging
-  variables between the program and the plugin is the intended usage.
-- **Creating a variable that doesn't exist** — the `RBP_` prefix is
-  **required** (enforced by the SDK/server; a violation raises
-  `RuntimeError`). Applies equally inside and outside Step execution.
-For new variable names, a convention that includes the plugin id is strongly
-recommended:
-```
-RBP_{plugin_id}_{name}
-e.g. RBP_vision_detect_count, RBP_gripper_last_error
-```
-Why:
-- `RBP_` — instantly identifies plugin-created variables in the program
-  editor/UI.
-- `{plugin_id}` — **prevents name collisions with other plugins.** If two
-  plugins use the same name they overwrite the same variable (`RBP_` alone is
-  not something the SDK guards against).
-#### Reading / writing variables
-```python
-value = await ctx.get_variable("counter")                 # read (no name restriction)
-await ctx.set_variable("counter", value + 1)              # modify existing variable — allowed
-await ctx.set_variable("RBP_my-plugin_result", 42)        # create new variable — RBP_ required
-```
-`set_variable` always applies to **every running main task** (a plugin belongs
-to muscat, not to a specific robot — there is no `robot_model` parameter):
-| When | Own program | Other robots' main tasks |
-|---|---|---|
-| During own Step execution | via the control queryable — **immediate** | broadcast — each at its next Step boundary |
-| Outside a Step (resident task, …) | resident endpoint — next Step boundary | same |
-`get_variable` has options:
-```python
-await ctx.get_variable("counter")                          # search all main tasks (first value found)
-await ctx.get_variable("counter", robot_model="C500920")   # a specific robot's value
-await ctx.get_variable("RBP_TEST", plugin_id="A.plugin")   # the value that plugin last wrote
-```
-Caveats:
-- If no program is running, `set_variable` is **silently ignored** and
-  `get_variable` returns `None`. (`RuntimeError` is raised only for real
-  errors, like the `RBP_` violation on a new variable — the message is tagged
-  `[plugin:{id}]` with the offending plugin.)
-- Rarely, a write can be lost if it races the worker's variable flush
-  (lock-free read-modify-write). For important values, re-check and retry on
-  the next cycle.
-#### Per-plugin value storage (meta)
-Besides the shared value, each variable entry records which plugin last wrote
-what:
-```python
-# state_dict["variables"] — after A wrote 1 and B wrote 2
-"RBP_TEST": {
-    "value": 2,                                # shared slot = last written value
-    "type": "local",
-    "meta": {"writers": {"A.plugin": 1, "B.plugin": 2}},   # per-plugin record
-}
-```
-So the exact value is recoverable even when names collide:
-- Plugin SDK: `ctx.get_variable("RBP_TEST", plugin_id="A.plugin")` → `1`
-- Program step expression: `COUNT = get_var("A.plugin", "RBP_TEST") + 1` → `2`
-- A plain name (`RBP_TEST += 1`) uses the shared slot (last written value) → `3`
-#### Executor state
-Subscribes to the `muscat/executor/state` publish (0.8 s interval) and exposes
-per-robot-model state:
-```python
-ctx.executor_state("C500920")   # "running" | "paused" | "waiting" | ... | None
-ctx.executor_state()            # {"C500920": "paused", "amr": "running"}
-ctx.is_paused("C500920")        # whether that model is paused
-ctx.is_stopped("C500920")       # stop/error transition of a model seen active this run
-```
-- States: `idle | running | paused | waiting | stopped | post_start | completed | error`
-- A model with no running task is `None` / absent from the dict.
-- The publish interval is 0.8 s, so expect up to ~1 s of latency.
-- With `IS_DEV=true` there is no publish at all — always `None`.
-To get a callback at the moment the state changes, without polling:
-```python
-@ctx.on_executor_state_change
-async def on_change(robot_model: str, state: str) -> None:
-    if state == "paused":
-        print(f"{robot_model} paused")
-```
-- Not called for repeated publishes of the same state — fires exactly once
-  per per-model state change.
-- An exception in the handler is only logged; state tracking keeps running.
-#### Responding to pause / stop
-```python
-@ctx.on_execute
-async def handle(args: dict) -> None:
-    for i in range(100):
-        # stop → CancelledError (propagated to the executor as a stop),
-        # pause → waits here until resumed.
-        # Inside on_execute this automatically watches only the robot model
-        # executing this Step.
-        await ctx.check_stop()
-        ...  # actual work
-        await asyncio.sleep(0.5)
-    await ctx.done()
-```
-Scope priority for `check_stop` / `is_paused` / `is_stopped`:
-1. `robot_model` given — that model only
-2. Omitted inside `on_execute` — **only the model executing this Step**
-   (passed in by the executor)
-3. Omitted elsewhere (resident task, …) — all models
-A handler doing long-running work must call `check_stop()` every loop
-iteration so it reacts to pause/stop immediately. Without it, the plugin keeps
-running even after the operator presses Stop.
-Variables your plugin wants the Program page variable picker to offer must be
-pre-declared in `manifest.json` under `"variables"` (see the manifest section
-below).
-### C++
-C++ plugins use `cpp/` and are built with CMake inside Docker against the
-Rainbow Robotics C++ SDK (see _C++ SDK_ below).
-```cpp
-#include <chrono>
-#include <cstdlib>
-#include <iostream>
-#include <string>
-#include <thread>
-int main() {
-  const char* plugin_id = std::getenv("RB_PLUGIN_ID");
-  std::cout << "[__PLUGIN_NAME__] backend ready"
-            << (plugin_id ? std::string(" (id=") + plugin_id + ")" : "")
-            << std::endl;
-  while (true) {
-    std::this_thread::sleep_for(std::chrono::seconds(1));
-  }
-  return 0;
-}
-```
-#### C++ SDK (`rainbow-rb-sdk-dev`)
-Both C++ runtimes (`cpp`, `ros2` + `rclcpp`) link the Rainbow Robotics C++ SDK
-from the apt package `rainbow-rb-sdk-dev`. The `muscat-pk` dev containers already
-have it, so `muscat-pk dev` / `build` need nothing extra. To build outside the
-container (your own Ubuntu 24.04 machine, or the robot PC):
-```bash
-curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/rb-sdk-apt.gpg
-echo 'deb [signed-by=/usr/share/keyrings/rb-sdk-apt.gpg] https://rainbowrobotics.github.io/rb-sdk stable main' | sudo tee /etc/apt/sources.list.d/rb-sdk.list
-sudo apt update && sudo apt install rainbow-rb-sdk-dev
-```
-- CMake: `find_package(rb_sdk REQUIRED)` + `target_link_libraries(<target> rb_sdk::rb_sdk)` (C++20). pkg-config: `rb_sdk`.
-- Headers: `<rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>` (`RBManipulateSDK`),
-  `<rainbow/rb_sdk/program/plugin_program_context.hpp>` (`rb_plugin::PluginProgramContext`, for `program.panel` commands — the header's top comment has a full `main()` example).
-- The binary is linked **dynamically**; `muscat-pk build` copies the matching `librb_sdk.so` into `dist/<arch>/lib/` (the robot has no SDK installed), so each plugin keeps the SDK version it was built with. The version is the one pinned in `CMakeLists.txt` (`find_package(rb_sdk <version> EXACT REQUIRED)`); change it with `muscat-pk sdk update <version>`.
-- UI ↔ backend messaging works from C++ too: `rb_plugin::RBPluginCall` in `<rainbow/rb_sdk/plugin/rb_plugin.hpp>` (see the scaffolded `cpp/main.cpp`).
-### ROS2 (rclpy)
-ROS2 Python plugins use `ros2_ws/` with `runtime.rosClient: "rclpy"`. relative topic names are placed under the plugin's ROS namespace — the plugin id
-with "." → "/" and "-" → "_" (`com.example.my-plugin` → `/com/example/my_plugin`), in dev
-and on the robot. Use an absolute name (`/cmd_vel`) for topics shared with other nodes.
-`RBPluginCall` works in the node module too (UI messaging and `plugin.router`).
-```python
-# ros2_ws/src/__PLUGIN_SLUG__/__PLUGIN_SLUG__/node.py
-import rclpy
-from rclpy.node import Node
-from rainbow.rb_sdk import RBManipulateSDK
-sdk = RBManipulateSDK()
-class __PLUGIN_CLASS__Node(Node):
-    def __init__(self):
-        super().__init__("__PLUGIN_SLUG___node")
-        self.get_logger().info("__PLUGIN_NAME__ node started")
-        # use sdk alongside ROS2 publishers/subscribers/services as needed
-```
-#### Talking to an external PC over ROS 2
-ROS 2 discovery stays on the robot (`ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST`; `muscat-pk dev`
-runs the same), so robots on one LAN don't mix topics. Allow specific PCs from the plugin UI —
-Muscat keeps the list per plugin, starts your backend with `ROS_STATIC_PEERS` set to it, and
-restarts the plugin when it changes. Your ROS code needs no changes; the PC needs no extra settings.
-```tsx
-const rb = useRb();
-const peers = await rb.rosPeers.get();               // ["192.168.0.50"]
-await rb.rosPeers.set(["192.168.0.50", "192.168.0.51"]); // saves + restarts the plugin; rejects on a bad IP
-```
-- Per plugin: plugin B keeps its allowed PCs when plugin A (allowing the same PC) is stopped or removed.
-- It opens communication; it is not access control — a PC that knows the robot's IP can still
-  add the robot to its own `ROS_STATIC_PEERS`.
-- In `muscat-pk dev` the list is kept in `.muscat-dev/ros-peers.json` (ROS 2 backends).
-### ROS2 (rclcpp)
-ROS2 C++ plugins use `ros2_ws/` with `runtime.rosClient: "rclcpp"`. The node links
-the Rainbow C++ SDK the same way as the `cpp` runtime (see _C++ SDK_ above).
-```cpp
-#include "rclcpp/rclcpp.hpp"
-class __PLUGIN_CLASS__Node : public rclcpp::Node {
-public:
-  __PLUGIN_CLASS__Node() : Node("__PLUGIN_SLUG___node") {
-    RCLCPP_INFO(this->get_logger(), "__PLUGIN_NAME__ node started");
-  }
-};
-```
----
-## Video streaming (MediaMTX)
-Muscat runs a MediaMTX media server. The backend publishes a stream over RTSP and
-the UI plays it over WebRTC. `muscat-pk dev` runs the same server (or uses a local
-Muscat's), so the addresses are identical in dev and on the robot.
-| | Address |
-| --- | --- |
-| Publish (backend) | `rtsp://127.0.0.1:8554/<plugin_id>/<name>` |
-| Play (UI) | `http://<host>:8889/<plugin_id>/<name>/` |
-- Prefix the path with your plugin id — paths are shared with robot cameras and other plugins.
-- The robot runtime has no ffmpeg, GStreamer or OpenCV; bring your own encoder (below).
-**Backend (Python)** — use PyAV: add `av` and `numpy` to `requirements.txt`. Its wheels
-include FFmpeg, so they ship in the ZIP like any other dependency.
-```python
-import fractions, time
-import av, numpy as np
-out = av.open("rtsp://127.0.0.1:8554/__PLUGIN_ID__/cam", mode="w", format="rtsp",
-              options={"rtsp_transport": "tcp"})
-stream = out.add_stream("libx264", rate=25, options={"preset": "ultrafast", "tune": "zerolatency"})
-stream.width, stream.height, stream.pix_fmt = 640, 360, "yuv420p"
-i = 0
-while True:
-    img = np.zeros((360, 640, 3), dtype=np.uint8)          # your RGB frame here
-    frame = av.VideoFrame.from_ndarray(img, format="rgb24")
-    frame.pts, frame.time_base = i, fractions.Fraction(1, 25)
-    for packet in stream.encode(frame):
-        out.mux(packet)
-    i += 1
-    time.sleep(1 / 25)
-```
-Run the encoder loop in a thread (or `asyncio.to_thread`) so it doesn't block the
-`RBPluginCall` handlers.
-**UI** — embed MediaMTX's WebRTC player. `location.hostname` is `localhost` in the
-preview and the robot's address on the robot:
-```tsx
-const STREAM = "__PLUGIN_ID__/cam"; // the path the backend publishes
-export default function Camera() {
-  return (
-    <iframe
-      src={`${location.protocol}//${location.hostname}:8889/${STREAM}/`}
-      allow="autoplay"
-      className="aspect-video w-full border-0"
-    />
-  );
-}
-```
----
-## manifest.json
-```jsonc
-{
-  // unique plugin ID — reverse-domain format recommended
-  "id": "com.example.my-plugin",
-  "name": "My Plugin",
-  "version": "1.0.0",
-  // minimum Muscat version required to load this plugin
-  "minMuscatVersion": "1.0.0",
-  // plugin author (empty string is fine)
-  "author": "Your Name",
-  // displayed in the Muscat plugin store / info panel
-  // string or { en (required), ko, ja, zh, vi, th, es }
-  "description": { "en": "Plugin description", "ko": "플러그인 설명" },
-  // SVG string (single file) or PNG/JPG size map (all three sizes required)
-  "icons": "assets/icon.svg",
-  // "icons": { "16": "assets/icon-16.png", "48": "assets/icon-48.png", "128": "assets/icon-128.png" },
-  // targetModels and/or targetCategorys — at least one is required
-  // "all" = every target, or list specific values
-  "targetModels": "all",
-  // "targetModels": ["C500920", "C500930"],
-  "targetCategorys": "all",
-  // "targetCategorys": ["manipulate", "amr", "rby1", "vision"],
-  "contributes": [
-    // program.panel — defines a custom command for the Program page sequence
-    //   builder; runs via PluginProgramContext when the program reaches it
-    {
-      "point": "program.panel",
-      "icon": "assets/icon.svg",
-      "label": { "ko": "내 플러그인", "en": "My Plugin" },
-      "ui": "program",           // must be unique across all contributions
-      "commandInfo": {
-        "name": "My Plugin",
-        "icon": "assets/icon.svg",
-        "funcName": "rb_program_sdk.plugin_execute",
-        "args": {}
-      }
-    },
-    // toolbar — adds a button to the top toolbar (required)
-    {
-      "point": "toolbar",
-      "icon": "assets/icon.svg",
-      "label": { "ko": "내 플러그인", "en": "My Plugin" },
-      "ui": "content",           // must be unique across all contributions
-      "opens": "popover"         // popover | panel | page
-    },
-    // move.panel — adds a panel to the Move screen
-    {
-      "point": "move.panel",
-      "icon": "assets/icon.svg",
-      "label": { "ko": "내 플러그인", "en": "My Plugin" },
-      "ui": "move"               // must be unique across all contributions
-    }
-  ],
-  // optional: variables this plugin exposes to pyfm programs — the Program
-  // page variable picker lists ONLY declared variables. name must start with
-  // RBP_; description is optional but without it the UI can't explain the
-  // variable, so write one.
-  "variables": [
-    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘", "en": "Gripper force" } },
-    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
-  ],
-  // runtime — one of:
-  //   { "type": "none" }
-  //   { "type": "python", "entry": "main.py" }
-  //   { "type": "cpp", "entry": "<executable name>" }
-  //   { "type": "ros2", "rosClient": "rclpy" | "rclcpp", "package": "...", "launch": "..._node" }
-  "runtime": { "type": "python", "entry": "main.py" },
-  // optional: TCP ports opened by this plugin backend
-  // only number[] is allowed; ranges/objects are not accepted
-  // external plugin ports must be within 28600-28999
-  "ports": [28600]
-}
-```
-**Backend types:**
-| type | source dir | build / run | entry |
-|---|---|---|---|
-| `python` | `py/` | pip + run in Docker | `main.py` |
-| `cpp` | `cpp/` | CMake in Docker | built executable name |
-| `ros2` (rclpy) | `ros2_ws/` | colcon (ament_python) in Docker | — |
-| `ros2` (rclcpp) | `ros2_ws/` | colcon (ament_cmake) in Docker | — |
-> Every back end runs in a Docker container matching the robot (Ubuntu 24.04 + Python 3.12), so dev behaves like production and compiled binaries are ABI-compatible. **Docker is required** for all backend types (only a frontend-only `none` plugin skips it). No local Python/toolchain setup is needed.
-**Contribution points:**
-| point | Where it appears | Backend | `commandInfo` |
-|---|---|---|:---:|
-| `toolbar` | Top toolbar button (must have at least one) | SDK / `rb.action` | — |
-| `lnb` | Left navigation entry | SDK / `rb.action` | — |
-| `move.panel` | Move screen panel | SDK / `rb.action` | — |
-| `program.panel` | Custom command in the Program page sequence builder | `PluginProgramContext` | ✓ |
-**`commandInfo` fields** (for `program.panel`):
-| field | type | description |
-|---|---|---|
-| `name` | `string` | Display name of the command in the program tree |
-| `icon` | `string` | Icon path |
-| `iconClassName` | `string?` | Optional CSS class for the icon |
-| `funcName` | `string?` | Backend function name to call |
-| `args` | `Record<string, any>?` | Default arguments |
-| `disabled` | `boolean?` | Whether the node is disabled |
-| `allowChildren` | `string[]?` | Allowed child commands |
-| `allowParents` | `string[]?` | Allowed parent commands |
-| `notAllowChildren` | `string[]?` | Disallowed child commands |
-| `syncGroupId` | `boolean?` | Sync group ID across children |
-| `disableCopy` | `boolean?` | Prevent copy |
-| `disableDelete` | `boolean?` | Prevent delete |
-| `requireChildren` | `boolean?` | Whether a child command is required |
-| `requireParent` | `boolean?` | Whether a parent command is required |
-| `childrenCommand` | `string?` | Default command type for children |
-**Validation rules:**
-- `id`, `name`, `version`, `minMuscatVersion` — required non-empty strings
-- `author` — required non-empty string
-- `description` — required (`string` or `{ en (required), ko?, ja?, zh?, vi?, th?, es? }`)
-- `icons` — SVG: single string path ending in `.svg`; PNG/JPG: object with `"16"`, `"48"`, `"128"` all present
-- `targetModels` — `"all"` or a non-empty array of robot model ID strings (at least one of `targetModels` / `targetCategorys` required)
-- `targetCategorys` — `"all"` or a non-empty array of `"manipulate" | "amr" | "rby1" | "vision"` (at least one of `targetModels` / `targetCategorys` required)
-- `contributes` — the plugin's screens; when present it must contain at least one `toolbar` entry. Leave it out (or `[]`) for a backend-only plugin: no UI is built, and Node.js is not needed to build it
-- `ui` — each contribution must have a unique value
-- `commandInfo` — required when `point` is `"program.panel"`
-- `ports` — optional `number[]`; every port must be within `28600-28999`
-  and must not be a reserved robot/industrial/internal port
-- `variables` — optional array of `{ name, type, init, description? }`:
-  - `name` — must start with `RBP_`, then letters/digits/underscore; unique per plugin
-  - `type` — `"number" | "string" | "array"`
-  - `init` — required initial value, must match `type`
-  - `description` — optional `string` or i18n object (`en` required in object form)
-`muscat-pk build` throws on any validation error. `muscat-pk dev` prints
-warnings — except `variables` errors (e.g. a name without the `RBP_` prefix),
-which are hard errors in `dev` / `dev:back` too.
-**Backend port rules:**
-- Declare a port only if your backend opens a TCP server/listener.
-- **Every listening TCP port must be declared.** `muscat-pk dev` and
-  `muscat-pk dev:back` watch the backend and stop it the moment it opens a port
-  that is not in `ports`. A port outside `28600-28999` can't be declared, so it
-  must not be opened either — picking e.g. `5500` is not a way around the rule.
-  It would escape this check *and* the robot's install-time conflict check, and
-  only collide once it's running on a robot.
-- Reserved ports include `502`, `2222`, `4840`, `5170-5179`, `8000-8999`,
-  `10000`, `30004`, `34964`, `44818`, `50000-50005`, and `50051`.
-- The robot rejects installation (HTTP 409) if a declared port is reserved,
-  out of range, or already claimed by another enabled plugin.
-**Reaching your backend's ports during development:**
-- Declared ports are published to `127.0.0.1` on your machine, so
-  `curl http://127.0.0.1:28600` works from the host on macOS, Windows, and Linux.
-- On native Linux the dev container uses host networking, so the ports are on
-  the host already.
-- If a declared port is already taken on your machine, `muscat-pk dev` warns and
-  skips publishing that one — the backend still listens inside the container.
----
-## Localized documentation
-You can ship per-language README files alongside the main `README.md`. Place them in the project root:
-```
-README.md        # default / English fallback
-README.ko.md     # Korean
-README.en.md     # explicit English (optional)
-README.ja.md     # Japanese
-```
-All `README*.md` files found at the project root are automatically copied to `dist/` on
-`muscat-pk build`. Muscat displays the file matching the user's locale,
-falling back to `README.md` if none matches.
----
-## Installing Python dependencies
-Add any package with an optional version pin to `requirements.txt`:
-```
-rainbow-rb-sdk
-rainbow-rb-flat-buffers
-numpy==1.26.4
-opencv-python
-```
-Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically
-inside the dev container (`pip install -r requirements.txt`) on every startup. No
-local Python is required for this.
-`muscat-pk dev:back` also best-effort creates/refreshes a local `.venv` in the
-background (via `uv` if available, else your system Python) with the same deps —
-purely so your editor (pylint, pyright, mypy, ...) can resolve imports and lint
-correctly. It's not used to run the backend; Docker is the actual execution
-environment, so this step is silently skipped if no local Python toolchain is
-available. Point your editor's Python interpreter at `.venv`.
-`muscat-pk sdk update` also refreshes `.venv` in place if one already exists, so
-your editor picks up the new `rainbow-rb-sdk` version immediately.
-> `muscat-pk build` only **pins** versions in `requirements.txt` — it does not run `pip install` (the robot installs them at load time).
----
-## Switching backend type
-```bash
-muscat-pk type change                 # interactive
-muscat-pk type change --to cpp        # → C++
-muscat-pk type change --to ros2       # → ROS2 (rclpy / Python)
-muscat-pk type change --to ros2-cpp   # → ROS2 (rclcpp / C++)
-muscat-pk type change --to python     # → Python
-```
-> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
-> Switching between a Python and a C++ backend asks whether to replace this README with the matching one (the old file is kept as `README.md.bak`). Add `--readme` to answer yes without the prompt.
----
-## AI coding assistants (MCP)
-If you build your plugin with an AI assistant (Claude Code, Codex, …), give it
-grounded knowledge of the Muscat UI components, design tokens, and SDK instead of
-letting it guess. `muscat-pk mcp` is an MCP server exposing:
-- `list_components` / `get_component_props` / `get_component_example` — every
-  `@rainbow-robotics/plugin-ui/react` component with its real props and a working
-  Storybook example.
-- `list_design_tokens` / `search_design_tokens` — the Tailwind classes to use
-  (`bg-bg-*`, `text-fg-*`, `typo-*`, …) so your UI matches the host theme.
-- `search_rb_sdk` — how to use `useRb()`, `rb.*`, `useRbFormData`/`useRbSave`, and
-  the backend runtimes.
-- `list_rb_sdk` / `get_rb_sdk_api` — the installed `rainbow-rb-sdk` (Python
-  backend) classes and signatures; with `lang: "cpp"`, the C++ SDK headers
-  (`rainbow-rb-sdk-dev`, read out of the `muscat-pk` cpp dev image — build it
-  once with `muscat-pk dev:back`).
-**Browse the components live** with `muscat-pk storybook`.
-`muscat-pk new` also writes `AGENTS.md` (read by Codex, Cursor, Gemini CLI, Copilot)
-and a `CLAUDE.md` that imports it: the UI rules (plugin-ui components instead of
-native `<select>`/`<input>`/`<button>`, design tokens for colors) for assistants that
-do not call the MCP tools on their own. Add your own project notes there.
-### Register the server
-**Claude Code** — a `.mcp.json` is already scaffolded at your plugin root, so
-it works out of the box:
-```json
-{
-  "mcpServers": {
-    "muscat": {
-      "command": "muscat-pk",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-**Codex** — register once with:
-```bash
-muscat-pk mcp --install codex
-```
-This appends the server to `~/.codex/config.toml` (idempotent — safe to run
-again). Equivalent manual config:
-```toml
-[mcp_servers.muscat]
-command = "muscat-pk"
-args = ["mcp"]
-```
-Any other MCP client works too — it's a standard stdio MCP server started with
-`muscat-pk mcp`. If `muscat-pk` isn't on the client's PATH, use its absolute path
-(`which muscat-pk`) as `command`.
----
-## Shipping
-```bash
-muscat-pk build            # build + ZIP
-muscat-pk build --no-zip   # build only, no ZIP
-```
-> Building the other arch (e.g. arm64 on an amd64 PC) runs in an emulated container for
-> C++ backends. Docker Desktop has it built in; on Linux enable it once with
-> `docker run --privileged --rm tonistiigi/binfmt --install all`, or pass `--arch` for one arch.
-- Builds `ui/content.tsx` → `dist/content.js` (minified)
-- Pins `requirements.txt` to latest versions (stable-only on `main` branch)
-- Copies `assets/`, `manifest.json`, `README*.md`, `py/`, and `requirements.txt` into `dist/`
-- ROS2: runs `colcon build` inside the Jazzy container; includes `ros2_ws/install/`
-- Output: `__PLUGIN_DIR__-{version}.zip`
-ZIP layout:
-```
-__PLUGIN_DIR__-1.0.0.zip
-├─ dist/
-│   ├─ content.js        # built UI
-│   ├─ manifest.json
-│   ├─ assets/
-│   ├─ README.md
-│   ├─ README.ko.md      # if present
-│   ├─ main.py           # from py/
-│   └─ requirements.txt  # pinned
-└─ ros2_ws/install/      # ROS2 only
-```
----
-## All commands
-```bash
-muscat-pk dev        # UI + backend
-muscat-pk dev:ui     # UI preview only (preview-host)
-muscat-pk dev:back   # backend only (Python: watchfiles / ROS2: Docker)
-muscat-pk build      # build → dist/ + distributable ZIP (--no-zip to skip)
-muscat-pk storybook  # browse the rb-components UI library in a browser
-muscat-pk mcp        # MCP server for AI assistants (components/tokens/SDK docs)
-```
-```bash
-muscat-pk type change    # switch backend type
-muscat-pk sdk list       # show current Python SDK version
-muscat-pk sdk update     # update Python SDK to latest
-muscat-pk update         # update muscat-plugin-kit itself
-muscat-pk uninstall      # remove muscat-pk itself
-```
+# __PLUGIN_NAME__
+A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
+## Quick start
+```bash
+muscat-pk dev        # UI preview + backend together
+muscat-pk dev:ui     # UI preview only
+muscat-pk dev:back   # backend only (Python watchfiles / ROS2 Docker)
+muscat-pk build      # build + distributable ZIP
+```
+---
+## Project structure
+```
+__PLUGIN_DIR__/
+├─ ui/
+│   ├─ content.tsx      # plugin UI entry point
+│   └─ style.css        # plugin styles auto-loaded by muscat()
+├─ py/
+│   └─ main.py          # Python backend entry point
+├─ assets/
+│   └─ icon.svg         # icon referenced from manifest
+├─ manifest.json        # metadata, contribution points, runtime config
+├─ README.md            # this file (copied to dist/ on build)
+└─ requirements.txt     # Python deps (auto-pinned to latest on build)
+```
+> ROS2 plugins additionally include a `ros2_ws/` directory.
+---
+## Frontend (`ui/content.tsx`)
+### JavaScript dependencies
+`muscat-pk build` runs this plugin project's own Vite build. Vite resolves
+imports from installed `node_modules`; it does not care whether a package is
+listed under `dependencies` or `devDependencies`, but the package must be
+installed.
+Do not run a production-only install such as `npm install --omit=dev` before
+building the plugin UI, because build tools like `vite`, `typescript`,
+`tailwindcss`, `@tailwindcss/vite`, `sass`, or `less` are usually
+`devDependencies`.
+The scaffold keeps this split:
+| package kind | examples | why |
+|---|---|---|
+| `dependencies` | `@rainbow-robotics/plugin-ui`, UI libraries imported by plugin source | Author-facing APIs used by `ui/*.tsx` |
+| `devDependencies` | `vite`, `typescript`, `tailwindcss`, `@tailwindcss/vite`, `sass`, `less` | Build/dev tools needed before `dist/*.js` is produced |
+The built plugin ZIP does not include `package.json` or `node_modules`. For
+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.
+```tsx
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+function App() {
+  const rb = useRb();
+}
+```
+### rb API
+| Method                                                                                                             | Description                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rb.pub(topic, payload)`                                                                                           | Publish a message to a topic                                                                                                                               |
+| `rb.sub(topic, handler)`                                                                                           | Subscribe to a topic — returns `{ undeclare() }`                                                                                                           |
+| `rb.action(topic, payload?)`                                                                                       | Send a request and await a reply                                                                                                                           |
+| `rb.serve(topic, handler)`                                                                                         | Handle incoming requests from the backend                                                                                                                  |
+| `rb.toast({ title?, message, type?, actionLabel?, handleActionClick?, closeOnActionClick?, duration?, onClose? })` | Show a host toast notification. `message` accepts a string or `ReactElement`. `type` can be `"info"`, `"danger"`, `"warning"`, `"caution"`, or `"success"` |
+| `rb.alert({ title?, message, buttonText? })`                                                                       | Show a host alert dialog. Resolves when the dialog is closed                                                                                               |
+| `rb.confirm({ title?, message, buttonText? })`                                                                     | Show a host confirmation dialog. `buttonText` accepts `{ yes, no }`. Resolves to `true` or `false`                                                         |
+| `rb.prompt({ title?, message, value?, placeholder?, buttonText? })`                                                | Show a host prompt dialog. `buttonText` accepts `{ yes, no }`. Resolves to the entered string or `undefined`                                               |
+Topic names passed to `pub`, `sub`, `action`, and `serve` are isolated per plugin.
+All methods support Generic Types:
+```tsx
+const status = await rb.action<{ ok: boolean }, { id: number }>(
+  "get-status",
+  { id: 1 },
+);
+const sub = await rb.sub<{ value: number }>("sensor/data", (data) => {
+  console.log(data.value);
+});
+sub.undeclare(); // cleanup
+const ok = await rb.confirm({
+  title: "Run",
+  message: "Start the backend action?",
+});
+if (ok) {
+  await rb.action("run");
+}
+```
+### Saving and restoring form data (`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.).
+```tsx
+import { useState } from "react";
+import { useRbFormData, useRbSave } from "@rainbow-robotics/plugin-ui/react";
+type GripArgs = { targetName: string; width: number };
+const DEFAULTS: GripArgs = { targetName: "", width: 20 };
+export default function App() {
+  // Previously-saved values, or undefined for a brand-new instance.
+  const saved = useRbFormData<GripArgs>();
+  const [args, setArgs] = useState<GripArgs>({ ...DEFAULTS, ...saved });
+  // Registers a getter the host calls when its Save button is clicked.
+  // Always returns the CURRENT values — re-registering on every render keeps
+  // the closure fresh, which useRbSave already handles for you.
+  useRbSave(() => ({
+    args,
+    summary: `${args.targetName || "target"} · ${args.width}mm`,
+  }));
+  return (/* ...form UI reading/writing `args`... */);
+}
+```
+The value returned from `useRbSave` must be JSON-serialisable — the host
+persists it as-is. Not every host embeds plugins in a save/restore form; if
+yours doesn't, you can skip these hooks entirely.
+### UI components
+Import Muscat components from `@rainbow-robotics/plugin-ui/react` and export a
+React component as the default export. The host mounts that component directly
+and provides `useRb()` through context.
+```tsx
+import { useState } from "react";
+import { RBLabelButton, RBSlider, RBSwitch } from "@rainbow-robotics/plugin-ui/react";
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+export default function App() {
+  const rb = useRb();
+  const [width, setWidth] = useState(20);
+  const [enabled, setEnabled] = useState(true);
+  return (
+    <div className="flex flex-col gap-4">
+      <RBSlider
+        value={[width]}
+        min={0}
+        max={100}
+        onValueChange={(values: number[]) => setWidth(values[0] ?? 0)}
+      />
+      <RBSwitch checked={enabled} onCheckedChange={setEnabled} />
+      <RBLabelButton
+        disabled={!enabled}
+        onClick={() => rb.action("grip", { width })}
+      >
+        Grip
+      </RBLabelButton>
+    </div>
+  );
+}
+```
+---
+## Developing directly on the robot PC
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat already serves the
+plugin gateway on port 10000. The CLI sees that, does not start its own local Muscat, and
+your plugin backend connects to the robot's gateway — exactly what you want when
+developing on the robot.
+---
+## Backend runtimes
+`manifest.json` chooses one backend runtime. `muscat-pk dev` runs backend code in
+a Docker container matching the robot environment. Backend code should contain
+plugin logic only; it should not start its own copy of the plugin gateway.
+### Which backend pattern? (depends on the contribution point)
+**How you control the robot depends on what your plugin contributes** (see
+`manifest.json` → `contributes[].point`). Don't mix these up:
+| Contribution point | What it is | Backend pattern |
+| --- | --- | --- |
+| `program.panel` (with `commandInfo`) | Defines a **custom command** the plugin adds to the Program page's rule-based sequence builder. The operator places it into the program tree like any built-in command (Move J, Point, Wait, …); it runs when the program reaches that step. | **`PluginProgramContext`** — integrated with the program's stop/pause and variables. See _Program command backend_ below. |
+| `toolbar` / `lnb` / `move.panel` | A live UI panel/popover the operator interacts with directly | Call the robot **SDK directly** (`RBManipulateSDK`, `RBAmrSDK`) from `py/main.py`, or `rb.action(...)` → your backend → SDK. **Not** a program step — there is no stop/pause/variable context. |
+Rule of thumb: use `PluginProgramContext` **only** for a `program.panel` command
+that runs as part of a program. To move the robot live from a toolbar/move panel,
+use the SDK — a program-step context does not apply.
+### Frontend-only (`none`)
+Use this when the plugin only has UI and calls host services:
+```json
+{ "runtime": { "type": "none" } }
+```
+### Python
+Python plugins use `py/main.py` and can communicate with the UI through
+`rainbow.rb_sdk.RBPluginCall`.
+```python
+import time
+from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK, RBPluginCall
+plugin = RBPluginCall()
+plugin.publish("state", {"ready": True})
+@plugin.subscribe("event")
+def on_ui_event(payload=None):
+    print(payload)
+@plugin.serve("tool/echo")
+def echo(payload=None):
+    return {"echo": payload}
+def call_frontend():
+    res = plugin.call("tool/ping", payload={"hello": "plugin"})
+    print(res)
+def move_j_example():
+    amr = RBAmrSDK()
+    manipulate = RBManipulateSDK()
+    return manipulate.move.call_move_j(
+        robot_model="C500920",
+        target={"tar_values": [0, 0, 0, 0, 0, 0], "tar_frame": 0, "tar_unit": 0},
+    )
+if __name__ == "__main__":
+    while True:
+        time.sleep(1)
+```
+#### External endpoints (`plugin.router`)
+`plugin.serve` / `plugin.subscribe` / `plugin.publish` are **internal only** (plugin
+UI ↔ backend, plugin ↔ plugin). To expose an endpoint to the outside world —
+REST, Socket.IO, TCP, MQTT, WebRTC — use `plugin.router`. Declaring one is a
+single decorator; the running Muscat (`common`) picks it up without a restart,
+and it disappears when the plugin stops or is removed.
+> Requires a robot running `rainbow-rb-sdk` **0.0.9.dev5 or newer** (the SDK is
+> provided by the plugin container at runtime). On older robots `plugin.router`
+> does not exist and raises `AttributeError`.
+```python
+from rainbow.rb_sdk import RBPluginCall
+from rainbow.rb_sdk.plugin import PluginRouteError
+plugin = RBPluginCall()  # plugin_id comes from env RB_PLUGIN_ID
+@plugin.router.on("/hello")                                  # all 5 transports
+def hello(payload: dict, meta: dict):
+    return {"msg": f"hi {payload.get('name')}"}              # return value = response body
+@plugin.router.on("/admin", explicit_routes=["api"])         # REST only
+def admin(payload, meta):
+    if not (meta.get("principal") or {}).get("is_admin"):
+        raise PluginRouteError(403, "admin only")            # becomes the external status
+    ...
+@plugin.router.subscribe("/cmd", explicit_events=["tcp"])    # receive external TCP publish
+def on_cmd(payload: dict):
+    ...
+plugin.router.emit("/state", {"busy": True})                 # push to external subscribers
+```
+| API | Meaning | External address |
+| --- | --- | --- |
+| `router.on(path, explicit_routes=None)` | request/response handler | `common/plugin/{plugin_id}/{path}` (REST is always `POST`) |
+| `router.subscribe(topic, explicit_events=None)` | receive external publishes | external side publishes to `common/plugin/{plugin_id}/{topic}` |
+| `router.emit(topic, payload)` | plugin → external push | external side subscribes to `common/plugin/{plugin_id}/{topic}` |
+- The `plugin_id` prefix is added by the SDK — write only the path in plugin code.
+- Paths may have several segments (`/tool/echo`). Declaring the same path twice raises `ValueError`.
+- Transport names: `api | socket | tcp | mqtt | webrtc`. `subscribe` accepts only `tcp | mqtt | webrtc`. Unknown names raise `ValueError`.
+- `explicit_routes` / `explicit_events` of `None` means every transport. A request on a transport not listed gets 404.
+Handler contract:
+- Signature `(payload, meta)`, `(payload)` or `()` — only the arguments you declare are injected. Sync and async both work.
+- `payload`: what the caller sent (for REST: JSON body merged with query params). The shape is up to the plugin.
+- `meta`: `{"transport": "api"|"socket"|"tcp"|"mqtt"|"webrtc", "principal": dict | None}`. When the robot's login policy is on, `principal` holds the token subject. **Role checks are the plugin's job** — inspect `meta["principal"]` yourself.
+- The return value is the response body (must be JSON-serialisable). `None` → empty response.
+- Status codes: `raise PluginRouteError(code, message)`. Any other exception → 500 with `str(exc)` as the message.
+- `subscribe` handlers take `(payload)` only and return nothing.
+#### Calling plugin endpoints from outside
+| Transport | How |
+| --- | --- |
+| REST | `POST /common/plugin/{plugin_id}/{path}` (through the api-gateway), JSON body |
+| Socket.IO | emit event `common/plugin/{plugin_id}/{path}`, response arrives in the ack |
+| TCP | topic `common/plugin/{plugin_id}/{path}` request / publish |
+| MQTT | request: `common/plugin/{plugin_id}/{path}/__req__`, publish: `common/plugin/{plugin_id}/{topic}` |
+| WebRTC | data channel topic `common/plugin/{plugin_id}/{path}` |
+Auth: when the robot's login policy is on, a token is **required** (any role — GUEST passes). When it is off, calls go straight through. REST uses the same Bearer token as the other Muscat APIs.
+```bash
+curl -s -X POST http://<robot>/common/plugin/my-plugin/hello \
+  -H 'Content-Type: application/json' -d '{"name":"kim"}'
+```
+| Situation | Status |
+| --- | --- |
+| No plugin declares that path / plugin is down / transport not allowed | 404 |
+| Plugin did not answer within 10 s | 504 |
+| `common` ↔ gateway not connected | 503 |
+| Handler raised | 500 (`PluginRouteError` → its `code`) |
+Known limits:
+- A plugin path named `install` cannot be called over REST (`POST /common/plugin/{id}/install` is taken by the registry install route first). Socket/TCP are unaffected.
+- Swagger shows one catch-all route, not per-plugin paths.
+- The MQTT broker echoes to the sender: a plugin that `emit`s and `subscribe`s the same topic receives its own push over `mqtt`. Drop `mqtt` from `explicit_events` or use separate topics. (TCP is filtered by `sender_id`.)
+- `on` and `subscribe` may share a name — they live in separate tables.
+During `muscat-pk dev` the local Muscat runtime takes the `router.*` registrations
+on its gateway (port `10000`), and its `common` (port `3000`) routes
+`common/plugin/...` to them like on the robot — try
+`curl http://localhost:3000/common/plugin/<plugin-id>/<path>`. After restarting the plugin process,
+external calls may return 504 for up to about a minute (until the gateway notices
+the old socket is gone), then 404 — that is expected.
+#### Program command backend (`program.panel`)
+A `program.panel` contribution defines a **custom command** your plugin adds to
+the Muscat **Program page**, where the operator builds a robot program as a
+rule-based sequence (a program tree). Your command appears alongside the
+built-ins (Move J, Point, Wait, …); the operator places it into the tree, and
+each time the program executes that step the host calls your backend through
+`PluginProgramContext` — receiving the step args, checking for stop/pause,
+reading/writing program variables, and signalling completion. This pattern is
+**only** for `program.panel`; a toolbar/move-panel plugin uses the SDK directly
+instead (see the table above).
+```python
+"""
+Plugin backend main.py example (program.panel command).
+manifest.json:
+  "runtime": {"type": "python", "entry": "main.py"},
+  "contributes": [{
+    "point": "program.panel",
+    "ui": "program",
+    "label": {"en": "My Plugin Step"},
+    "commandInfo": {
+      "name": "My Plugin Step",
+      "icon": "assets/icon.svg",
+      "funcName": "rb_program_sdk.plugin_execute",
+      "args": {"message": "hello"}   # plugin-author-defined args
+    }
+  }]
+The host invokes commandInfo.funcName (rb_program_sdk.plugin_execute) with
+args.plugin_id + your args when the program reaches this step.
+"""
+import asyncio
+from rainbow.rb_sdk import PluginProgramContext
+ctx = PluginProgramContext(plugin_id="my-plugin")
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    """Called once when my Step executes. Variable writes apply to the
+    running program immediately + broadcast to other robots' main tasks."""
+    count = await ctx.get_variable("counter")          # read an existing program variable
+    await ctx.set_variable("counter", count + 1)       # update an existing variable — allowed
+    await ctx.set_variable("RBP_TEST", 1)              # NEW variables must start with RBP_
+    for i in range(100):
+        await ctx.check_stop()   # auto-scoped to this Step's robot model
+        await asyncio.sleep(0.5)
+    await ctx.done()
+async def background_monitor() -> None:
+    """Resident task outside any Step. If no program is running,
+    get returns None and set is silently ignored — always safe to call."""
+    while True:
+        await asyncio.sleep(1.0)
+        # targets every running main task (no robot_model param — always broadcast)
+        await ctx.set_variable("RBP_TEST", 3)
+        # get options
+        v1 = await ctx.get_variable("counter")                           # first value found in the whole tree
+        v2 = await ctx.get_variable("counter", robot_model="C500920")    # a specific robot
+        v3 = await ctx.get_variable("RBP_TEST", plugin_id="my-plugin")   # the value my-plugin last wrote
+        if ctx.executor_state("C500920") == "paused":
+            print("C500920 program is paused")
+async def main() -> None:
+    asyncio.create_task(background_monitor())
+    await ctx.start()  # stays resident
+asyncio.run(main())
+```
+#### Program variables & executor state (`PluginProgramContext`)
+`rainbow.rb_sdk.PluginProgramContext` lets the plugin process interact with the
+running program (PyFM): read/write program variables and observe execution
+state — inside a Step handler or from a resident task, at any time.
+- The `on_execute` handler is called **only when PyFM executes this plugin's
+  Step**. One Step execution = one handler call, and the Step does not finish
+  until you call `ctx.done()` — always call it.
+- The plugin process itself stays resident after `ctx.start()`; executor state
+  queries and variable access below keep working whether or not a Step is
+  executing.
+#### Variable naming rules (important)
+PyFM variables are a **program-wide shared namespace**. One rule:
+- **Modifying an existing variable** — the name passes as-is. Exchanging
+  variables between the program and the plugin is the intended usage.
+- **Creating a variable that doesn't exist** — the `RBP_` prefix is
+  **required** (enforced by the SDK/server; a violation raises
+  `RuntimeError`). Applies equally inside and outside Step execution.
+For new variable names, a convention that includes the plugin id is strongly
+recommended:
+```
+RBP_{plugin_id}_{name}
+e.g. RBP_vision_detect_count, RBP_gripper_last_error
+```
+Why:
+- `RBP_` — instantly identifies plugin-created variables in the program
+  editor/UI.
+- `{plugin_id}` — **prevents name collisions with other plugins.** If two
+  plugins use the same name they overwrite the same variable (`RBP_` alone is
+  not something the SDK guards against).
+#### Reading / writing variables
+```python
+value = await ctx.get_variable("counter")                 # read (no name restriction)
+await ctx.set_variable("counter", value + 1)              # modify existing variable — allowed
+await ctx.set_variable("RBP_my-plugin_result", 42)        # create new variable — RBP_ required
+```
+`set_variable` always applies to **every running main task** (a plugin belongs
+to muscat, not to a specific robot — there is no `robot_model` parameter):
+| When | Own program | Other robots' main tasks |
+|---|---|---|
+| During own Step execution | via the control queryable — **immediate** | broadcast — each at its next Step boundary |
+| Outside a Step (resident task, …) | resident endpoint — next Step boundary | same |
+`get_variable` has options:
+```python
+await ctx.get_variable("counter")                          # search all main tasks (first value found)
+await ctx.get_variable("counter", robot_model="C500920")   # a specific robot's value
+await ctx.get_variable("RBP_TEST", plugin_id="A.plugin")   # the value that plugin last wrote
+```
+Caveats:
+- If no program is running, `set_variable` is **silently ignored** and
+  `get_variable` returns `None`. (`RuntimeError` is raised only for real
+  errors, like the `RBP_` violation on a new variable — the message is tagged
+  `[plugin:{id}]` with the offending plugin.)
+- Rarely, a write can be lost if it races the worker's variable flush
+  (lock-free read-modify-write). For important values, re-check and retry on
+  the next cycle.
+#### Per-plugin value storage (meta)
+Besides the shared value, each variable entry records which plugin last wrote
+what:
+```python
+# state_dict["variables"] — after A wrote 1 and B wrote 2
+"RBP_TEST": {
+    "value": 2,                                # shared slot = last written value
+    "type": "local",
+    "meta": {"writers": {"A.plugin": 1, "B.plugin": 2}},   # per-plugin record
+}
+```
+So the exact value is recoverable even when names collide:
+- Plugin SDK: `ctx.get_variable("RBP_TEST", plugin_id="A.plugin")` → `1`
+- Program step expression: `COUNT = get_var("A.plugin", "RBP_TEST") + 1` → `2`
+- A plain name (`RBP_TEST += 1`) uses the shared slot (last written value) → `3`
+#### Executor state
+Subscribes to the `muscat/executor/state` publish (0.8 s interval) and exposes
+per-robot-model state:
+```python
+ctx.executor_state("C500920")   # "running" | "paused" | "waiting" | ... | None
+ctx.executor_state()            # {"C500920": "paused", "amr": "running"}
+ctx.is_paused("C500920")        # whether that model is paused
+ctx.is_stopped("C500920")       # stop/error transition of a model seen active this run
+```
+- States: `idle | running | paused | waiting | stopped | post_start | completed | error`
+- A model with no running task is `None` / absent from the dict.
+- The publish interval is 0.8 s, so expect up to ~1 s of latency.
+- With `IS_DEV=true` there is no publish at all — always `None`.
+To get a callback at the moment the state changes, without polling:
+```python
+@ctx.on_executor_state_change
+async def on_change(robot_model: str, state: str) -> None:
+    if state == "paused":
+        print(f"{robot_model} paused")
+```
+- Not called for repeated publishes of the same state — fires exactly once
+  per per-model state change.
+- An exception in the handler is only logged; state tracking keeps running.
+#### Responding to pause / stop
+```python
+@ctx.on_execute
+async def handle(args: dict) -> None:
+    for i in range(100):
+        # stop → CancelledError (propagated to the executor as a stop),
+        # pause → waits here until resumed.
+        # Inside on_execute this automatically watches only the robot model
+        # executing this Step.
+        await ctx.check_stop()
+        ...  # actual work
+        await asyncio.sleep(0.5)
+    await ctx.done()
+```
+Scope priority for `check_stop` / `is_paused` / `is_stopped`:
+1. `robot_model` given — that model only
+2. Omitted inside `on_execute` — **only the model executing this Step**
+   (passed in by the executor)
+3. Omitted elsewhere (resident task, …) — all models
+A handler doing long-running work must call `check_stop()` every loop
+iteration so it reacts to pause/stop immediately. Without it, the plugin keeps
+running even after the operator presses Stop.
+Variables your plugin wants the Program page variable picker to offer must be
+pre-declared in `manifest.json` under `"variables"` (see the manifest section
+below).
+### C++
+C++ plugins use `cpp/` and are built with CMake inside Docker against the
+Rainbow Robotics C++ SDK (see _C++ SDK_ below).
+```cpp
+#include <chrono>
+#include <cstdlib>
+#include <iostream>
+#include <string>
+#include <thread>
+int main() {
+  const char* plugin_id = std::getenv("RB_PLUGIN_ID");
+  std::cout << "[__PLUGIN_NAME__] backend ready"
+            << (plugin_id ? std::string(" (id=") + plugin_id + ")" : "")
+            << std::endl;
+  while (true) {
+    std::this_thread::sleep_for(std::chrono::seconds(1));
+  }
+  return 0;
+}
+```
+#### C++ SDK (`rainbow-rb-sdk-dev`)
+Both C++ runtimes (`cpp`, `ros2` + `rclcpp`) link the Rainbow Robotics C++ SDK
+from the apt package `rainbow-rb-sdk-dev`. The `muscat-pk` dev containers already
+have it, so `muscat-pk dev` / `build` need nothing extra. To build outside the
+container (your own Ubuntu 24.04 machine, or the robot PC):
+```bash
+curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/rb-sdk-apt.gpg
+echo 'deb [signed-by=/usr/share/keyrings/rb-sdk-apt.gpg] https://rainbowrobotics.github.io/rb-sdk stable main' | sudo tee /etc/apt/sources.list.d/rb-sdk.list
+sudo apt update && sudo apt install rainbow-rb-sdk-dev
+```
+- CMake: `find_package(rb_sdk REQUIRED)` + `target_link_libraries(<target> rb_sdk::rb_sdk)` (C++20). pkg-config: `rb_sdk`.
+- Headers: `<rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>` (`RBManipulateSDK`),
+  `<rainbow/rb_sdk/program/plugin_program_context.hpp>` (`rb_plugin::PluginProgramContext`, for `program.panel` commands — the header's top comment has a full `main()` example).
+- The binary is linked **dynamically**; `muscat-pk build` copies the matching `librb_sdk.so` into `dist/<arch>/lib/` (the robot has no SDK installed), so each plugin keeps the SDK version it was built with. The version is the one pinned in `CMakeLists.txt` (`find_package(rb_sdk <version> EXACT REQUIRED)`); change it with `muscat-pk sdk update <version>`.
+- UI ↔ backend messaging works from C++ too: `rb_plugin::RBPluginCall` in `<rainbow/rb_sdk/plugin/rb_plugin.hpp>` (see the scaffolded `cpp/main.cpp`).
+### ROS2 (rclpy)
+ROS2 Python plugins use `ros2_ws/` with `runtime.rosClient: "rclpy"`. relative topic names are placed under the plugin's ROS namespace — the plugin id
+with "." → "/" and "-" → "_" (`com.example.my-plugin` → `/com/example/my_plugin`), in dev
+and on the robot. Use an absolute name (`/cmd_vel`) for topics shared with other nodes.
+`RBPluginCall` works in the node module too (UI messaging and `plugin.router`).
+```python
+# ros2_ws/src/__PLUGIN_SLUG__/__PLUGIN_SLUG__/node.py
+import rclpy
+from rclpy.node import Node
+from rainbow.rb_sdk import RBManipulateSDK
+sdk = RBManipulateSDK()
+class __PLUGIN_CLASS__Node(Node):
+    def __init__(self):
+        super().__init__("__PLUGIN_SLUG___node")
+        self.get_logger().info("__PLUGIN_NAME__ node started")
+        # use sdk alongside ROS2 publishers/subscribers/services as needed
+```
+#### Talking to an external PC over ROS 2
+ROS 2 discovery stays on the robot (`ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST`; `muscat-pk dev`
+runs the same), so robots on one LAN don't mix topics. Allow specific PCs from the plugin UI —
+Muscat keeps the list per plugin, starts your backend with `ROS_STATIC_PEERS` set to it, and
+restarts the plugin when it changes. Your ROS code needs no changes; the PC needs no extra settings.
+```tsx
+const rb = useRb();
+const peers = await rb.rosPeers.get();               // ["192.168.0.50"]
+await rb.rosPeers.set(["192.168.0.50", "192.168.0.51"]); // saves + restarts the plugin; rejects on a bad IP
+```
+- Per plugin: plugin B keeps its allowed PCs when plugin A (allowing the same PC) is stopped or removed.
+- It opens communication; it is not access control — a PC that knows the robot's IP can still
+  add the robot to its own `ROS_STATIC_PEERS`.
+- In `muscat-pk dev` the list is kept in `.muscat-dev/ros-peers.json` (ROS 2 backends).
+### ROS2 (rclcpp)
+ROS2 C++ plugins use `ros2_ws/` with `runtime.rosClient: "rclcpp"`. The node links
+the Rainbow C++ SDK the same way as the `cpp` runtime (see _C++ SDK_ above).
+```cpp
+#include "rclcpp/rclcpp.hpp"
+class __PLUGIN_CLASS__Node : public rclcpp::Node {
+public:
+  __PLUGIN_CLASS__Node() : Node("__PLUGIN_SLUG___node") {
+    RCLCPP_INFO(this->get_logger(), "__PLUGIN_NAME__ node started");
+  }
+};
+```
+---
+## Video streaming (MediaMTX)
+Muscat runs a MediaMTX media server. The backend publishes a stream over RTSP and
+the UI plays it over WebRTC. `muscat-pk dev` runs the same server (or uses a local
+Muscat's), so the addresses are identical in dev and on the robot.
+| | Address |
+| --- | --- |
+| Publish (backend) | `rtsp://127.0.0.1:8554/<plugin_id>/<name>` |
+| Play (UI) | `http://<host>:8889/<plugin_id>/<name>/` |
+- Prefix the path with your plugin id — paths are shared with robot cameras and other plugins.
+- The robot runtime has no ffmpeg, GStreamer or OpenCV; bring your own encoder (below).
+**Backend (Python)** — use PyAV: add `av` and `numpy` to `requirements.txt`. Its wheels
+include FFmpeg, so they ship in the ZIP like any other dependency.
+```python
+import fractions, time
+import av, numpy as np
+out = av.open("rtsp://127.0.0.1:8554/__PLUGIN_ID__/cam", mode="w", format="rtsp",
+              options={"rtsp_transport": "tcp"})
+stream = out.add_stream("libx264", rate=25, options={"preset": "ultrafast", "tune": "zerolatency"})
+stream.width, stream.height, stream.pix_fmt = 640, 360, "yuv420p"
+i = 0
+while True:
+    img = np.zeros((360, 640, 3), dtype=np.uint8)          # your RGB frame here
+    frame = av.VideoFrame.from_ndarray(img, format="rgb24")
+    frame.pts, frame.time_base = i, fractions.Fraction(1, 25)
+    for packet in stream.encode(frame):
+        out.mux(packet)
+    i += 1
+    time.sleep(1 / 25)
+```
+Run the encoder loop in a thread (or `asyncio.to_thread`) so it doesn't block the
+`RBPluginCall` handlers.
+**UI** — embed MediaMTX's WebRTC player. `location.hostname` is `localhost` in the
+preview and the robot's address on the robot:
+```tsx
+const STREAM = "__PLUGIN_ID__/cam"; // the path the backend publishes
+export default function Camera() {
+  return (
+    <iframe
+      src={`${location.protocol}//${location.hostname}:8889/${STREAM}/`}
+      allow="autoplay"
+      className="aspect-video w-full border-0"
+    />
+  );
+}
+```
+---
+## manifest.json
+```jsonc
+{
+  // unique plugin ID — reverse-domain format recommended
+  "id": "com.example.my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  // minimum Muscat version required to load this plugin
+  "minMuscatVersion": "1.0.0",
+  // plugin author (empty string is fine)
+  "author": "Your Name",
+  // displayed in the Muscat plugin store / info panel
+  // string or { en (required), ko, ja, zh, vi, th, es }
+  "description": { "en": "Plugin description", "ko": "플러그인 설명" },
+  // SVG string (single file) or PNG/JPG size map (all three sizes required)
+  "icons": "assets/icon.svg",
+  // "icons": { "16": "assets/icon-16.png", "48": "assets/icon-48.png", "128": "assets/icon-128.png" },
+  // targetModels and/or targetCategorys — at least one is required
+  // "all" = every target, or list specific values
+  "targetModels": "all",
+  // "targetModels": ["C500920", "C500930"],
+  "targetCategorys": "all",
+  // "targetCategorys": ["manipulate", "amr", "rby1", "vision"],
+  "contributes": [
+    // program.panel — defines a custom command for the Program page sequence
+    //   builder; runs via PluginProgramContext when the program reaches it
+    {
+      "point": "program.panel",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "program",           // must be unique across all contributions
+      "commandInfo": {
+        "name": "My Plugin",
+        "icon": "assets/icon.svg",
+        "funcName": "rb_program_sdk.plugin_execute",
+        "args": {}
+      }
+    },
+    // toolbar — adds a button to the top toolbar (required)
+    {
+      "point": "toolbar",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "content",           // must be unique across all contributions
+      "opens": "popover"         // popover | panel | page
+    },
+    // move.panel — adds a panel to the Move screen
+    {
+      "point": "move.panel",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "move"               // must be unique across all contributions
+    }
+  ],
+  // optional: variables this plugin exposes to pyfm programs — the Program
+  // page variable picker lists ONLY declared variables. name must start with
+  // RBP_; description is optional but without it the UI can't explain the
+  // variable, so write one.
+  "variables": [
+    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘", "en": "Gripper force" } },
+    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
+  ],
+  // runtime — one of:
+  //   { "type": "none" }
+  //   { "type": "python", "entry": "main.py" }
+  //   { "type": "cpp", "entry": "<executable name>" }
+  //   { "type": "ros2", "rosClient": "rclpy" | "rclcpp", "package": "...", "launch": "..._node" }
+  "runtime": { "type": "python", "entry": "main.py" },
+  // optional: TCP ports opened by this plugin backend
+  // only number[] is allowed; ranges/objects are not accepted
+  // external plugin ports must be within 28600-28999
+  "ports": [28600]
+}
+```
+**Backend types:**
+| type | source dir | build / run | entry |
+|---|---|---|---|
+| `python` | `py/` | pip + run in Docker | `main.py` |
+| `cpp` | `cpp/` | CMake in Docker | built executable name |
+| `ros2` (rclpy) | `ros2_ws/` | colcon (ament_python) in Docker | — |
+| `ros2` (rclcpp) | `ros2_ws/` | colcon (ament_cmake) in Docker | — |
+> Every back end runs in a Docker container matching the robot (Ubuntu 24.04 + Python 3.12), so dev behaves like production and compiled binaries are ABI-compatible. **Docker is required** for all backend types (only a frontend-only `none` plugin skips it). No local Python/toolchain setup is needed.
+**Contribution points:**
+| point | Where it appears | Backend | `commandInfo` |
+|---|---|---|:---:|
+| `toolbar` | Top toolbar button (must have at least one) | SDK / `rb.action` | — |
+| `lnb` | Left navigation entry | SDK / `rb.action` | — |
+| `move.panel` | Move screen panel | SDK / `rb.action` | — |
+| `program.panel` | Custom command in the Program page sequence builder | `PluginProgramContext` | ✓ |
+**`commandInfo` fields** (for `program.panel`):
+| field | type | description |
+|---|---|---|
+| `name` | `string` | Display name of the command in the program tree |
+| `icon` | `string` | Icon path |
+| `iconClassName` | `string?` | Optional CSS class for the icon |
+| `funcName` | `string?` | Backend function name to call |
+| `args` | `Record<string, any>?` | Default arguments |
+| `disabled` | `boolean?` | Whether the node is disabled |
+| `allowChildren` | `string[]?` | Allowed child commands |
+| `allowParents` | `string[]?` | Allowed parent commands |
+| `notAllowChildren` | `string[]?` | Disallowed child commands |
+| `syncGroupId` | `boolean?` | Sync group ID across children |
+| `disableCopy` | `boolean?` | Prevent copy |
+| `disableDelete` | `boolean?` | Prevent delete |
+| `requireChildren` | `boolean?` | Whether a child command is required |
+| `requireParent` | `boolean?` | Whether a parent command is required |
+| `childrenCommand` | `string?` | Default command type for children |
+**Validation rules:**
+- `id`, `name`, `version`, `minMuscatVersion` — required non-empty strings
+- `author` — required non-empty string
+- `description` — required (`string` or `{ en (required), ko?, ja?, zh?, vi?, th?, es? }`)
+- `icons` — SVG: single string path ending in `.svg`; PNG/JPG: object with `"16"`, `"48"`, `"128"` all present
+- `targetModels` — `"all"` or a non-empty array of robot model ID strings (at least one of `targetModels` / `targetCategorys` required)
+- `targetCategorys` — `"all"` or a non-empty array of `"manipulate" | "amr" | "rby1" | "vision"` (at least one of `targetModels` / `targetCategorys` required)
+- `contributes` — the plugin's screens; when present it must contain at least one `toolbar` entry. Leave it out (or `[]`) for a backend-only plugin: no UI is built, and Node.js is not needed to build it
+- `ui` — each contribution must have a unique value
+- `commandInfo` — required when `point` is `"program.panel"`
+- `ports` — optional `number[]`; every port must be within `28600-28999`
+  and must not be a reserved robot/industrial/internal port
+- `variables` — optional array of `{ name, type, init, description? }`:
+  - `name` — must start with `RBP_`, then letters/digits/underscore; unique per plugin
+  - `type` — `"number" | "string" | "array"`
+  - `init` — required initial value, must match `type`
+  - `description` — optional `string` or i18n object (`en` required in object form)
+`muscat-pk build` throws on any validation error. `muscat-pk dev` prints
+warnings — except `variables` errors (e.g. a name without the `RBP_` prefix),
+which are hard errors in `dev` / `dev:back` too.
+**Backend port rules:**
+- Declare a port only if your backend opens a TCP server/listener.
+- **Every listening TCP port must be declared.** `muscat-pk dev` and
+  `muscat-pk dev:back` watch the backend and stop it the moment it opens a port
+  that is not in `ports`. A port outside `28600-28999` can't be declared, so it
+  must not be opened either — picking e.g. `5500` is not a way around the rule.
+  It would escape this check *and* the robot's install-time conflict check, and
+  only collide once it's running on a robot.
+- Reserved ports include `502`, `2222`, `4840`, `5170-5179`, `8000-8999`,
+  `10000`, `30004`, `34964`, `44818`, `50000-50005`, and `50051`.
+- The robot rejects installation (HTTP 409) if a declared port is reserved,
+  out of range, or already claimed by another enabled plugin.
+**Reaching your backend's ports during development:**
+- Declared ports are published to `127.0.0.1` on your machine, so
+  `curl http://127.0.0.1:28600` works from the host on macOS, Windows, and Linux.
+- On native Linux the dev container uses host networking, so the ports are on
+  the host already.
+- If a declared port is already taken on your machine, `muscat-pk dev` warns and
+  skips publishing that one — the backend still listens inside the container.
+---
+## Localized documentation
+You can ship per-language README files alongside the main `README.md`. Place them in the project root:
+```
+README.md        # default / English fallback
+README.ko.md     # Korean
+README.en.md     # explicit English (optional)
+README.ja.md     # Japanese
+```
+All `README*.md` files found at the project root are automatically copied to `dist/` on
+`muscat-pk build`. Muscat displays the file matching the user's locale,
+falling back to `README.md` if none matches.
+---
+## Installing Python dependencies
+Add any package with an optional version pin to `requirements.txt`:
+```
+rainbow-rb-sdk
+rainbow-rb-flat-buffers
+numpy==1.26.4
+opencv-python
+```
+Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically
+inside the dev container (`pip install -r requirements.txt`) on every startup. No
+local Python is required for this.
+`muscat-pk dev:back` also best-effort creates/refreshes a local `.venv` in the
+background (via `uv` if available, else your system Python) with the same deps —
+purely so your editor (pylint, pyright, mypy, ...) can resolve imports and lint
+correctly. It's not used to run the backend; Docker is the actual execution
+environment, so this step is silently skipped if no local Python toolchain is
+available. Point your editor's Python interpreter at `.venv`.
+`muscat-pk sdk update` also refreshes `.venv` in place if one already exists, so
+your editor picks up the new `rainbow-rb-sdk` version immediately.
+> `muscat-pk build` only **pins** versions in `requirements.txt` — it does not run `pip install` (the robot installs them at load time).
+---
+## Switching backend type
+```bash
+muscat-pk type change                 # interactive
+muscat-pk type change --to cpp        # → C++
+muscat-pk type change --to ros2       # → ROS2 (rclpy / Python)
+muscat-pk type change --to ros2-cpp   # → ROS2 (rclcpp / C++)
+muscat-pk type change --to python     # → Python
+```
+> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
+> Switching between a Python and a C++ backend asks whether to replace this README with the matching one (the old file is kept as `README.md.bak`). Add `--readme` to answer yes without the prompt.
+---
+## AI coding assistants (MCP)
+If you build your plugin with an AI assistant (Claude Code, Codex, …), give it
+grounded knowledge of the Muscat UI components, design tokens, and SDK instead of
+letting it guess. `muscat-pk mcp` is an MCP server exposing:
+- `list_components` / `get_component_props` / `get_component_example` — every
+  `@rainbow-robotics/plugin-ui/react` component with its real props and a working
+  Storybook example.
+- `list_design_tokens` / `search_design_tokens` — the Tailwind classes to use
+  (`bg-bg-*`, `text-fg-*`, `typo-*`, …) so your UI matches the host theme.
+- `search_rb_sdk` — how to use `useRb()`, `rb.*`, `useRbFormData`/`useRbSave`, and
+  the backend runtimes.
+- `list_rb_sdk` / `get_rb_sdk_api` — the installed `rainbow-rb-sdk` (Python
+  backend) classes and signatures; with `lang: "cpp"`, the C++ SDK headers
+  (`rainbow-rb-sdk-dev`, read out of the `muscat-pk` cpp dev image — build it
+  once with `muscat-pk dev:back`).
+**Browse the components live** with `muscat-pk storybook`.
+`muscat-pk new` also writes `AGENTS.md` (read by Codex, Cursor, Gemini CLI, Copilot)
+and a `CLAUDE.md` that imports it: the UI rules (plugin-ui components instead of
+native `<select>`/`<input>`/`<button>`, design tokens for colors) for assistants that
+do not call the MCP tools on their own. Add your own project notes there.
+### Register the server
+**Claude Code** — a `.mcp.json` is already scaffolded at your plugin root, so
+it works out of the box:
+```json
+{
+  "mcpServers": {
+    "muscat": {
+      "command": "muscat-pk",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+**Codex** — register once with:
+```bash
+muscat-pk mcp --install codex
+```
+This appends the server to `~/.codex/config.toml` (idempotent — safe to run
+again). Equivalent manual config:
+```toml
+[mcp_servers.muscat]
+command = "muscat-pk"
+args = ["mcp"]
+```
+Any other MCP client works too — it's a standard stdio MCP server started with
+`muscat-pk mcp`. If `muscat-pk` isn't on the client's PATH, use its absolute path
+(`which muscat-pk`) as `command`.
+---
+## Shipping
+```bash
+muscat-pk build            # build + ZIP
+muscat-pk build --no-zip   # build only, no ZIP
+```
+> Building the other arch (e.g. arm64 on an amd64 PC) runs in an emulated container for
+> C++ backends. Docker Desktop has it built in; on Linux enable it once with
+> `docker run --privileged --rm tonistiigi/binfmt --install all`, or pass `--arch` for one arch.
+- Builds `ui/content.tsx` → `dist/content.js` (minified)
+- Pins `requirements.txt` to latest versions (stable-only on `main` branch)
+- Copies `assets/`, `manifest.json`, `README*.md`, `py/`, and `requirements.txt` into `dist/`
+- ROS2: runs `colcon build` inside the Jazzy container; includes `ros2_ws/install/`
+- Output: `__PLUGIN_DIR__-{version}.zip`
+ZIP layout:
+```
+__PLUGIN_DIR__-1.0.0.zip
+├─ dist/
+│   ├─ content.js        # built UI
+│   ├─ manifest.json
+│   ├─ assets/
+│   ├─ README.md
+│   ├─ README.ko.md      # if present
+│   ├─ main.py           # from py/
+│   └─ requirements.txt  # pinned
+└─ ros2_ws/install/      # ROS2 only
+```
+---
+## All commands
+```bash
+muscat-pk dev        # UI + backend
+muscat-pk dev:ui     # UI preview only (preview-host)
+muscat-pk dev:back   # backend only (Python: watchfiles / ROS2: Docker)
+muscat-pk build      # build → dist/ + distributable ZIP (--no-zip to skip)
+muscat-pk storybook  # browse the rb-components UI library in a browser
+muscat-pk mcp        # MCP server for AI assistants (components/tokens/SDK docs)
+```
+```bash
+muscat-pk type change    # switch backend type
+muscat-pk sdk list       # show current Python SDK version
+muscat-pk sdk update     # update Python SDK to latest
+muscat-pk update         # update muscat-plugin-kit itself
+muscat-pk uninstall      # remove muscat-pk itself
+```