brepjs-cad 0.1.0

package/dist/diff-ByiVwVrr.js

@@ -0,0 +1,509 @@
+import { cut, exportGlb, exportSTEP, getBounds, init, isCompSolid, isCompound, isEdge, isFace, isOk, isShape3D, isShell, isSolid, isVertex, isWire, measureArea, measureDistance, measureLength, measureVolume, mesh, validSolid } from "brepjs";
+//#region src/verify/report.ts
+function emptyReport() {
+	return {
+		shapeType: null,
+		checks: [],
+		measurements: {},
+		errors: [],
+		errorInfos: [],
+		hints: []
+	};
+}
+/** Record a failure on the report, keeping the flat `errors` string list and structured `errorInfos` in sync. */
+function pushError(r, info) {
+	r.errors.push(info.message);
+	r.errorInfos.push(info);
+}
+function reportOk(r) {
+	return r.errors.length === 0 && r.checks.every((c) => c.passed);
+}
+/**
+* Local, brepjs-cad-owned advice keyed on `BrepErrorCode` values (see `brepjs`'s public
+* `BrepErrorCode`). Intentionally not importing the library's internal `getSuggestionForCode`:
+* this table is the agent loop's own actionable `fix` + `nextStep` guidance, and the library's
+* public `BrepError.suggestion` is still surfaced alongside it on each hint.
+*/
+var HINT_TABLE = {
+	FILLET_NO_EDGES: {
+		fix: "Select real edges before filleting — pass an edge query (e.g. find edges by direction/position) or a non-empty edge list, not the whole solid.",
+		nextStep: "List the solid’s edges, pick the ones to round, then call fillet(solid, radius, edges)."
+	},
+	CHAMFER_NO_EDGES: {
+		fix: "Select real edges before chamfering — pass a non-empty edge query/list rather than relying on a default that matched nothing.",
+		nextStep: "Enumerate the solid’s edges, choose the target edges, then call chamfer(solid, distance, edges)."
+	},
+	INVALID_FILLET_RADIUS: {
+		fix: "Use a fillet radius that is > 0 and small enough to fit the adjacent faces (well under half the thinnest wall).",
+		nextStep: "Reduce the radius (try a fraction of the smallest local feature size) and re-verify."
+	},
+	INVALID_CHAMFER_DISTANCE: {
+		fix: "Use a chamfer distance that is > 0 and smaller than the adjacent edge lengths.",
+		nextStep: "Lower the distance below the shortest adjacent edge and re-verify."
+	},
+	INVALID_THICKNESS: {
+		fix: "Use a shell/wall thickness that is > 0 and less than half the smallest cross-section.",
+		nextStep: "Reduce the thickness and re-verify, or remove the offending face from the removed-faces set."
+	},
+	ZERO_LENGTH_EXTRUSION: {
+		fix: "Extrude by a non-zero distance — a length of 0 produces no solid.",
+		nextStep: "Set a positive extrusion height (units: mm) and re-verify."
+	},
+	ZERO_OFFSET: {
+		fix: "Offset by a non-zero amount — an offset of 0 is a no-op the kernel rejects.",
+		nextStep: "Use a small non-zero offset (positive grows, negative shrinks) and re-verify."
+	},
+	FILLET_NOT_3D: {
+		fix: "fillet needs a 3D solid. Build the solid (extrude/revolve/box) before rounding edges.",
+		nextStep: "Move the fillet after the solid is created, then fillet the solid’s edges."
+	},
+	CHAMFER_NOT_3D: {
+		fix: "chamfer needs a 3D solid. Build the solid first, then chamfer its edges.",
+		nextStep: "Reorder so chamfer runs on the finished solid, not a sketch/wire/face."
+	},
+	FUSE_NOT_3D: {
+		fix: "fuse needs two 3D solids. Ensure both operands are solids before unioning.",
+		nextStep: "Extrude/loft each profile into a solid first, then fuse and unwrap the Result."
+	},
+	CUT_NOT_3D: {
+		fix: "cut needs 3D solids for both the base and the tool. Build both as solids first.",
+		nextStep: "Make the tool a solid (e.g. a box/cylinder), then cut(base, tool) and unwrap the Result."
+	},
+	INTERSECT_NOT_3D: {
+		fix: "intersect needs two 3D solids. Build both operands as solids first.",
+		nextStep: "Ensure both inputs are solids, then intersect(a, b) and unwrap the Result."
+	},
+	SHELL_NOT_3D: {
+		fix: "shell needs a 3D solid. Create the solid before hollowing it.",
+		nextStep: "Build the solid first, then shell it with a thickness and the faces to remove."
+	},
+	OFFSET_NOT_3D: {
+		fix: "This offset needs a 3D solid. Build the solid before offsetting.",
+		nextStep: "Reorder so offset runs on the solid, then re-verify."
+	},
+	SWEEP_NOT_3D: {
+		fix: "sweep needs a 3D result context — check the profile and path produce a solid sweep.",
+		nextStep: "Verify the profile is a closed wire/face and the path is a valid wire, then re-sweep."
+	},
+	LOFT_NOT_3D: {
+		fix: "loft needs 3D-capable sections. Use closed profiles that can form a solid.",
+		nextStep: "Provide at least two closed section wires/faces, then loft and unwrap the Result."
+	},
+	REVOLUTION_NOT_3D: {
+		fix: "revolve needs a 2D profile revolved about an axis. Pass a face/closed wire.",
+		nextStep: "Use a closed profile and a valid axis, then revolve and unwrap the Result."
+	},
+	LOFT_FAILED: {
+		fix: "The loft could not be built — usually mismatched, self-intersecting, or out-of-order sections.",
+		nextStep: "Make the sections consistent (same orientation, non-self-intersecting, ordered along the loft) and retry."
+	},
+	LOFT_EMPTY: {
+		fix: "loft received too few sections. Provide at least two profiles.",
+		nextStep: "Add the missing section wires/faces and loft again."
+	},
+	SWEEP_FAILED: {
+		fix: "The sweep failed — usually a path with sharp corners/self-intersection or a profile too large for the path curvature.",
+		nextStep: "Smooth or simplify the path, shrink the profile, then re-sweep."
+	},
+	FUSE_FAILED: {
+		fix: "The boolean union failed — often touching-but-not-overlapping solids or tolerance issues.",
+		nextStep: "Make the operands overlap slightly (or heal/translate one), then re-fuse."
+	},
+	CUT_FAILED: {
+		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."
+	},
+	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."
+	},
+	STEP_EXPORT_CRASHED: {
+		fix: "STEP export crashed in the kernel — frequently a disjoint/degenerate fuse or an invalid solid reaching the exporter.",
+		nextStep: "Run validity checks first, heal/simplify the shape (or avoid fusing disjoint solids), then re-export."
+	},
+	STEP_EXPORT_FAILED: {
+		fix: "STEP export failed. The shape is likely invalid or non-manifold.",
+		nextStep: "Fix validity errors (heal/sew) until the solid is valid, then re-export."
+	},
+	STL_EXPORT_CRASHED: {
+		fix: "STL export crashed — usually an invalid or non-manifold mesh source.",
+		nextStep: "Verify the solid is valid and watertight, then re-export."
+	},
+	STL_EXPORT_FAILED: {
+		fix: "STL export failed. The shape is likely invalid or empty.",
+		nextStep: "Fix validity errors first, then re-export."
+	},
+	NULL_SHAPE_INPUT: {
+		fix: "An operation received a null/empty shape. Ensure the previous step actually produced a shape.",
+		nextStep: "Check the upstream Result was unwrapped (not an Err) before passing it on."
+	},
+	NULL_SHAPE: {
+		fix: "An operation produced or received a null shape. A prior step likely failed silently.",
+		nextStep: "Verify each intermediate shape is non-null before chaining the next operation."
+	},
+	VALIDATION_FAILED: {
+		fix: "The shape failed validity (BRepCheck). It is non-manifold, self-intersecting, or has bad geometry.",
+		nextStep: "Heal/sew the shape, or revisit the operation that produced it, until validSolid passes."
+	}
+};
+/** Synthetic code attached to validity-check failures (validSolid returns a plain string error). */
+var VALIDITY_FAILURE_CODE = "VALIDATION_FAILED";
+function hintFor(info) {
+	if (!info.code) return null;
+	const entry = HINT_TABLE[info.code];
+	const fix = entry?.fix ?? info.suggestion ?? "No specific fix available; inspect the error and the operation that produced it.";
+	const nextStep = entry?.nextStep ?? "Adjust the failing operation per the message/suggestion, then re-verify.";
+	return {
+		code: info.code,
+		message: info.message,
+		fix,
+		nextStep
+	};
+}
+function buildHints(r) {
+	const hints = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const info of r.errorInfos) {
+		const hint = hintFor(info);
+		if (!hint) continue;
+		const key = `${hint.code}${hint.message}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		hints.push(hint);
+	}
+	return hints;
+}
+function serializeReport(r) {
+	return JSON.stringify({
+		ok: reportOk(r),
+		...r
+	}, null, 2);
+}
+//#endregion
+//#region src/verify/checks.ts
+function shapeTypeOf(s) {
+	if (isSolid(s)) return "Solid";
+	if (isCompSolid(s)) return "CompSolid";
+	if (isCompound(s)) return "Compound";
+	if (isShell(s)) return "Shell";
+	if (isFace(s)) return "Face";
+	if (isWire(s)) return "Wire";
+	if (isEdge(s)) return "Edge";
+	if (isVertex(s)) return "Vertex";
+	return "Unknown";
+}
+function runChecks(shape) {
+	const r = emptyReport();
+	r.shapeType = shapeTypeOf(shape);
+	if (isSolid(shape)) {
+		const valid = validSolid(shape);
+		const validCheck = {
+			name: "isValidSolid",
+			passed: isOk(valid)
+		};
+		if (!isOk(valid)) {
+			validCheck.detail = valid.error;
+			r.errorInfos.push({
+				message: `isValidSolid: ${valid.error}`,
+				code: VALIDITY_FAILURE_CODE
+			});
+		}
+		r.checks.push(validCheck);
+	}
+	if (isShape3D(shape)) {
+		const vol = measureVolume(shape);
+		if (isOk(vol)) {
+			r.measurements.volume = vol.value;
+			r.checks.push({
+				name: "positiveVolume",
+				passed: vol.value > 0
+			});
+		} else pushError(r, {
+			message: `measureVolume: ${vol.error.message}`,
+			code: vol.error.code,
+			suggestion: vol.error.suggestion
+		});
+	}
+	if (isFace(shape) || isShape3D(shape)) {
+		const area = measureArea(shape);
+		if (isOk(area)) r.measurements.area = area.value;
+	}
+	try {
+		r.measurements.bounds = getBounds(shape);
+	} catch (e) {
+		pushError(r, { message: `getBounds: ${e.message}` });
+	}
+	r.hints = buildHints(r);
+	return r;
+}
+//#endregion
+//#region src/verify/runPart.ts
+function isResult(v) {
+	return typeof v === "object" && v !== null && "ok" in v && typeof v.ok === "boolean";
+}
+function isBrepError(v) {
+	if (typeof v !== "object" || v === null) return false;
+	const rec = v;
+	return typeof rec["code"] === "string" && typeof rec["message"] === "string";
+}
+/** Pull structured `{ message, code, suggestion }` out of a `BrepError`, a thrown `Error`, or anything. */
+function toErrorInfo(prefix, e) {
+	if (isBrepError(e)) return {
+		message: `${prefix}: ${e.message}`,
+		code: e.code,
+		suggestion: e.suggestion
+	};
+	if (e instanceof Error) return { message: `${prefix}: ${e.message}` };
+	return { message: `${prefix}: ${String(e)}` };
+}
+function finalize(result) {
+	result.report.hints = buildHints(result.report);
+	return result;
+}
+async function runPart(modulePath, opts = {}) {
+	await init();
+	const report = emptyReport();
+	let mod;
+	try {
+		mod = await import(modulePath);
+	} catch (e) {
+		pushError(report, toErrorInfo("import failed", e));
+		return finalize({
+			shape: null,
+			report
+		});
+	}
+	if (typeof mod.default !== "function") {
+		pushError(report, { message: "module has no default-exported part function" });
+		return finalize({
+			shape: null,
+			report
+		});
+	}
+	let out;
+	try {
+		out = await mod.default();
+	} catch (e) {
+		pushError(report, toErrorInfo("part threw", e));
+		return finalize({
+			shape: null,
+			report
+		});
+	}
+	let shape;
+	if (isResult(out)) if (isOk(out)) shape = out.value;
+	else {
+		pushError(report, toErrorInfo("part returned Err", out.error));
+		return finalize({
+			shape: null,
+			report
+		});
+	}
+	else shape = out;
+	if (!shape) {
+		pushError(report, { message: "part produced no shape" });
+		return finalize({
+			shape: null,
+			report
+		});
+	}
+	const result = runChecks(shape);
+	let glb;
+	let step;
+	if (opts.glb) try {
+		glb = exportGlb(mesh(shape));
+	} catch (e) {
+		pushError(result, toErrorInfo("exportGlb", e));
+	}
+	if (opts.step) {
+		const r = exportSTEP(shape);
+		if (isOk(r)) step = await r.value.arrayBuffer();
+		else pushError(result, toErrorInfo("exportSTEP", r.error));
+	}
+	return finalize({
+		shape,
+		report: result,
+		step,
+		glb
+	});
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.132.0/helpers/usingCtx.js
+function _usingCtx() {
+	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
+		var n = Error();
+		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
+	}, e = {}, n = [];
+	function using(r, e) {
+		if (null != e) {
+			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
+			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
+			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
+			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
+			t && (o = function o() {
+				try {
+					t.call(e);
+				} catch (r) {
+					return Promise.reject(r);
+				}
+			}), n.push({
+				v: e,
+				d: o,
+				a: r
+			});
+		} else r && n.push({
+			d: e,
+			a: r
+		});
+		return e;
+	}
+	return {
+		e,
+		u: using.bind(null, !1),
+		a: using.bind(null, !0),
+		d: function d() {
+			var o, t = this.e, s = 0;
+			function next() {
+				for (; o = n.pop();) try {
+					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
+					if (o.d) {
+						var r = o.d.call(o.v);
+						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
+					} else s |= 1;
+				} catch (r) {
+					return err(r);
+				}
+				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
+				if (t !== e) throw t;
+			}
+			function err(n) {
+				return t = t !== e ? new r(n, t) : n, next();
+			}
+			return next();
+		}
+	};
+}
+//#endregion
+//#region src/verify/measure.ts
+async function runMeasure(aPath, bPath) {
+	try {
+		var _usingCtx$2 = _usingCtx();
+		const errors = [];
+		const a = await runPart(aPath);
+		errors.push(...a.report.errors);
+		if (!a.shape) return { errors };
+		const sa = _usingCtx$2.u(a.shape);
+		if (bPath === void 0) {
+			const len = measureLength(sa);
+			if (isOk(len)) return {
+				length: len.value,
+				errors
+			};
+			errors.push(`measureLength: ${len.error.message}`);
+			return { errors };
+		}
+		const b = await runPart(bPath);
+		errors.push(...b.report.errors);
+		if (!b.shape) return { errors };
+		const dist = measureDistance(sa, _usingCtx$2.u(b.shape));
+		if (isOk(dist)) return {
+			distance: dist.value,
+			errors
+		};
+		errors.push(`measureDistance: ${dist.error.message}`);
+		return { errors };
+	} catch (_) {
+		_usingCtx$2.e = _;
+	} finally {
+		_usingCtx$2.d();
+	}
+}
+//#endregion
+//#region src/verify/diff.ts
+function emptyDiff(errors) {
+	return {
+		volumeDelta: 0,
+		areaDelta: 0,
+		bboxDelta: {
+			xMin: 0,
+			xMax: 0,
+			yMin: 0,
+			yMax: 0,
+			zMin: 0,
+			zMax: 0
+		},
+		symmetricDifferenceVolume: 0,
+		errors
+	};
+}
+function volumeOf(shape, errors) {
+	const v = measureVolume(shape);
+	if (isOk(v)) return v.value;
+	errors.push(`measureVolume: ${v.error.message}`);
+	return 0;
+}
+function areaOf(shape, errors) {
+	if (!isShape3D(shape)) return 0;
+	const a = measureArea(shape);
+	if (isOk(a)) return a.value;
+	errors.push(`measureArea: ${a.error.message}`);
+	return 0;
+}
+function cutVolume(x, y, errors) {
+	try {
+		var _usingCtx$1 = _usingCtx();
+		const r = cut(x, y);
+		if (!isOk(r)) {
+			errors.push(`cut: ${r.error.message}`);
+			return 0;
+		}
+		return volumeOf(_usingCtx$1.u(r.value), errors);
+	} catch (_) {
+		_usingCtx$1.e = _;
+	} finally {
+		_usingCtx$1.d();
+	}
+}
+async function runDiff(aPath, bPath) {
+	try {
+		var _usingCtx3 = _usingCtx();
+		const errors = [];
+		const a = await runPart(aPath);
+		errors.push(...a.report.errors);
+		const b = await runPart(bPath);
+		errors.push(...b.report.errors);
+		if (!a.shape || !b.shape) return emptyDiff(errors);
+		const sa = _usingCtx3.u(a.shape);
+		const sb = _usingCtx3.u(b.shape);
+		const ba = getBounds(sa);
+		const bb = getBounds(sb);
+		const bboxDelta = {
+			xMin: bb.xMin - ba.xMin,
+			xMax: bb.xMax - ba.xMax,
+			yMin: bb.yMin - ba.yMin,
+			yMax: bb.yMax - ba.yMax,
+			zMin: bb.zMin - ba.zMin,
+			zMax: bb.zMax - ba.zMax
+		};
+		const areaDelta = areaOf(sb, errors) - areaOf(sa, errors);
+		let volumeDelta = 0;
+		let symmetricDifferenceVolume = 0;
+		if (isShape3D(sa) && isShape3D(sb)) {
+			volumeDelta = volumeOf(sb, errors) - volumeOf(sa, errors);
+			symmetricDifferenceVolume = cutVolume(sa, sb, errors) + cutVolume(sb, sa, errors);
+		}
+		return {
+			volumeDelta,
+			areaDelta,
+			bboxDelta,
+			symmetricDifferenceVolume,
+			errors
+		};
+	} catch (_) {
+		_usingCtx3.e = _;
+	} finally {
+		_usingCtx3.d();
+	}
+}
+//#endregion
+export { emptyReport as a, runChecks as i, runMeasure as n, reportOk as o, runPart as r, serializeReport as s, runDiff as t };

package/dist/disposeShape.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Release a live WASM-backed kernel shape handle returned by `runPart`.
+ * No-op for null/undefined or shapes without a disposer, so callers can pass
+ * `result.shape` unconditionally. WASM memory accumulates without this.
+ */
+export declare function disposeShape(shape: unknown): void;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { runPart, type RunPartOptions, type RunPartResult } from './verify/runPart.js';
+export { runChecks } from './verify/checks.js';
+export { runMeasure, type MeasureReport } from './verify/measure.js';
+export { runDiff } from './verify/diff.js';
+export { serializeReport, emptyReport, type VerifyReport, type VerifyCheck, type VerifyMeasurements, type DiffReport, type BoundsDelta, } from './verify/report.js';

package/dist/snapshot/registry.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_snapshot_static = require("./static.cjs");
+//#region src/snapshot/registry.ts
+var DEFAULT_PORT = 7373;
+var PROBE_SPAN = 8;
+var DEFAULT_SHUTDOWN_AFTER_MS = 720 * 60 * 1e3;
+async function probe(port) {
+	const ctrl = new AbortController();
+	const timer = setTimeout(() => ctrl.abort(), 400);
+	try {
+		const res = await fetch(`http://127.0.0.1:${port}/__cad/server`, { signal: ctrl.signal });
+		if (!res.ok) return false;
+		const d = await res.json();
+		return d.app === "brepjs-cad-viewer" && d.dynamicRoot === true && typeof d.serverApiVersion === "number" && d.serverApiVersion >= 1;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function acquireServer(opts = {}) {
+	const ports = opts.port !== void 0 ? [opts.port] : Array.from({ length: PROBE_SPAN }, (_, i) => DEFAULT_PORT + i);
+	for (const port of ports) if (await probe(port)) return {
+		port,
+		url: `http://127.0.0.1:${port}`,
+		reused: true,
+		close: () => Promise.resolve()
+	};
+	let server;
+	for (const port of ports) try {
+		server = await require_snapshot_static.startStaticServer({ port });
+		break;
+	} catch {}
+	if (!server) throw new Error(`no free port in ${ports[0]}..${ports[ports.length - 1]}`);
+	const timer = setTimeout(() => void server?.close(), opts.shutdownAfterMs ?? 432e5);
+	timer.unref();
+	const started = server;
+	return {
+		port: started.port,
+		url: started.url,
+		reused: false,
+		close: async () => {
+			clearTimeout(timer);
+			await started.close();
+		}
+	};
+}
+//#endregion
+exports.DEFAULT_SHUTDOWN_AFTER_MS = DEFAULT_SHUTDOWN_AFTER_MS;
+exports.acquireServer = acquireServer;

package/dist/snapshot/registry.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_SHUTDOWN_AFTER_MS: number;
+export interface AcquireOptions {
+    port?: number;
+    shutdownAfterMs?: number;
+}
+export interface AcquiredServer {
+    port: number;
+    url: string;
+    reused: boolean;
+    close(): Promise<void>;
+}
+export declare function acquireServer(opts?: AcquireOptions): Promise<AcquiredServer>;

package/dist/snapshot/registry.js

@@ -0,0 +1,48 @@
+import { startStaticServer } from "./static.js";
+//#region src/snapshot/registry.ts
+var DEFAULT_PORT = 7373;
+var PROBE_SPAN = 8;
+var DEFAULT_SHUTDOWN_AFTER_MS = 720 * 60 * 1e3;
+async function probe(port) {
+	const ctrl = new AbortController();
+	const timer = setTimeout(() => ctrl.abort(), 400);
+	try {
+		const res = await fetch(`http://127.0.0.1:${port}/__cad/server`, { signal: ctrl.signal });
+		if (!res.ok) return false;
+		const d = await res.json();
+		return d.app === "brepjs-cad-viewer" && d.dynamicRoot === true && typeof d.serverApiVersion === "number" && d.serverApiVersion >= 1;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function acquireServer(opts = {}) {
+	const ports = opts.port !== void 0 ? [opts.port] : Array.from({ length: PROBE_SPAN }, (_, i) => DEFAULT_PORT + i);
+	for (const port of ports) if (await probe(port)) return {
+		port,
+		url: `http://127.0.0.1:${port}`,
+		reused: true,
+		close: () => Promise.resolve()
+	};
+	let server;
+	for (const port of ports) try {
+		server = await startStaticServer({ port });
+		break;
+	} catch {}
+	if (!server) throw new Error(`no free port in ${ports[0]}..${ports[ports.length - 1]}`);
+	const timer = setTimeout(() => void server?.close(), opts.shutdownAfterMs ?? 432e5);
+	timer.unref();
+	const started = server;
+	return {
+		port: started.port,
+		url: started.url,
+		reused: false,
+		close: async () => {
+			clearTimeout(timer);
+			await started.close();
+		}
+	};
+}
+//#endregion
+export { DEFAULT_SHUTDOWN_AFTER_MS, acquireServer };

package/dist/snapshot/serve.cjs

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_snapshot_registry = require("./registry.cjs");
+let node_path = require("node:path");
+//#region src/snapshot/serve.ts
+function viewerUrl(base, file) {
+	if (!file) return base;
+	const abs = (0, node_path.resolve)(file);
+	return `${base}/?dir=${encodeURIComponent((0, node_path.dirname)(abs))}&file=${encodeURIComponent((0, node_path.basename)(abs))}`;
+}
+/** Acquire (reuse or start) the persistent server and return its viewer URL. */
+async function serve(opts = {}) {
+	const server = await require_snapshot_registry.acquireServer(opts);
+	const url = viewerUrl(server.url, opts.file);
+	if (!server.reused) {
+		const onSig = () => void server.close().then(() => process.exit(0));
+		process.once("SIGINT", onSig);
+		process.once("SIGTERM", onSig);
+	}
+	return {
+		port: server.port,
+		url,
+		reused: server.reused,
+		close: () => server.close()
+	};
+}
+//#endregion
+exports.serve = serve;

package/dist/snapshot/serve.d.ts

@@ -0,0 +1,12 @@
+import { AcquireOptions } from './registry.js';
+export interface ServeOptions extends AcquireOptions {
+    file?: string;
+}
+export interface ServeHandle {
+    port: number;
+    url: string;
+    reused: boolean;
+    close(): Promise<void>;
+}
+/** Acquire (reuse or start) the persistent server and return its viewer URL. */
+export declare function serve(opts?: ServeOptions): Promise<ServeHandle>;