--- name: render description: Start or reuse the CAD Explorer viewer, return review links, and create saved snapshots for explicit CAD and robot-description files. Use when rendering or visually reviewing `.step`, `.stp`, `.glb`, `.stl`, `.3mf`, `.dxf`, `.urdf`, `.srdf`, or `.sdf` files, especially when handed off from CAD, URDF, SRDF, or SDF generation skills. --- # Render Use this skill to open generated or modified CAD and robot-description files in CAD Explorer. The expected input is one or more explicit file paths that already exist or were just generated by another skill. Supported files: `.step`, `.stp`, `.glb`, `.stl`, `.3mf`, `.dxf`, `.urdf`, `.srdf`, `.sdf`. ## Handoff Contract - Accept explicit file paths from CAD, URDF, SRDF, SDF, SendCutSend, or standard-part workflows. - Start or reuse CAD Explorer with `dev:ensure`; do not assume a fixed port. Treat `dev:ensure` as the viewer liveness check for returned links. - Treat port reuse as mandatory: if `dev:ensure` reports local binding/probing denial such as `EPERM` or `EACCES`, rerun the same `dev:ensure` command with the needed local-binding permission/escalation instead of choosing a new port yourself. - Do not use `npm run dev -- --port ...`, raw `vite dev`, or raw `vite preview` for normal agent handoffs; those bypass the reuse policy and can leave duplicate localhost Explorer servers running. - Return the printed Explorer URL for each requested file. - For generation review or visual feedback, prefer the snapshot CLI over opening the viewer manually or using Playwright. Viewer links are still returned for handoff/live review. - Generate GIFs only for CAD STEP-module parameter animation review. Otherwise use still snapshots, not GIFs. - If startup fails, report the failure and let the owning skill continue with its non-GUI validation. ## Commands From this skill directory: ```bash npm --prefix scripts/viewer run dev:ensure -- --file path/to/model.step ``` For saved headless snapshots, use the skill-level snapshot wrapper. It delegates into the viewer package's `scripts/viewer/snapshot` implementation: ```bash python3 scripts/snapshot --job path/to/render-job.json python3 scripts/snapshot --job - ``` Shortcut flags are available for common theme snapshots only: ```bash python3 scripts/snapshot \ --input path/to/model.step \ --output /tmp/model.png \ --mode view \ --theme technical \ --camera iso \ --view-labels ``` STEP module sidecar parameters can be supplied with `--params` for stills or animated parameter GIFs: ```bash python3 scripts/snapshot \ --input path/to/model.step \ --output /tmp/model.png \ --params '{"drive":180,"ringVisible":false}' python3 scripts/snapshot \ --input path/to/model.step \ --output /tmp/model.gif \ --params '{"values":{"ringVisible":true},"animate":{"drive":{"from":0,"to":1260}},"durationSeconds":6,"fps":18,"loop":true}' ``` The snapshot CLI defaults to `--theme technical`, a flat, high-contrast theme intended for visual diagnosis rather than presentation. `--theme` accepts a built-in theme name, an inline JSON theme object, or a path to a JSON theme file; set `theme.display.mode` to `solid` or `wireframe` for surface/wire output. `--params` targets Explorer `.step.js` STEP module sidecar parameters, not Python/build123d regeneration parameters. The snapshot CLI chooses default dimensions by request context when width/height are omitted: diagnostic stills 1600x1200, simple unlabeled parts 1200x900, sections/labeled/dimensioned views at least 1600x1200, complex assemblies 1800x1200 or 1920x1440 via `render.sizeProfile`, presentation renders 2400x1600 or 2800x1800 via `render.sizeProfile`, STEP-module parameter GIFs 960x640, and contact sheets at least 2400 px wide. Keep transparent snapshots presentation-oriented unless transparency answers a concrete overlap, collision, or internal-relationship question. Use JSON jobs for custom theme settings, selections, sections, orbit settings, robot joint values, STEP module params, DXF thickness/bend options, and multi-output snapshots. Supported render modes are `view`, `orbit`, `section`, and `list`. Supported inputs are `.step`, `.stp`, `.glb`, `.stl`, `.3mf`, `.dxf`, `.urdf`, `.srdf`, and `.sdf`. When the workspace root is known, pass it explicitly: ```bash npm --prefix scripts/viewer run dev:ensure -- \ --workspace-root /path/to/workspace \ --file path/to/model.step ``` Use foreground Vite only for manual Explorer development: ```bash npm --prefix scripts/viewer run dev ``` `dev:ensure` probes and checks registered local CAD Explorer servers across its full port range first, reuses one with a matching scan root whenever possible, and only then starts a detached Vite server on the first available port. Use the URL it prints. ## MoveIt2 Controls For SRDF Explorer reviews, start the MoveIt2 server only when the user needs interactive IK or path-planning controls. SRDF generation and plain Explorer links do not require it. From this skill directory: ```bash scripts/moveit2_server/setup.sh scripts/moveit2_server/check-moveit2-server.sh scripts/moveit2_server/run-moveit2-server.sh ``` The server defaults to `ws://127.0.0.1:8765/ws`. CAD Explorer connects to that URL in local dev unless `EXPLORER_MOVEIT2_WS_URL` or the browser `?moveit2Ws=` query override is set. For protocol and reporting details, read `references/moveit2-server.md`. Useful Explorer environment variables: ```text EXPLORER_PORT EXPLORER_PORT_END EXPLORER_ROOT_DIR EXPLORER_DEFAULT_FILE EXPLORER_WORKSPACE_ROOT EXPLORER_GITHUB_URL EXPLORER_MOVEIT2_WS_URL EXPLORER_ALLOWED_HOSTS EXPLORER_SERVER_REGISTRY ``` When exposing CAD Explorer through remotehost/Tailscale Serve, set `EXPLORER_ALLOWED_HOSTS` to the Serve hostname before starting or restarting `dev:ensure`: ```bash EXPLORER_ALLOWED_HOSTS=macbook-pro-108.tail3c8ded.ts.net \ npm --prefix scripts/viewer run dev:ensure -- \ --workspace-root /path/to/workspace \ --root-dir models \ --file path/to/model.urdf ``` Before returning the remote link, verify the host-header path locally: ```bash curl -I -H 'Host: macbook-pro-108.tail3c8ded.ts.net' \ 'http://127.0.0.1:PORT/?file=path/to/model.urdf' ``` The expected response is `200 OK`. If a remote phone loads the page shell but shows a blank/black screen through a Vite dev server, try a production preview before deeper rendering changes. Build with the same scan root and default file, start `vite preview` with the same `EXPLORER_ALLOWED_HOSTS` hostname, verify the Host-header path, then repoint remotehost/Tailscale Serve to the preview port: ```bash EXPLORER_WORKSPACE_ROOT=/path/to/workspace \ EXPLORER_ROOT_DIR=models \ EXPLORER_DEFAULT_FILE=robots/elrobot/elrobot-follower.urdf \ npm --prefix scripts/viewer run build cd scripts/viewer EXPLORER_WORKSPACE_ROOT=/path/to/workspace \ EXPLORER_ROOT_DIR=models \ EXPLORER_DEFAULT_FILE=robots/elrobot/elrobot-follower.urdf \ EXPLORER_ALLOWED_HOSTS=macbook-pro-108.tail3c8ded.ts.net \ EXPLORER_PORT=4202 \ npm exec vite preview -- --host 127.0.0.1 --port 4202 --strictPort ``` This removes Vite's dev client and HMR websocket from the phone path while preserving the same `?file=` URL. Keep GUI work lightweight: start the server only when a link/review is needed, prefer `dev:ensure` for agent workflows, and do not stop an existing Explorer server unless the user asks.