brepjs-cad 0.175.0 → 0.176.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.176.0](https://github.com/andymai/brepjs/compare/brepjs-cad-v0.175.0...brepjs-cad-v0.176.0) (2026-08-26)
+
+
+### Features
+
+* **brepjs-cad:** brep preview — element-aware model viewer with live watch ([#2231](https://github.com/andymai/brepjs/issues/2231)) ([002a20f](https://github.com/andymai/brepjs/commit/002a20f9ad8d38cb812f00a875583bdb850a004d))
+
 ## [0.175.0](https://github.com/andymai/brepjs/compare/brepjs-cad-v0.174.0...brepjs-cad-v0.175.0) (2026-08-26)
 
 

package/dist/brepjs-cad.cjs

@@ -1,14 +1,15 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_diff = require("./diff-DX9zgrss.cjs");
-exports.DEFAULT_TOLERANCE_PCT = require_diff.DEFAULT_TOLERANCE_PCT;
-exports.TYPECHECK_CODE = require_diff.TYPECHECK_CODE;
-exports.emptyReport = require_diff.emptyReport;
-exports.evaluateExpected = require_diff.evaluateExpected;
-exports.isExpectedDims = require_diff.isExpectedDims;
-exports.pctDelta = require_diff.pctDelta;
-exports.runChecks = require_diff.runChecks;
+const require_usingCtx = require("./usingCtx-DNbyRoEg.cjs");
+const require_diff = require("./diff-CmIV_qOi.cjs");
+exports.DEFAULT_TOLERANCE_PCT = require_usingCtx.DEFAULT_TOLERANCE_PCT;
+exports.TYPECHECK_CODE = require_usingCtx.TYPECHECK_CODE;
+exports.emptyReport = require_usingCtx.emptyReport;
+exports.evaluateExpected = require_usingCtx.evaluateExpected;
+exports.isExpectedDims = require_usingCtx.isExpectedDims;
+exports.pctDelta = require_usingCtx.pctDelta;
+exports.runChecks = require_usingCtx.runChecks;
 exports.runDiff = require_diff.runDiff;
 exports.runMeasure = require_diff.runMeasure;
-exports.runPart = require_diff.runPart;
-exports.serializeReport = require_diff.serializeReport;
-exports.typecheckPart = require_diff.typecheckPart;
+exports.runPart = require_usingCtx.runPart;
+exports.serializeReport = require_usingCtx.serializeReport;
+exports.typecheckPart = require_usingCtx.typecheckPart;

package/dist/brepjs-cad.js

@@ -1,2 +1,3 @@
-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-B1sSWjLa.js";
+import { c as evaluateExpected, d as runChecks, f as emptyReport, h as serializeReport, i as TYPECHECK_CODE, l as isExpectedDims, o as typecheckPart, r as runPart, s as DEFAULT_TOLERANCE_PCT, u as pctDelta } from "./usingCtx-DOzK2eJh.js";
+import { n as runMeasure, t as runDiff } from "./diff-C2vDUt9F.js";
 export { DEFAULT_TOLERANCE_PCT, TYPECHECK_CODE, emptyReport, evaluateExpected, isExpectedDims, pctDelta, runChecks, runDiff, runMeasure, runPart, serializeReport, typecheckPart };

package/dist/cli/main.cjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_diff = require("../diff-DX9zgrss.cjs");
+const require_usingCtx = require("../usingCtx-DNbyRoEg.cjs");
+const require_diff = require("../diff-CmIV_qOi.cjs");
+const require_openBrowser = require("../openBrowser-C1AiX6cC.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';
@@ -97,114 +98,20 @@ function scaffoldPart(name, dir) {
 		files
 	};
 }
-function debounce(fn, delayMs = 150) {
-	let timer;
-	const cancel = () => {
-		if (timer) {
-			clearTimeout(timer);
-			timer = void 0;
-		}
-	};
-	const trigger = () => {
-		cancel();
-		timer = setTimeout(() => {
-			timer = void 0;
-			fn();
-		}, delayMs);
-	};
-	return {
-		trigger,
-		cancel
-	};
-}
-var SOURCE_FILE_RE = /\.(?:m?[jt]s|[jt]sx)$/;
-function isWatchRelevant(filename) {
-	if (filename === void 0 || filename === null) return true;
-	const name = filename.toString();
-	if (/(?:^|[\\/])tsconfig(?:\..+)?\.json$/.test(name)) return true;
-	return SOURCE_FILE_RE.test(name);
-}
-/**
-* Root the watcher at the project, not the entry's own directory: with the common
-* `src/main.ts` layout, tsconfig.json (whose JSX options change how sources transpile)
-* and `../` imports live one level up. Nearest package.json or tsconfig.json walking up
-* wins; entries with no project marker fall back to their own directory.
-*/
-function watchRootFor(entryPath) {
-	const start = (0, node_path.dirname)(entryPath);
-	let dir = start;
-	for (;;) {
-		if ((0, node_fs.existsSync)((0, node_path.join)(dir, "package.json")) || (0, node_fs.existsSync)((0, node_path.join)(dir, "tsconfig.json"))) return dir;
-		const parent = (0, node_path.dirname)(dir);
-		if (parent === dir) return start;
-		dir = parent;
-	}
-}
-var IGNORED_DIR_NAMES = /* @__PURE__ */ new Set([
-	"node_modules",
-	"dist",
-	".git"
-]);
-/**
-* Watch a directory tree with one non-recursive `fs.watch` per directory, skipping
-* node_modules/dist/.git and never following symlinks. `fs.watch({recursive})` has no
-* exclusion API, so on a real project it would descend into node_modules — tens of
-* thousands of inotify watches. Whenever an event fires in a directory it is re-scanned,
-* which picks up newly created subdirectories. Returns a stop function.
-*/
-function watchTree(root, onEvent) {
-	const watchers = /* @__PURE__ */ new Map();
-	const add = (dir) => {
-		if (watchers.has(dir)) return;
-		try {
-			watchers.set(dir, (0, node_fs.watch)(dir, (_event, filename) => {
-				scan(dir);
-				onEvent(filename);
-			}));
-		} catch {}
-	};
-	const scan = (dir) => {
-		let entries;
-		try {
-			entries = (0, node_fs.readdirSync)(dir, { withFileTypes: true });
-		} catch {
-			return;
-		}
-		for (const entry of entries) {
-			if (!entry.isDirectory() || IGNORED_DIR_NAMES.has(entry.name)) continue;
-			const child = (0, node_path.join)(dir, entry.name);
-			if (watchers.has(child)) continue;
-			add(child);
-			scan(child);
-		}
-	};
-	add(root);
-	scan(root);
-	return () => {
-		for (const watcher of watchers.values()) watcher.close();
-		watchers.clear();
-	};
-}
-//#endregion
-//#region src/disposeShape.ts
-function disposeShape(shape) {
-	const disposer = shape?.[Symbol.dispose];
-	if (typeof disposer === "function") disposer.call(shape);
-}
 //#endregion
 //#region src/cli/exportPart.ts
 function stem(file) {
 	return (0, node_path.basename)(file).replace(/\.brep\.ts$/, "").replace(/\.ts$/, "");
 }
 async function exportPart(modulePath, formats, outDir) {
-	const { shape, report, step, glb } = await require_diff.runPart(modulePath, {
+	const { shape, report, step, glb } = await require_usingCtx.runPart(modulePath, {
 		step: Boolean(formats.step),
 		glb: Boolean(formats.glb)
 	});
 	const errors = [];
 	const written = [];
-	if (!(require_diff.reportOk(report) && shape !== null)) {
-		disposeShape(shape);
+	if (!(require_usingCtx.reportOk(report) && shape !== null)) {
+		require_openBrowser.disposeShape(shape);
 		const failures = report.errorInfos.map((e) => e.message);
 		return {
 			ok: false,
@@ -231,7 +138,7 @@ async function exportPart(modulePath, formats, outDir) {
 			} else errors.push("GLB export produced no data");
 		}
 		if (formats.stl) {
-			const { exportSTL, isOk } = await require_diff.loadBrep();
+			const { exportSTL, isOk } = await require_usingCtx.loadBrep();
 			const r = exportSTL(shape);
 			if (isOk(r)) {
 				const p = (0, node_path.join)(outDir, `${base}.stl`);
@@ -240,7 +147,7 @@ async function exportPart(modulePath, formats, outDir) {
 			} else errors.push(`STL export: ${r.error.message}`);
 		}
 	} finally {
-		disposeShape(shape);
+		require_openBrowser.disposeShape(shape);
 	}
 	return {
 		ok: errors.length === 0,
@@ -250,43 +157,6 @@ 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/snapshot/aiming.ts
 /**
 * Kernel-anchored marks for the judge: `B<index>` at each body's bbox centroid (only for multi-body
@@ -372,14 +242,14 @@ program.command("verify", { isDefault: true }).argument("<files...>", "path(s) o
 		if (opts.step || opts.serve || opts.snapshot || opts.glb || opts.expectCode || opts.expectInvalid) process.stderr.write("batch mode: --step/--glb/--serve/--snapshot/--expect-code/--expect-invalid ignored (single-file only)\n");
 		const results = [];
 		for (const f of targets) {
-			const { report, shape } = await require_diff.runPart(f, {
+			const { report, shape } = await require_usingCtx.runPart(f, {
 				check: Boolean(opts.check),
 				metrics: Boolean(opts.metrics)
 			});
-			disposeShape(shape);
+			require_openBrowser.disposeShape(shape);
 			results.push({
 				file: f,
-				ok: require_diff.reportOk(report),
+				ok: require_usingCtx.reportOk(report),
 				report
 			});
 		}
@@ -391,7 +261,7 @@ program.command("verify", { isDefault: true }).argument("<files...>", "path(s) o
 	}
 	const file = targets[0] ?? files[0] ?? "";
 	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), {
+	const { report, step, glb, shape } = await require_usingCtx.runPart((0, node_path.resolve)(file), {
 		step: wantStep,
 		glb: Boolean(opts.glb),
 		check: Boolean(opts.check),
@@ -419,27 +289,27 @@ program.command("verify", { isDefault: true }).argument("<files...>", "path(s) o
 			}
 		} else if (opts.snapshot) process.stderr.write("snapshot skipped: STEP export produced no artifact\n");
 	} catch (e) {
-		require_diff.pushError(report, { message: `artifact write failed: ${e.message}` });
+		require_usingCtx.pushError(report, { message: `artifact write failed: ${e.message}` });
 	} finally {
-		disposeShape(shape);
+		require_openBrowser.disposeShape(shape);
 	}
-	const json = require_diff.serializeReport(report);
+	const json = require_usingCtx.serializeReport(report);
 	if (opts.json && opts.json !== "-") (0, node_fs.writeFileSync)(opts.json, json);
 	process.stdout.write(json + "\n");
-	if (!require_diff.reportOk(report)) process.exitCode = 1;
+	if (!require_usingCtx.reportOk(report)) process.exitCode = 1;
 	if (opts.expectInvalid || opts.expectCode) {
 		const codes = [...new Set(report.errorInfos.map((e) => e.code).filter((c) => Boolean(c)))];
-		const valid = require_diff.reportOk(report);
+		const valid = require_usingCtx.reportOk(report);
 		const pass = (!opts.expectInvalid || !valid) && (!opts.expectCode || codes.includes(opts.expectCode));
 		process.exitCode = pass ? 0 : 1;
 		process.stderr.write(`expect: ${pass ? "PASS" : "FAIL"}` + (opts.expectCode ? ` code=${opts.expectCode}` : "") + (opts.expectInvalid ? " invalid" : "") + ` (ok=${valid}, codes=${codes.join(",") || "none"})\n`);
 		return;
 	}
-	if (Boolean(opts.serve) && stepPath !== void 0 && require_diff.reportOk(report) && stepPath) {
+	if (Boolean(opts.serve) && stepPath !== void 0 && require_usingCtx.reportOk(report) && stepPath) {
 		const { serve } = await Promise.resolve().then(() => require("../snapshot/serve.cjs"));
 		const { url, reused } = await serve({ file: stepPath });
 		process.stderr.write(`viewer: ${url}\n`);
-		if (!reused && opts.open && shouldAutoOpen()) openBrowser(url);
+		if (!reused && opts.open && require_openBrowser.shouldAutoOpen()) require_openBrowser.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) => {
@@ -462,14 +332,14 @@ program.command("snapshot").argument("<file>", "path to a .brep.ts module; rende
 	const resolved = (0, node_path.resolve)(file);
 	const base = opts.out ? (0, node_path.resolve)(opts.out) : `${resolved}-shots`;
 	const outDir = opts.label ? (0, node_path.join)(base, opts.label) : base;
-	const { report, step, shape } = await require_diff.runPart(resolved, {
+	const { report, step, shape } = await require_usingCtx.runPart(resolved, {
 		step: true,
 		metrics: true
 	});
 	try {
 		if (!step) {
 			process.stderr.write("snapshot: part produced no STEP — nothing to render\n");
-			process.stdout.write(require_diff.serializeReport(report) + "\n");
+			process.stdout.write(require_usingCtx.serializeReport(report) + "\n");
 			process.exitCode = 1;
 			return;
 		}
@@ -477,7 +347,7 @@ program.command("snapshot").argument("<file>", "path to a .brep.ts module; rende
 		(0, node_fs.writeFileSync)(stepPath, Buffer.from(step));
 		const shoot = await loadSnapshotShoot();
 		if (!shoot) {
-			process.stdout.write(require_diff.serializeReport(report) + "\n");
+			process.stdout.write(require_usingCtx.serializeReport(report) + "\n");
 			return;
 		}
 		const section = aimedSection(report.manufacturability?.bores ?? [], report.measurements.bounds);
@@ -491,7 +361,7 @@ program.command("snapshot").argument("<file>", "path to a .brep.ts module; rende
 		});
 		for (const p of pngs) process.stdout.write(`${p}\n`);
 	} finally {
-		disposeShape(shape);
+		require_openBrowser.disposeShape(shape);
 	}
 });
 program.command("init").argument("<name>", "part name; scaffolds <name>.brep.ts + tsconfig.json + README.md").option("--out <dir>", "target directory (defaults to ./<name>)").action((name, opts) => {
@@ -506,40 +376,22 @@ program.command("watch").argument("<file>", "path to a .brep.ts module; re-verif
 	const path = (0, node_path.resolve)(file);
 	const run = async (fresh) => {
 		try {
-			const { report, shape } = await require_diff.runPart(path, { freshImport: fresh });
+			const { report, shape } = await require_usingCtx.runPart(path, { freshImport: fresh });
 			try {
-				process.stdout.write(require_diff.serializeReport(report) + "\n");
+				process.stdout.write(require_usingCtx.serializeReport(report) + "\n");
 			} finally {
-				disposeShape(shape);
+				require_openBrowser.disposeShape(shape);
 			}
 		} catch (e) {
 			process.stderr.write(`watch run failed: ${e.message}\n`);
 		}
 	};
-	let inFlight = false;
-	let rerunQueued = false;
-	const start = (fresh) => {
-		inFlight = true;
-		run(fresh).finally(() => {
-			inFlight = false;
-			if (rerunQueued) {
-				rerunQueued = false;
-				start(true);
-			}
-		});
-	};
-	const schedule = () => {
-		if (inFlight) {
-			rerunQueued = true;
-			return;
-		}
-		start(true);
-	};
-	const { trigger } = debounce(schedule, 150);
+	const runner = require_openBrowser.createSerialRunner(run);
+	const { trigger } = require_openBrowser.debounce(runner.trigger, 150);
 	process.stderr.write(`watching ${path} (Ctrl-C to stop)\n`);
-	start(false);
-	const stopWatching = watchTree(watchRootFor(path), (filename) => {
-		if (isWatchRelevant(filename)) trigger();
+	runner.start(false);
+	const stopWatching = require_openBrowser.watchTree(require_openBrowser.watchRootFor(path), (filename) => {
+		if (require_openBrowser.isWatchRelevant(filename)) trigger();
 	});
 	const stop = () => {
 		stopWatching();
@@ -548,6 +400,15 @@ program.command("watch").argument("<file>", "path to a .brep.ts module; re-verif
 	process.on("SIGINT", stop);
 	process.on("SIGTERM", stop);
 });
+program.command("preview").argument("<file>", "path to a model module (.ts/.tsx); a families element tree renders per element").option("--watch", "re-evaluate on save and push updates to the open viewer tab").option("--write-only", "write artifacts and exit without starting the viewer server").option("--glb <out>", "write a merged GLB of the whole model").option("--json <out>", "write the JSON summary to this path").option("--port <n>", "viewer server port (default: OS-assigned)", (v) => parseInt(v, 10)).option("--no-open", "do not auto-open the browser").action(async (file, opts) => {
+	const { runPreview } = await Promise.resolve().then(() => require("../preview/preview.cjs"));
+	try {
+		await runPreview((0, node_path.resolve)(file), opts);
+	} catch (e) {
+		process.stderr.write(`preview failed: ${e.message}\n`);
+		process.exitCode = 1;
+	}
+});
 program.command("export").argument("<file>", "path to a .brep.ts module").option("--step", "write a STEP artifact").option("--glb", "write a GLB artifact").option("--stl", "write an STL artifact").option("--all", "write STEP + GLB + STL").option("--out <dir>", "output directory", ".").action(async (file, opts) => {
 	const formats = opts.all ? {
 		step: true,

package/dist/cli/main.js

@@ -1,11 +1,12 @@
 #!/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-B1sSWjLa.js";
+import { _ as loadBrep, h as serializeReport, m as reportOk, p as pushError, r as runPart } from "../usingCtx-DOzK2eJh.js";
+import { n as runMeasure, t as runDiff } from "../diff-C2vDUt9F.js";
+import { a as debounce, c as watchTree, i as createSerialRunner, n as shouldAutoOpen, o as isWatchRelevant, r as disposeShape, s as watchRootFor, t as openBrowser } from "../openBrowser-BBYw6VVb.js";
 import { fileURLToPath } from "node:url";
-import { existsSync, globSync, mkdirSync, readdirSync, realpathSync, watch, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, globSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { basename, 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';
@@ -96,100 +97,6 @@ function scaffoldPart(name, dir) {
 		files
 	};
 }
-function debounce(fn, delayMs = 150) {
-	let timer;
-	const cancel = () => {
-		if (timer) {
-			clearTimeout(timer);
-			timer = void 0;
-		}
-	};
-	const trigger = () => {
-		cancel();
-		timer = setTimeout(() => {
-			timer = void 0;
-			fn();
-		}, delayMs);
-	};
-	return {
-		trigger,
-		cancel
-	};
-}
-var SOURCE_FILE_RE = /\.(?:m?[jt]s|[jt]sx)$/;
-function isWatchRelevant(filename) {
-	if (filename === void 0 || filename === null) return true;
-	const name = filename.toString();
-	if (/(?:^|[\\/])tsconfig(?:\..+)?\.json$/.test(name)) return true;
-	return SOURCE_FILE_RE.test(name);
-}
-/**
-* Root the watcher at the project, not the entry's own directory: with the common
-* `src/main.ts` layout, tsconfig.json (whose JSX options change how sources transpile)
-* and `../` imports live one level up. Nearest package.json or tsconfig.json walking up
-* wins; entries with no project marker fall back to their own directory.
-*/
-function watchRootFor(entryPath) {
-	const start = dirname(entryPath);
-	let dir = start;
-	for (;;) {
-		if (existsSync(join(dir, "package.json")) || existsSync(join(dir, "tsconfig.json"))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return start;
-		dir = parent;
-	}
-}
-var IGNORED_DIR_NAMES = /* @__PURE__ */ new Set([
-	"node_modules",
-	"dist",
-	".git"
-]);
-/**
-* Watch a directory tree with one non-recursive `fs.watch` per directory, skipping
-* node_modules/dist/.git and never following symlinks. `fs.watch({recursive})` has no
-* exclusion API, so on a real project it would descend into node_modules — tens of
-* thousands of inotify watches. Whenever an event fires in a directory it is re-scanned,
-* which picks up newly created subdirectories. Returns a stop function.
-*/
-function watchTree(root, onEvent) {
-	const watchers = /* @__PURE__ */ new Map();
-	const add = (dir) => {
-		if (watchers.has(dir)) return;
-		try {
-			watchers.set(dir, watch(dir, (_event, filename) => {
-				scan(dir);
-				onEvent(filename);
-			}));
-		} catch {}
-	};
-	const scan = (dir) => {
-		let entries;
-		try {
-			entries = readdirSync(dir, { withFileTypes: true });
-		} catch {
-			return;
-		}
-		for (const entry of entries) {
-			if (!entry.isDirectory() || IGNORED_DIR_NAMES.has(entry.name)) continue;
-			const child = join(dir, entry.name);
-			if (watchers.has(child)) continue;
-			add(child);
-			scan(child);
-		}
-	};
-	add(root);
-	scan(root);
-	return () => {
-		for (const watcher of watchers.values()) watcher.close();
-		watchers.clear();
-	};
-}
-//#endregion
-//#region src/disposeShape.ts
-function disposeShape(shape) {
-	const disposer = shape?.[Symbol.dispose];
-	if (typeof disposer === "function") disposer.call(shape);
-}
 //#endregion
 //#region src/cli/exportPart.ts
 function stem(file) {
@@ -249,43 +156,6 @@ 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/snapshot/aiming.ts
 /**
 * Kernel-anchored marks for the judge: `B<index>` at each body's bbox centroid (only for multi-body
@@ -515,28 +385,10 @@ program.command("watch").argument("<file>", "path to a .brep.ts module; re-verif
 			process.stderr.write(`watch run failed: ${e.message}\n`);
 		}
 	};
-	let inFlight = false;
-	let rerunQueued = false;
-	const start = (fresh) => {
-		inFlight = true;
-		run(fresh).finally(() => {
-			inFlight = false;
-			if (rerunQueued) {
-				rerunQueued = false;
-				start(true);
-			}
-		});
-	};
-	const schedule = () => {
-		if (inFlight) {
-			rerunQueued = true;
-			return;
-		}
-		start(true);
-	};
-	const { trigger } = debounce(schedule, 150);
+	const runner = createSerialRunner(run);
+	const { trigger } = debounce(runner.trigger, 150);
 	process.stderr.write(`watching ${path} (Ctrl-C to stop)\n`);
-	start(false);
+	runner.start(false);
 	const stopWatching = watchTree(watchRootFor(path), (filename) => {
 		if (isWatchRelevant(filename)) trigger();
 	});
@@ -547,6 +399,15 @@ program.command("watch").argument("<file>", "path to a .brep.ts module; re-verif
 	process.on("SIGINT", stop);
 	process.on("SIGTERM", stop);
 });
+program.command("preview").argument("<file>", "path to a model module (.ts/.tsx); a families element tree renders per element").option("--watch", "re-evaluate on save and push updates to the open viewer tab").option("--write-only", "write artifacts and exit without starting the viewer server").option("--glb <out>", "write a merged GLB of the whole model").option("--json <out>", "write the JSON summary to this path").option("--port <n>", "viewer server port (default: OS-assigned)", (v) => parseInt(v, 10)).option("--no-open", "do not auto-open the browser").action(async (file, opts) => {
+	const { runPreview } = await import("../preview/preview.js");
+	try {
+		await runPreview(resolve(file), opts);
+	} catch (e) {
+		process.stderr.write(`preview failed: ${e.message}\n`);
+		process.exitCode = 1;
+	}
+});
 program.command("export").argument("<file>", "path to a .brep.ts module").option("--step", "write a STEP artifact").option("--glb", "write a GLB artifact").option("--stl", "write an STL artifact").option("--all", "write STEP + GLB + STL").option("--out <dir>", "output directory", ".").action(async (file, opts) => {
 	const formats = opts.all ? {
 		step: true,

package/dist/cli/watch.d.ts

@@ -19,3 +19,12 @@ export declare function watchRootFor(entryPath: string): string;
  * which picks up newly created subdirectories. Returns a stop function.
  */
 export declare function watchTree(root: string, onEvent: (filename: string | Buffer | null | undefined) => void): () => void;
+/**
+ * Serialize an async job: while one run is in flight, triggers coalesce into exactly
+ * one trailing rerun (verify/preview runs share one kernel — overlapping runs would
+ * interleave output and reorder reports).
+ */
+export declare function createSerialRunner(run: (fresh: boolean) => Promise<void>): {
+    start: (fresh: boolean) => void;
+    trigger: () => void;
+};