brepjs-verify 0.3.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.8.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.7.1...brepjs-verify-v0.8.0) (2026-06-13)
+
+
+### Features
+
+* **brepjs-verify:** auto-open browser on --serve + document the MCP server ([#1308](https://github.com/andymai/brepjs/issues/1308)) ([de4272c](https://github.com/andymai/brepjs/commit/de4272c9196f70baec4ff762a33636fccef4c012))
+* **brepjs-verify:** burn bbox dimensions into agent snapshots ([#1280](https://github.com/andymai/brepjs/issues/1280)) ([25b6b8d](https://github.com/andymai/brepjs/commit/25b6b8df68909a41eaef5307519a29a8a05ccc00))
+* **verify:** add center of mass to the verify report ([#1288](https://github.com/andymai/brepjs/issues/1288)) ([5738600](https://github.com/andymai/brepjs/commit/5738600e31f56c00d928d62e32ab9d5e8220b377))
+* **verify:** add export_part MCP tool and sandbox export ([#1316](https://github.com/andymai/brepjs/issues/1316)) ([8a52f90](https://github.com/andymai/brepjs/commit/8a52f90c5b3d76c8bf6ef50a36c6977833af59bb))
+* **verify:** add JSONL run-record provenance for sandbox runs ([#1309](https://github.com/andymai/brepjs/issues/1309)) ([6bda9b6](https://github.com/andymai/brepjs/commit/6bda9b630b8e4edf6eb860002c58b3e36cf1bfd4))
+* **verify:** add manifold flag to the topology channel ([#1291](https://github.com/andymai/brepjs/issues/1291)) ([5ea5bb4](https://github.com/andymai/brepjs/commit/5ea5bb4db5bc8539f2773752e1c42770c91b5e0d))
+* **verify:** add MCP server with run_program tool (stdio) ([#1300](https://github.com/andymai/brepjs/issues/1300)) ([e3c2c9e](https://github.com/andymai/brepjs/commit/e3c2c9e678dd719608cea8b6ee38101de9775e5d))
+* **verify:** add topology counts to the verify report ([#1285](https://github.com/andymai/brepjs/issues/1285)) ([17a0eed](https://github.com/andymai/brepjs/commit/17a0eede727ac29007591cb0249274a35896facb))
+* **verify:** sandbox executor — run agent code in an isolated child process ([#1295](https://github.com/andymai/brepjs/issues/1295)) ([8b72aa2](https://github.com/andymai/brepjs/commit/8b72aa2e272a58aa6d3886b8304eeaefb1a09b2e))
+* **verify:** validate each body of multi-solid assemblies ([#1293](https://github.com/andymai/brepjs/issues/1293)) ([deb682f](https://github.com/andymai/brepjs/commit/deb682f1104179f261f232be7d94ceb154985328))
+* **viewer:** click-to-inspect face picking in verify --serve ([#1278](https://github.com/andymai/brepjs/issues/1278)) ([735dc04](https://github.com/andymai/brepjs/commit/735dc0401143ff47046a79e6fb7bac53cf00a91e))
+* **viewer:** measurements info panel in verify --serve ([#1277](https://github.com/andymai/brepjs/issues/1277)) ([c1ccf1d](https://github.com/andymai/brepjs/commit/c1ccf1d7c50ab43dc0444468f92fcf9365fda9da))
+* **viewer:** orthographic/perspective projection toggle ([#1281](https://github.com/andymai/brepjs/issues/1281)) ([96673e4](https://github.com/andymai/brepjs/commit/96673e45e1ee316f9d26e52c995b4daba691e8b0))
+* **viewer:** section/clipping plane in verify --serve ([#1279](https://github.com/andymai/brepjs/issues/1279)) ([cc0d00b](https://github.com/andymai/brepjs/commit/cc0d00b7a6296cc698fce1ae42b7503e6d47c032))
+* **viewer:** shared ViewerControls toolbar; interactive verify --serve ([#1275](https://github.com/andymai/brepjs/issues/1275)) ([139ae15](https://github.com/andymai/brepjs/commit/139ae15a29d8a7ad5e520ba21d6dc9788242c089))
+
+## [0.7.1](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.7.0...brepjs-verify-v0.7.1) (2026-06-13)
+
+
+### Bug Fixes
+
+* **brepjs-verify:** repair preview viewer + GLB Y-up/materials fidelity ([#1271](https://github.com/andymai/brepjs/issues/1271)) ([2823d21](https://github.com/andymai/brepjs/commit/2823d212e2fc5f79e785911ec2b9f3320bdfdbbf))
+
+## [0.7.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.6.0...brepjs-verify-v0.7.0) (2026-06-10)
+
+
+### Features
+
+* **brepjs-verify:** eval-driven skill, hint, and reference improvements ([#1219](https://github.com/andymai/brepjs/issues/1219)) ([1a9b80f](https://github.com/andymai/brepjs/commit/1a9b80f3d3dbb44d7a8ae2f601ff305b70534efe))
+* **brepjs-verify:** live text-to-cad eval flywheel ([#1215](https://github.com/andymai/brepjs/issues/1215)) ([4e81fc4](https://github.com/andymai/brepjs/commit/4e81fc4053491ce3e08182d57d76bd649252ea3c))
+* **brepjs-verify:** standalone bundled CLI + rename from brepjs-cad ([#1211](https://github.com/andymai/brepjs/issues/1211)) ([05b3799](https://github.com/andymai/brepjs/commit/05b3799a0e9ee4968d4cac92f3a2ea236e39cd35))
+
+
+### Bug Fixes
+
+* **brepjs-verify:** correct fillet/chamfer arg order in no-edges hints ([#1218](https://github.com/andymai/brepjs/issues/1218)) ([835f13a](https://github.com/andymai/brepjs/commit/835f13ac966b4264ba56a5cfc371bbbbbd1a0f01))
+* **brepjs-verify:** point skills entry at ./skill directory, not SKILL.md ([#1270](https://github.com/andymai/brepjs/issues/1270)) ([9413a57](https://github.com/andymai/brepjs/commit/9413a57d8c2cac943371e75bcbaf11b3fdd9a657))
+
+## [0.6.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.5.1...brepjs-verify-v0.6.0) (2026-06-09)
+
+
+### Features
+
+* **brepjs-verify:** eval-driven skill, hint, and reference improvements ([#1219](https://github.com/andymai/brepjs/issues/1219)) ([1a9b80f](https://github.com/andymai/brepjs/commit/1a9b80f3d3dbb44d7a8ae2f601ff305b70534efe))
+* **brepjs-verify:** live text-to-cad eval flywheel ([#1215](https://github.com/andymai/brepjs/issues/1215)) ([4e81fc4](https://github.com/andymai/brepjs/commit/4e81fc4053491ce3e08182d57d76bd649252ea3c))
+* **brepjs-verify:** standalone bundled CLI + rename from brepjs-cad ([#1211](https://github.com/andymai/brepjs/issues/1211)) ([05b3799](https://github.com/andymai/brepjs/commit/05b3799a0e9ee4968d4cac92f3a2ea236e39cd35))
+
+
+### Bug Fixes
+
+* **brepjs-verify:** correct fillet/chamfer arg order in no-edges hints ([#1218](https://github.com/andymai/brepjs/issues/1218)) ([835f13a](https://github.com/andymai/brepjs/commit/835f13ac966b4264ba56a5cfc371bbbbbd1a0f01))
+
+## [0.5.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.4.1...brepjs-verify-v0.5.0) (2026-06-08)
+
+
+### Features
+
+* **brepjs-verify:** eval-driven skill, hint, and reference improvements ([#1219](https://github.com/andymai/brepjs/issues/1219)) ([1a9b80f](https://github.com/andymai/brepjs/commit/1a9b80f3d3dbb44d7a8ae2f601ff305b70534efe))
+* **brepjs-verify:** live text-to-cad eval flywheel ([#1215](https://github.com/andymai/brepjs/issues/1215)) ([4e81fc4](https://github.com/andymai/brepjs/commit/4e81fc4053491ce3e08182d57d76bd649252ea3c))
+* **brepjs-verify:** standalone bundled CLI + rename from brepjs-cad ([#1211](https://github.com/andymai/brepjs/issues/1211)) ([05b3799](https://github.com/andymai/brepjs/commit/05b3799a0e9ee4968d4cac92f3a2ea236e39cd35))
+
+
+### Bug Fixes
+
+* **brepjs-verify:** correct fillet/chamfer arg order in no-edges hints ([#1218](https://github.com/andymai/brepjs/issues/1218)) ([835f13a](https://github.com/andymai/brepjs/commit/835f13ac966b4264ba56a5cfc371bbbbbd1a0f01))
+
+## [0.4.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.3.0...brepjs-verify-v0.4.0) (2026-06-04)
+
+
+### Features
+
+* **brepjs-verify:** eval-driven skill, hint, and reference improvements ([#1219](https://github.com/andymai/brepjs/issues/1219)) ([1a9b80f](https://github.com/andymai/brepjs/commit/1a9b80f3d3dbb44d7a8ae2f601ff305b70534efe))
+
 ## [0.3.0](https://github.com/andymai/brepjs/compare/brepjs-verify-v0.2.1...brepjs-verify-v0.3.0) (2026-06-04)
 
 

package/README.md

@@ -21,6 +21,15 @@ The CLI the skill invokes. Install it in **your** project, where `brepjs` + the
 npm i -D brepjs-verify brepjs occt-wasm
 ```
 
+## API reference
+
+The package bundles brepjs's full API reference for offline/agent use — the complete export surface with signatures and examples:
+
+- `reference/llms-full.txt` — every export, full signatures (the deep reference)
+- `reference/llms.txt` — the same content as a quicker index
+
+Point your agent at `node_modules/brepjs-verify/reference/llms-full.txt` for anything the skill's curated references don't cover.
+
 ## The `.brep.ts` contract
 
 A model is a module whose default export is a zero-arg function returning a shape (or a `Result<shape>`):
@@ -36,28 +45,58 @@ export default () => box(40, 20, 10, { centered: true });
 ```
 npx -y brepjs-verify part.brep.ts --step part.step --json report.json   # primary STEP + deterministic report
 npx -y brepjs-verify part.brep.ts --snapshot shots/                     # iso/front/top/right PNGs
-npx -y brepjs-verify part.brep.ts --serve                               # clickable preview link (renders the real STEP)
+npx -y brepjs-verify part.brep.ts --serve                               # preview server + opens the viewer in your browser
+npx -y brepjs-verify part.brep.ts --serve --no-open                     # preview server; just print the URL (no browser)
 ```
 
-`--snapshot`/`--serve` use the bundled viewer (shipped under `viewer/dist`, including the OCCT WASM). The viewer is read-only display + screenshot in v1.
+`--snapshot`/`--serve` use the bundled viewer (shipped under `viewer/dist`, including the OCCT WASM). The `--serve` link is interactive: a toolbar offers view presets + fit, solid/wireframe/x-ray modes, edge/grid toggles, a turntable, click-to-inspect face picking, a section/clipping plane, a measurements panel, and an in-browser PNG screenshot. `--snapshot` loads the same page with `ui=0` to suppress the toolbar, and burns the bounding-box size into each PNG (`dims=1`) so the agent can read scale from the image.
+
+`--serve` prints the viewer URL and, in an interactive terminal, opens it in your default browser. Auto-open is skipped when it would be unwanted — when the server is reused (a tab is already open), under CI, when output is piped (non-TTY, e.g. agent runs), or on Linux with no display server. Pass `--no-open` to always suppress it.
 
 ## CLI reference
 
 The `brepjs-verify` bin is a multi-command CLI. `verify` is the default command, so `brepjs-verify part.brep.ts` runs it directly.
 
-| Command                         | What it does                                                                                                                                                                                                                            |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `brepjs-verify verify <file>`   | Default command. Loads the part, runs deterministic checks, prints the JSON report. Flags: `--json <out>`, `--step <out>`, `--glb <out>`, `--snapshot <dir>`, `--serve`. Exits non-zero when the report is not `ok` (unless `--serve`). |
-| `brepjs-verify init <name>`     | Scaffolds a parameterized `<name>.brep.ts` + `tsconfig.json` + `README.md` into `./<name>` (or `--out <dir>`). Never overwrites existing files.                                                                                         |
-| `brepjs-verify watch <file>`    | Re-verifies on every save until Ctrl-C (debounced; watches the parent dir to survive editor rename-on-save).                                                                                                                            |
-| `brepjs-verify export <file>`   | Batch artifacts behind a validity gate: `--step`, `--glb`, `--stl`, or `--all`; `--out <dir>` (default `.`). Exits non-zero on failure.                                                                                                 |
-| `brepjs-verify measure <a> [b]` | Measurements for one part; with a second module, the distance between the two parts.                                                                                                                                                    |
-| `brepjs-verify diff <a> <b>`    | Compares the measurements of a baseline and a comparison module.                                                                                                                                                                        |
-| `brepjs-verify snapshot`        | Multi-view PNG capture — surfaced via `verify --snapshot <dir>`. Requires the optional `puppeteer`/Chrome dependency; degrades with a clear message when absent.                                                                        |
-| `brepjs-verify serve`           | Preview server with a `?dir=&file=` deep link — surfaced via `verify --serve`.                                                                                                                                                          |
+| Command                         | What it does                                                                                                                                                                                                                                                                                       |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `brepjs-verify verify <file>`   | Default command. Loads the part, runs deterministic checks, prints the JSON report. Flags: `--json <out>`, `--step <out>`, `--glb <out>`, `--snapshot <dir>`, `--serve`, `--no-open` (with `--serve`, don't auto-open the browser). Exits non-zero when the report is not `ok` (unless `--serve`). |
+| `brepjs-verify init <name>`     | Scaffolds a parameterized `<name>.brep.ts` + `tsconfig.json` + `README.md` into `./<name>` (or `--out <dir>`). Never overwrites existing files.                                                                                                                                                    |
+| `brepjs-verify watch <file>`    | Re-verifies on every save until Ctrl-C (debounced; watches the parent dir to survive editor rename-on-save).                                                                                                                                                                                       |
+| `brepjs-verify export <file>`   | Batch artifacts behind a validity gate: `--step`, `--glb`, `--stl`, or `--all`; `--out <dir>` (default `.`). Exits non-zero on failure.                                                                                                                                                            |
+| `brepjs-verify measure <a> [b]` | Measurements for one part; with a second module, the distance between the two parts.                                                                                                                                                                                                               |
+| `brepjs-verify diff <a> <b>`    | Compares the measurements of a baseline and a comparison module.                                                                                                                                                                                                                                   |
+| `brepjs-verify snapshot`        | Multi-view PNG capture — surfaced via `verify --snapshot <dir>`. Requires the optional `puppeteer`/Chrome dependency; degrades with a clear message when absent.                                                                                                                                   |
+| `brepjs-verify serve`           | Preview server with a `?dir=&file=` deep link — surfaced via `verify --serve`. Auto-opens the browser in an interactive terminal (suppressed under CI / non-TTY / no display, or with `--no-open`).                                                                                                |
 
 Every command writes a single machine-readable JSON document to stdout; diagnostics (paths, kernel chatter, watch notices) go to stderr.
 
+## MCP server
+
+`brepjs-verify-mcp` is a stdio [MCP](https://modelcontextprotocol.io) server that exposes the verify substrate to MCP-capable agents (Claude Code, Claude Desktop, any MCP client). It currently provides one tool:
+
+| Tool          | Input                                  | Returns                                                                                                                                                                                                                               |
+| ------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run_program` | `{ code: string, timeoutMs?: number }` | Executes the brepjs `.brep.ts` source in an isolated, timeout/OOM-bounded sandbox and returns the verification report (validity, measurements, topology) as JSON. `isError` is set when the part fails checks, times out, or crashes. |
+
+This is the closed _build → verify_ loop as a single call: the agent sends part source, gets back the deterministic report. The program runs in a separate process with a wall-clock timeout and a memory cap, so a runaway part can't hang the agent.
+
+### Connect (local build)
+
+Build the package, then register the server by absolute path. Run both commands from the package root (`packages/brepjs-verify`), where `dist/` is emitted — `$(pwd)` is resolved by your shell at that location:
+
+```bash
+npm run build   # emits dist/mcp/server.js
+claude mcp add brepjs-verify -- node "$(pwd)/dist/mcp/server.js"
+```
+
+Once the package is published to npm, the same server is available without a local build:
+
+```bash
+claude mcp add brepjs-verify -- npx -y --package brepjs-verify brepjs-verify-mcp
+```
+
+The server runs locally as a child process of your agent (stdio) — geometry never leaves your machine.
+
 ## Examples gallery
 
 Few-shot examples live under `skill/examples/<name>.brep.ts`, each with a `<name>.expected.json` baseline. Grouped by category:

package/dist/brepjs-verify.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_diff = require("./diff-mxAOOl_m.cjs");
+const require_diff = require("./diff-DDEu6YJM.cjs");
 exports.DEFAULT_TOLERANCE_PCT = require_diff.DEFAULT_TOLERANCE_PCT;
 exports.TYPECHECK_CODE = require_diff.TYPECHECK_CODE;
 exports.emptyReport = require_diff.emptyReport;

package/dist/brepjs-verify.js

@@ -1,2 +1,2 @@
-import { a as typecheckPart, c as isExpectedDims, d as emptyReport, i as TYPECHECK_CODE, l as pctDelta, m as serializeReport, n as runMeasure, o as DEFAULT_TOLERANCE_PCT, r as runPart, s as evaluateExpected, t as runDiff, u as runChecks } from "./diff-Covv1XuJ.js";
+import { a as typecheckPart, c as isExpectedDims, d as emptyReport, i as TYPECHECK_CODE, l as pctDelta, m as serializeReport, n as runMeasure, o as DEFAULT_TOLERANCE_PCT, r as runPart, s as evaluateExpected, t as runDiff, u as runChecks } from "./diff-BCECMYSQ.js";
 export { DEFAULT_TOLERANCE_PCT, TYPECHECK_CODE, emptyReport, evaluateExpected, isExpectedDims, pctDelta, runChecks, runDiff, runMeasure, runPart, serializeReport, typecheckPart };

package/dist/cli/main.cjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_diff = require("../diff-mxAOOl_m.cjs");
+const require_diff = require("../diff-DDEu6YJM.cjs");
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let commander = require("commander");
 let node_os = require("node:os");
+let node_child_process = require("node:child_process");
 //#region src/cli/scaffold.ts
 function partTemplate(name) {
 	return `import { box, cut, unwrap } from 'brepjs';
@@ -177,6 +178,43 @@ async function exportPart(modulePath, formats, outDir) {
 	};
 }
 //#endregion
+//#region src/cli/openBrowser.ts
+/**
+* Whether `--serve` should auto-open the browser for the current environment.
+*
+* Opens only for an interactive session — suppressed under CI, when stderr is
+* not a TTY (agent/piped runs), or on Linux without a display server — so
+* automation never spawns a browser unexpectedly. An explicit `--no-open` is a
+* separate, always-on override handled by the caller.
+*/
+function shouldAutoOpen({ env = process.env, platform = process.platform, isTTY = Boolean(process.stderr.isTTY) } = {}) {
+	if (env["CI"]) return false;
+	if (!isTTY) return false;
+	if (platform === "linux" && !env["DISPLAY"] && !env["WAYLAND_DISPLAY"]) return false;
+	return true;
+}
+/** The platform-specific command that opens `url` in the default browser. */
+function browserCommand(url, platform) {
+	if (platform === "darwin") return ["open", [url]];
+	if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+	return ["xdg-open", [url]];
+}
+/**
+* Best-effort open of `url` in the default browser. Never throws and never
+* blocks — a missing opener just leaves the printed URL as the fallback.
+*/
+function openBrowser(url, platform = process.platform) {
+	try {
+		const [cmd, args] = browserCommand(url, platform);
+		const child = (0, node_child_process.spawn)(cmd, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
 //#region src/cli/main.ts
 console.log = (...args) => {
 	process.stderr.write(args.map(String).join(" ") + "\n");
@@ -192,7 +230,7 @@ async function loadSnapshotShoot() {
 }
 var program = new commander.Command();
 program.name("brepjs-verify");
-program.command("verify", { isDefault: true }).argument("<file>", "path to a .brep.ts module with a default-exported part function").option("--step <out>", "write the primary STEP artifact to this path").option("--glb <out>", "write a derived GLB preview to this path").option("--json <out>", "write the JSON report to this path").option("--check", "type-check the part (against brepjs types) before running; skip execution on type errors").option("--snapshot <dir>", "render iso/front/top/right PNGs to this dir (requires built viewer)").option("--serve", "after verifying, start a preview server and print a ?dir=&file= deep link (stays running)").action(async (file, opts) => {
+program.command("verify", { isDefault: true }).argument("<file>", "path to a .brep.ts module with a default-exported part function").option("--step <out>", "write the primary STEP artifact to this path").option("--glb <out>", "write a derived GLB preview to this path").option("--json <out>", "write the JSON report to this path").option("--check", "type-check the part (against brepjs types) before running; skip execution on type errors").option("--snapshot <dir>", "render iso/front/top/right PNGs to this dir (requires built viewer)").option("--serve", "after verifying, start a preview server and print a ?dir=&file= deep link (stays running)").option("--no-open", "with --serve, do not auto-open the browser (just print the viewer URL)").action(async (file, opts) => {
 	const wantStep = Boolean(opts.step) || Boolean(opts.snapshot) || Boolean(opts.serve);
 	const { report, step, glb, shape } = await require_diff.runPart((0, node_path.resolve)(file), {
 		step: wantStep,
@@ -227,8 +265,9 @@ program.command("verify", { isDefault: true }).argument("<file>", "path to a .br
 	if (!require_diff.reportOk(report)) process.exitCode = 1;
 	if (Boolean(opts.serve) && stepPath !== void 0 && require_diff.reportOk(report) && stepPath) {
 		const { serve } = await Promise.resolve().then(() => require("../snapshot/serve.cjs"));
-		const { url } = await serve({ file: stepPath });
+		const { url, reused } = await serve({ file: stepPath });
 		process.stderr.write(`viewer: ${url}\n`);
+		if (!reused && opts.open && shouldAutoOpen()) openBrowser(url);
 	}
 });
 program.command("measure").argument("<a>", "path to a .brep.ts module").argument("[b]", "optional second module; if given, measures distance between the two parts").action(async (a, b) => {

package/dist/cli/main.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { f as pushError, h as loadBrep, m as serializeReport, n as runMeasure, p as reportOk, r as runPart, t as runDiff } from "../diff-Covv1XuJ.js";
+import { f as pushError, h as loadBrep, m as serializeReport, n as runMeasure, p as reportOk, r as runPart, t as runDiff } from "../diff-BCECMYSQ.js";
 import { fileURLToPath } from "node:url";
 import { existsSync, mkdirSync, realpathSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { Command } from "commander";
 import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
 //#region src/cli/scaffold.ts
 function partTemplate(name) {
 	return `import { box, cut, unwrap } from 'brepjs';
@@ -176,6 +177,43 @@ async function exportPart(modulePath, formats, outDir) {
 	};
 }
 //#endregion
+//#region src/cli/openBrowser.ts
+/**
+* Whether `--serve` should auto-open the browser for the current environment.
+*
+* Opens only for an interactive session — suppressed under CI, when stderr is
+* not a TTY (agent/piped runs), or on Linux without a display server — so
+* automation never spawns a browser unexpectedly. An explicit `--no-open` is a
+* separate, always-on override handled by the caller.
+*/
+function shouldAutoOpen({ env = process.env, platform = process.platform, isTTY = Boolean(process.stderr.isTTY) } = {}) {
+	if (env["CI"]) return false;
+	if (!isTTY) return false;
+	if (platform === "linux" && !env["DISPLAY"] && !env["WAYLAND_DISPLAY"]) return false;
+	return true;
+}
+/** The platform-specific command that opens `url` in the default browser. */
+function browserCommand(url, platform) {
+	if (platform === "darwin") return ["open", [url]];
+	if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+	return ["xdg-open", [url]];
+}
+/**
+* Best-effort open of `url` in the default browser. Never throws and never
+* blocks — a missing opener just leaves the printed URL as the fallback.
+*/
+function openBrowser(url, platform = process.platform) {
+	try {
+		const [cmd, args] = browserCommand(url, platform);
+		const child = spawn(cmd, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
 //#region src/cli/main.ts
 console.log = (...args) => {
 	process.stderr.write(args.map(String).join(" ") + "\n");
@@ -191,7 +229,7 @@ async function loadSnapshotShoot() {
 }
 var program = new Command();
 program.name("brepjs-verify");
-program.command("verify", { isDefault: true }).argument("<file>", "path to a .brep.ts module with a default-exported part function").option("--step <out>", "write the primary STEP artifact to this path").option("--glb <out>", "write a derived GLB preview to this path").option("--json <out>", "write the JSON report to this path").option("--check", "type-check the part (against brepjs types) before running; skip execution on type errors").option("--snapshot <dir>", "render iso/front/top/right PNGs to this dir (requires built viewer)").option("--serve", "after verifying, start a preview server and print a ?dir=&file= deep link (stays running)").action(async (file, opts) => {
+program.command("verify", { isDefault: true }).argument("<file>", "path to a .brep.ts module with a default-exported part function").option("--step <out>", "write the primary STEP artifact to this path").option("--glb <out>", "write a derived GLB preview to this path").option("--json <out>", "write the JSON report to this path").option("--check", "type-check the part (against brepjs types) before running; skip execution on type errors").option("--snapshot <dir>", "render iso/front/top/right PNGs to this dir (requires built viewer)").option("--serve", "after verifying, start a preview server and print a ?dir=&file= deep link (stays running)").option("--no-open", "with --serve, do not auto-open the browser (just print the viewer URL)").action(async (file, opts) => {
 	const wantStep = Boolean(opts.step) || Boolean(opts.snapshot) || Boolean(opts.serve);
 	const { report, step, glb, shape } = await runPart(resolve(file), {
 		step: wantStep,
@@ -226,8 +264,9 @@ program.command("verify", { isDefault: true }).argument("<file>", "path to a .br
 	if (!reportOk(report)) process.exitCode = 1;
 	if (Boolean(opts.serve) && stepPath !== void 0 && reportOk(report) && stepPath) {
 		const { serve } = await import("../snapshot/serve.js");
-		const { url } = await serve({ file: stepPath });
+		const { url, reused } = await serve({ file: stepPath });
 		process.stderr.write(`viewer: ${url}\n`);
+		if (!reused && opts.open && shouldAutoOpen()) openBrowser(url);
 	}
 });
 program.command("measure").argument("<a>", "path to a .brep.ts module").argument("[b]", "optional second module; if given, measures distance between the two parts").action(async (a, b) => {

package/dist/cli/openBrowser.d.ts

@@ -0,0 +1,23 @@
+/** Inputs that decide whether auto-opening a browser is appropriate. */
+export interface AutoOpenEnv {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    /** Whether stderr is an interactive terminal. */
+    isTTY?: boolean;
+}
+/**
+ * Whether `--serve` should auto-open the browser for the current environment.
+ *
+ * Opens only for an interactive session — suppressed under CI, when stderr is
+ * not a TTY (agent/piped runs), or on Linux without a display server — so
+ * automation never spawns a browser unexpectedly. An explicit `--no-open` is a
+ * separate, always-on override handled by the caller.
+ */
+export declare function shouldAutoOpen({ env, platform, isTTY, }?: AutoOpenEnv): boolean;
+/** The platform-specific command that opens `url` in the default browser. */
+export declare function browserCommand(url: string, platform: NodeJS.Platform): [string, string[]];
+/**
+ * Best-effort open of `url` in the default browser. Never throws and never
+ * blocks — a missing opener just leaves the printed URL as the fallback.
+ */
+export declare function openBrowser(url: string, platform?: NodeJS.Platform): void;

package/dist/{diff-Covv1XuJ.js → diff-BCECMYSQ.js}

@@ -162,6 +162,14 @@ var HINT_TABLE = {
 		fix: "The boolean subtraction failed — often a tool that does not actually intersect the base, or tolerance issues.",
 		nextStep: "Confirm the tool overlaps the base, optionally heal the inputs, then re-cut."
 	},
+	FILLET_FAILED: {
+		fix: "The fillet could not be built — usually the radius is too large for an edge it touched (it cannot exceed the adjacent face/wall), or you filleted EVERY edge (the no-edge-list form) including ones too thin to round.",
+		nextStep: "Select only the edges you mean to round — e.g. edgeFinder().inDirection(\"Z\").findAll(solid) — and/or reduce the radius below the thinnest adjacent wall, then re-verify."
+	},
+	CHAMFER_FAILED: {
+		fix: "The chamfer could not be built — usually the distance is too large for an edge it touched, or you chamfered EVERY edge (the no-edge-list form) including ones too thin.",
+		nextStep: "Select only the target edges with an edge finder and/or reduce the distance below the shortest adjacent edge, then re-verify."
+	},
 	BOOLEAN_HAS_ERRORS: {
 		fix: "The boolean ran but the kernel reported errors (often coincident faces or near-tangent contact).",
 		nextStep: "Perturb one operand slightly so contact is a clean overlap, or heal the inputs, then retry."
@@ -197,6 +205,10 @@ var HINT_TABLE = {
 	TYPECHECK: {
 		fix: "Fix the TypeScript type error before running the part — the API call or value does not match brepjs’s types.",
 		nextStep: "Correct the flagged type (e.g. argument/return type or import), then re-verify."
+	},
+	EXPECTED_UNKNOWN_KEY: {
+		fix: "Your `expected` block has keys the CLI does not assert (so the intended check never ran). Bounds must be `{ xMin, xMax, yMin, yMax, zMin, zMax }` — not `{ min, max }` or `{ x, y, z }`.",
+		nextStep: "Rewrite `expected` using only volume, area, tolerancePct, and bounds.{xMin..zMax}, then re-verify."
 	}
 };
 /** Synthetic code attached to validity-check failures (validSolid returns a plain string error). */
@@ -247,7 +259,7 @@ function shapeTypeOf(brep, s) {
 	return "Unknown";
 }
 function runChecks(brep, shape) {
-	const { isSolid, isShape3D, isFace, measureVolume, measureArea, getBounds, validSolid, isOk } = brep;
+	const { isSolid, isShape3D, isFace, measureVolumeProps, measureArea, getBounds, getFaces, getEdges, getWires, getVertices, getSolids, getShells, isManifoldShell, validSolid, isOk } = brep;
 	const r = emptyReport();
 	r.shapeType = shapeTypeOf(brep, shape);
 	if (isSolid(shape)) {
@@ -264,19 +276,41 @@ function runChecks(brep, shape) {
 			});
 		}
 		r.checks.push(validCheck);
+	} else {
+		const solids = getSolids(shape);
+		if (solids.length > 0) {
+			const failures = [];
+			solids.forEach((s, i) => {
+				const v = validSolid(s);
+				if (!isOk(v)) failures.push(`body ${i}: ${v.error}`);
+			});
+			const bodiesCheck = {
+				name: "allBodiesValid",
+				passed: failures.length === 0
+			};
+			if (failures.length > 0) {
+				bodiesCheck.detail = `${failures.length}/${solids.length} bodies invalid — ${failures.join("; ")}`;
+				r.errorInfos.push({
+					message: `allBodiesValid: ${bodiesCheck.detail}`,
+					code: VALIDITY_FAILURE_CODE
+				});
+			}
+			r.checks.push(bodiesCheck);
+		}
 	}
 	if (isShape3D(shape)) {
-		const vol = measureVolume(shape);
-		if (isOk(vol)) {
-			r.measurements.volume = vol.value;
+		const volProps = measureVolumeProps(shape);
+		if (isOk(volProps)) {
+			r.measurements.volume = volProps.value.volume;
+			r.measurements.centerOfMass = volProps.value.centerOfMass;
 			r.checks.push({
 				name: "positiveVolume",
-				passed: vol.value > 0
+				passed: volProps.value.volume > 0
 			});
 		} else pushError(r, {
-			message: `measureVolume: ${vol.error.message}`,
-			code: vol.error.code,
-			suggestion: vol.error.suggestion
+			message: `measureVolume: ${volProps.error.message}`,
+			code: volProps.error.code,
+			suggestion: volProps.error.suggestion
 		});
 	}
 	if (isFace(shape) || isShape3D(shape)) {
@@ -288,6 +322,18 @@ function runChecks(brep, shape) {
 	} catch (e) {
 		pushError(r, { message: `getBounds: ${e.message}` });
 	}
+	try {
+		r.topology = {
+			faceCount: getFaces(shape).length,
+			edgeCount: getEdges(shape).length,
+			wireCount: getWires(shape).length,
+			vertexCount: getVertices(shape).length
+		};
+	} catch {}
+	if (r.topology) try {
+		const shells = getShells(shape);
+		if (shells.length > 0) r.topology.manifold = shells.every((s) => isManifoldShell(s));
+	} catch {}
 	r.hints = buildHints(r);
 	return r;
 }
@@ -300,8 +346,38 @@ function pctDelta(actual, expected) {
 	return Math.abs(actual - expected) / Math.abs(expected) * 100;
 }
 function withinTolerance(actual, expected, tolerancePct) {
+	if (Math.abs(actual - expected) <= 1e-6) return true;
 	return pctDelta(actual, expected) <= tolerancePct;
 }
+var TOP_LEVEL_KEYS = new Set([
+	"volume",
+	"area",
+	"bounds",
+	"tolerancePct"
+]);
+var BOUND_KEYS = new Set([
+	"xMin",
+	"xMax",
+	"yMin",
+	"yMax",
+	"zMin",
+	"zMax"
+]);
+/**
+* Keys in an `expected` block that the CLI does not understand and would silently ignore — a
+* `{ min: [...], max: [...] }` or `{ x: [...] }` bounds shape, or a misspelled top-level field.
+* Surfaced as an error (not dropped) so a wrong `expected` shape fails loud instead of passing
+* vacuously with the intended assertion never run.
+*/
+function unknownExpectedKeys(expected) {
+	const bad = [];
+	for (const k of Object.keys(expected)) if (!TOP_LEVEL_KEYS.has(k)) bad.push(k);
+	const bounds = expected.bounds;
+	if (bounds && typeof bounds === "object") {
+		for (const k of Object.keys(bounds)) if (!BOUND_KEYS.has(k)) bad.push(`bounds.${k}`);
+	}
+	return bad;
+}
 function isExpectedDims(v) {
 	if (typeof v !== "object" || v === null) return false;
 	const r = v;
@@ -425,6 +501,25 @@ var COMPILER_OPTIONS = {
 	skipLibCheck: true,
 	allowImportingTsExtensions: true
 };
+/**
+* Locate the `@types/node` declarations so a part may import Node built-ins (`node:fs` to load a
+* font, `node:fs/promises` to read a STEP file, etc.) without `--check` failing on the import.
+* Returns the `@types` directory to use as a `typeRoots` entry. Probes the tool's own install
+* first (where `@types/node` ships as a dependency), then the part's directory.
+*/
+function nodeTypesRoot(partPath, toolDir) {
+	const froms = [
+		import.meta.url,
+		toolDir ? pathToFileURL(resolve(toolDir, "package.json")).href : void 0,
+		pathToFileURL(partPath).href
+	];
+	for (const from of froms) {
+		if (!from) continue;
+		try {
+			return dirname(dirname(createRequire(from).resolve("@types/node/package.json")));
+		} catch {}
+	}
+}
 function diagnosticToErrorInfo(d) {
 	const text = ts.flattenDiagnosticMessageText(d.messageText, "\n");
 	let where = "";
@@ -449,6 +544,11 @@ function typecheckPart(partPath, toolDir) {
 	const dts = resolveBrepjsTypes(partPath, toolDir);
 	const options = { ...COMPILER_OPTIONS };
 	if (dts) options.paths = { brepjs: [dts] };
+	const typesRoot = nodeTypesRoot(partPath, toolDir);
+	if (typesRoot) {
+		options.typeRoots = [typesRoot];
+		options.types = ["node"];
+	}
 	const program = ts.createProgram([partPath], options);
 	const errors = [
 		...program.getSemanticDiagnostics(),
@@ -462,6 +562,39 @@ function typecheckPart(partPath, toolDir) {
 }
 //#endregion
 //#region src/verify/runPart.ts
+/** Centroid of a face group's vertices, in part (Z-up, mm) coordinates. */
+function faceCentroid(m, start, count) {
+	let x = 0;
+	let y = 0;
+	let z = 0;
+	for (let i = start; i < start + count; i++) {
+		const vi = (m.triangles[i] ?? 0) * 3;
+		x += m.vertices[vi] ?? 0;
+		y += m.vertices[vi + 1] ?? 0;
+		z += m.vertices[vi + 2] ?? 0;
+	}
+	const n = count || 1;
+	return [
+		x / n,
+		y / n,
+		z / n
+	];
+}
+function buildMaterialMap(m, spec) {
+	if (spec === void 0 || spec === null) return {};
+	if (typeof spec !== "function" && (typeof spec !== "object" || Array.isArray(spec))) return { warning: "export const materials must be a function or a material object — ignored" };
+	const sel = spec;
+	const select = typeof sel === "function" ? sel : () => sel;
+	const map = /* @__PURE__ */ new Map();
+	for (const fg of m.faceGroups) {
+		const mat = select({
+			faceId: fg.faceId,
+			center: faceCentroid(m, fg.start, fg.count)
+		});
+		if (mat) map.set(fg.faceId, mat);
+	}
+	return map.size > 0 ? { map } : {};
+}
 async function loadPart(modulePath) {
 	try {
 		return await import(pathToFileURL(modulePath).href);
@@ -485,7 +618,13 @@ function toErrorInfo(prefix, e) {
 		code: e.code,
 		suggestion: e.suggestion
 	};
-	if (e instanceof Error) return { message: `${prefix}: ${e.message}` };
+	if (e instanceof Error) {
+		const code = e.message.match(/\[[A-Z][A-Z0-9_]*\]\s+([A-Z][A-Z0-9_]+):/)?.[1];
+		return code ? {
+			message: `${prefix}: ${e.message}`,
+			code
+		} : { message: `${prefix}: ${e.message}` };
+	}
 	return { message: `${prefix}: ${String(e)}` };
 }
 function finalize(result) {
@@ -565,11 +704,22 @@ async function runPart(modulePath, opts = {}) {
 	if (isExpectedDims(mod.expected)) {
 		const expected = mod.expected;
 		result.assertions = evaluateExpected(expected, result.measurements);
+		const unknown = unknownExpectedKeys(expected);
+		if (unknown.length > 0) pushError(result, {
+			message: `expected has unrecognized keys (ignored): ${unknown.join(", ")}. Valid keys: volume, area, tolerancePct, bounds.{xMin,xMax,yMin,yMax,zMin,zMax}.`,
+			code: "EXPECTED_UNKNOWN_KEY"
+		});
 	}
 	let glb;
 	let step;
 	if (opts.glb) try {
-		glb = exportGlb(mesh(shape));
+		const shapeMesh = mesh(shape);
+		const { map, warning } = buildMaterialMap(shapeMesh, mod.materials);
+		if (warning) pushError(result, {
+			message: `materials: ${warning}`,
+			code: "MATERIALS_IGNORED"
+		});
+		glb = map ? exportGlb(shapeMesh, { materials: map }) : exportGlb(shapeMesh);
 	} catch (e) {
 		pushError(result, toErrorInfo("exportGlb", e));
 	}