96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
---
|
|
name: cad-viewer
|
|
description: Start or reuse CAD Viewer and return review links for explicit CAD, implicit CAD, robot-description, and G-code files. Use when visually reviewing `.step`, `.stp`, `.implicit.js`, `.implicit.mjs`, `.glb`, `.stl`, `.3mf`, `.gcode`, `.dxf`, `.urdf`, `.srdf`, or `.sdf` files, especially when handed off from CAD, implicit-cad, G-code, URDF, SRDF, or SDF generation skills.
|
|
---
|
|
|
|
# CAD Viewer
|
|
|
|
Provenance: maintained in [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad).
|
|
Use the installed local skill files as the runtime source of truth; the
|
|
repository link is only for provenance and release review.
|
|
|
|
Use this skill to open existing or newly generated CAD, implicit CAD,
|
|
robot-description, DXF, or plain FDM G-code files in CAD Viewer and hand back
|
|
live review links. The expected input is one or more explicit file paths.
|
|
|
|
## Start Viewer
|
|
|
|
Start or reuse one local CAD Viewer with `npm run agent:start`, passing the
|
|
absolute artifact directory as `--dir`. The `agent:start` launcher owns port
|
|
selection, compatible-server reuse, directory activation, and the `?dir=` query
|
|
parameter. Dev-mode viewers are reused only for matching git identities; dist
|
|
bundle viewers can be reused across git branches when their viewer versions
|
|
match. It activates reused servers through the Viewer's lightweight directory
|
|
activation API, without requiring agents to probe ports or trigger catalog
|
|
scans manually. Use the Viewer URL printed by `agent:start` as-is, then add only
|
|
a `file=` query value for the artifact you want to review.
|
|
|
|
Choose `--dir` as the absolute directory that contains the model
|
|
artifacts and sidecars, commonly `<repo>/models` or the consuming project's
|
|
equivalent model directory. The `file=` value must be relative to that `--dir`.
|
|
Do not manually choose ports, probe servers, rewrite `?dir=`, or start a
|
|
separate Viewer just to change directories.
|
|
|
|
Run from this skill directory:
|
|
|
|
```bash
|
|
npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir <absolute-model-root>
|
|
```
|
|
|
|
Use the printed Viewer URL and append `file=`:
|
|
|
|
```bash
|
|
http://127.0.0.1:<printed-port>/?dir=/absolute/project/models&file=path/to/model.step
|
|
```
|
|
|
|
If a non-Viewer process or another worktree's Viewer occupies the candidate
|
|
port, the launcher will continue automatically. In sandboxed agent environments,
|
|
local binding or probe failures such as `EPERM` or `EACCES` can be expected;
|
|
rerun the same command with the needed permission/escalation.
|
|
|
|
## Links
|
|
|
|
- Before returning any `file=` link, resolve `<dir>/<file>` and confirm the
|
|
artifact exists. Pass the generated artifact (e.g. `.step`), not its
|
|
generator source (e.g. `.py`). If the resolved path is missing, do not
|
|
return the link, and instead report the problem and point to the correct
|
|
generated artifact path.
|
|
- Return one Viewer URL per requested file.
|
|
- Start/reuse the Viewer once per absolute directory `--dir`, then append
|
|
`file=<path>` for each requested file. The file path must be relative to
|
|
`--dir`.
|
|
- For directory-only review links, return the URL printed by `agent:start`
|
|
without adding `file=`.
|
|
- Do not stop an existing Viewer server unless the user asks.
|
|
- If Viewer startup fails, report the failure and continue with the owning skill's non-GUI validation or artifacts.
|
|
|
|
## Claude Preview
|
|
|
|
The viewer port is dynamic — it is chosen at startup and may differ across
|
|
worktrees. To integrate with the Claude Preview tool, add `--json` to the
|
|
`agent:start` command:
|
|
|
|
```bash
|
|
npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir <absolute-model-root> --json
|
|
```
|
|
|
|
The launcher writes a JSON result line to stdout after the human-readable lines.
|
|
Parse it by taking the last line of stdout that begins with `{`:
|
|
|
|
```json
|
|
{"url":"http://127.0.0.1:<port>/?dir=<absolute-model-root>","port":<port>,"action":"reuse"}
|
|
```
|
|
|
|
`action` is `"reuse"` when an existing server was reused and is immediately
|
|
ready, or `"start"` when a new server process was spawned and may still be
|
|
initializing. For a `"start"` result, probe `GET /__cad/server` on the base
|
|
URL (e.g. `http://127.0.0.1:<port>/__cad/server`) until it returns HTTP 200
|
|
before passing the `url` value to the Claude Preview tool.
|
|
|
|
## References
|
|
|
|
- Read `references/development.md` when the user asks to modify, debug, or
|
|
iterate on CAD Viewer source.
|
|
- Read `references/viewer-features.md` when you need supported file types, Viewer controls, or file-specific feature details.
|
|
- Read `references/moveit2-server.md` only when the user specifically needs optional SRDF MoveIt2 IK or path-planning controls.
|