brepjs 18.151.2 → 18.152.0

package/README.md

@@ -60,6 +60,8 @@ To set expectations, this project deliberately does not:
 npm install brepjs occt-wasm
 ```
 
+Starting fresh? `npm create brepjs my-project` scaffolds a TypeScript app with the kernel and the declarative family layer preconfigured.
+
 `brepjs/quick` handles WASM init automatically via top-level await (ESM only). Other options:
 
 ```typescript
@@ -84,6 +86,7 @@ The chapter-based guide is the recommended starting point:
 - **[Cheat Sheet](https://brepjs.dev/getting-started/cheat-sheet)**: single-page reference
 - **[Core Concepts](https://brepjs.dev/concepts/brep-vs-mesh)**: B-Rep, topology, types, kernels, tolerance
 - **[Common Tasks](https://brepjs.dev/tasks/booleans)**: booleans, fillets, sketching, lofts, sweeps, finders, measurement, IO
+- **[Declarative Models](https://brepjs.dev/families/overview)**: React-like parametric components (brepjs-families), key-path identity, IFC export
 - **[Three.js Integration](https://brepjs.dev/integration/threejs)**: meshing and rendering
 - **[Migration](https://brepjs.dev/migration/replicad)**: coming from Replicad, OpenSCAD, or Three.js
 - **[Extending brepjs](https://brepjs.dev/extending/architecture)**: custom kernels, custom operations, architecture
@@ -139,6 +142,27 @@ npx -y -p brepjs-cad brep bracket.brep.ts --check --step bracket.step --json rep
 
 The command exits non-zero unless the report is `ok` (valid **and** every declared dimension within tolerance), so it drops straight into CI or an agent loop. For MCP-capable agents the package also ships a stdio MCP server (`brep-mcp`) exposing the same build-and-verify step as a `run_program` tool. See the [**Authoring with AI**](https://brepjs.dev/agent/overview) guide for the full loop, CLI reference, the MCP server, examples, and the measurement eval.
 
+## Declarative models and BIM (brepjs-families + brepjs-bim)
+
+[`brepjs-families`](https://www.npmjs.com/package/brepjs-families) is a React-like component layer over the CSG IR: parametric parts are prop-driven, composable, zod-validated components, and identical subtrees materialize once because the IR is content-addressed. [`brepjs-bim`](https://www.npmjs.com/package/brepjs-bim) projects the same tree to IFC4 with stable GlobalIds derived from component key paths — walls, slabs, columns, beams, roofs, stairs, and real openings (`IfcOpeningElement` + `IfcRelFillsElement`).
+
+```typescript
+const Wall = family('Wall', (p: WallProps) =>
+  el('Box', { size: [p.length, p.thickness, p.height], voids: p.voids ?? [] })
+);
+const wall = Wall({ key: 'south', length: 4000, thickness: 200, height: 2700 });
+const tree = resolve(Storey({ key: 'ground', items: [wall] }));
+evaluateModel(tree, evaluator); // viewport meshes, one per key path
+familiesToBim(tree, { project }); // IFC via brepjs-bim
+```
+
+```bash
+npm create brepjs my-building   # scaffold a project
+npx brepjs add room storey slab # copy in starter families (code you own)
+```
+
+See the [**Declarative Models**](https://brepjs.dev/families/overview) guide.
+
 ## Projects Using brepjs
 
 - [Gridfinity Layout Tool](https://github.com/andymai/gridfinity-layout-tool): Web-based layout generator for Gridfinity storage systems

package/bin/brepjs.mjs

@@ -19,14 +19,46 @@
 import { mkdir, open, readFile, writeFile, access, lstat, realpath, rename, rm } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { join, resolve as resolvePath, sep } from 'node:path';
+import { dirname, join, resolve as resolvePath, sep } from 'node:path';
 import process from 'node:process';
 
-const DEFAULT_REGISTRY =
-  'https://raw.githubusercontent.com/andymai/brepjs/main/packages/brepjs-families/registry';
+// The default registry pins to the release tag of the INSTALLED
+// brepjs-families, so copied sources match the package the project compiles
+// against instead of tracking main (which can drift ahead). Without a local
+// install, fall back to main.
+const REGISTRY_PATH = 'packages/brepjs-families/registry';
+
+async function installedFamiliesVersion() {
+  // Walk ancestor node_modules like Node's resolver, so a hoisted install
+  // (workspaces, monorepos) still pins the registry.
+  let dir = process.cwd();
+  for (;;) {
+    try {
+      const pkg = JSON.parse(
+        await readFile(join(dir, 'node_modules', 'brepjs-families', 'package.json'), 'utf8')
+      );
+      if (typeof pkg.version === 'string' && /^\d+\.\d+\.\d+$/.test(pkg.version)) {
+        return pkg.version;
+      }
+    } catch {
+      // keep walking
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function defaultRegistry() {
+  const version = await installedFamiliesVersion();
+  if (version !== null) {
+    return `https://raw.githubusercontent.com/andymai/brepjs/brepjs-families-v${version}/${REGISTRY_PATH}`;
+  }
+  return `https://raw.githubusercontent.com/andymai/brepjs/main/${REGISTRY_PATH}`;
+}
 
 function parseArgs(argv) {
-  const args = { _: [], registry: DEFAULT_REGISTRY, dir: 'src/families', force: false, install: false };
+  const args = { _: [], registry: null, dir: 'src/families', force: false, install: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--registry') args.registry = argv[++i];
@@ -295,6 +327,7 @@ async function diff(args) {
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const args = parseArgs(rest);
+  args.registry = args.registry ?? (await defaultRegistry());
   if (cmd === 'add' && args._.length > 0) return add(args);
   if (cmd === 'diff' && args._.length === 1) return diff(args);
   console.error(

package/dist/brepjs.cjs

@@ -4528,7 +4528,15 @@ function foldBuildVec(dim, comps) {
 		nums[2]
 	]);
 }
+var optimized = /* @__PURE__ */ new WeakMap();
 function optimizeNode(n) {
+	const cached = optimized.get(n);
+	if (cached !== void 0) return cached;
+	const out = rewriteNode(n);
+	optimized.set(n, out);
+	return out;
+}
+function rewriteNode(n) {
 	switch (n.kind) {
 		case "Box": return box$2(foldExpr(n.x), foldExpr(n.y), foldExpr(n.z));
 		case "Sphere": return sphere$2(foldExpr(n.radius));
@@ -4646,13 +4654,16 @@ function optimizeTranslate(target, vector) {
 //#endregion
 //#region src/csg/edit.ts
 function replaceNode(root, pred, replacement) {
-	return walk(root, pred, replacement);
+	return walk(root, pred, replacement, /* @__PURE__ */ new Map());
 }
-function walk(node, pred, repl) {
-	if (pred(node)) return repl;
-	return rebuildChildren(node, pred, repl);
+function walk(node, pred, repl, memo) {
+	const cached = memo.get(node);
+	if (cached !== void 0) return cached;
+	const out = pred(node) ? repl : rebuildChildren(node, pred, repl, memo);
+	memo.set(node, out);
+	return out;
 }
-function rebuildChildren(n, pred, repl) {
+function rebuildChildren(n, pred, repl, memo) {
 	switch (n.kind) {
 		case "Box":
 		case "Sphere":
@@ -4666,23 +4677,23 @@ function rebuildChildren(n, pred, repl) {
 		case "Empty":
 		case "Path":
 		case "Profile": return n;
-		case "Fuse": return fuse$1(walk(n.a, pred, repl), walk(n.b, pred, repl), n.tolerance);
-		case "Cut": return cut$1(walk(n.a, pred, repl), walk(n.b, pred, repl), n.tolerance);
-		case "Intersect": return intersect$1(walk(n.a, pred, repl), walk(n.b, pred, repl), n.tolerance);
-		case "FuseAll": return fuseAll$1(n.shapes.map((c) => walk(c, pred, repl)), n.tolerance);
-		case "CutAll": return cutAll$1(walk(n.base, pred, repl), n.tools.map((c) => walk(c, pred, repl)), n.tolerance);
-		case "Translate": return translate$1(walk(n.target, pred, repl), n.vector);
-		case "Rotate": return rotate$1(walk(n.target, pred, repl), n.angle, {
+		case "Fuse": return fuse$1(walk(n.a, pred, repl, memo), walk(n.b, pred, repl, memo), n.tolerance);
+		case "Cut": return cut$1(walk(n.a, pred, repl, memo), walk(n.b, pred, repl, memo), n.tolerance);
+		case "Intersect": return intersect$1(walk(n.a, pred, repl, memo), walk(n.b, pred, repl, memo), n.tolerance);
+		case "FuseAll": return fuseAll$1(n.shapes.map((c) => walk(c, pred, repl, memo)), n.tolerance);
+		case "CutAll": return cutAll$1(walk(n.base, pred, repl, memo), n.tools.map((c) => walk(c, pred, repl, memo)), n.tolerance);
+		case "Translate": return translate$1(walk(n.target, pred, repl, memo), n.vector);
+		case "Rotate": return rotate$1(walk(n.target, pred, repl, memo), n.angle, {
 			axis: n.axis,
 			at: n.at
 		});
-		case "Scale": return scale$2(walk(n.target, pred, repl), n.factor, { center: n.center });
-		case "Mirror": return mirror$1(walk(n.target, pred, repl), {
+		case "Scale": return scale$2(walk(n.target, pred, repl, memo), n.factor, { center: n.center });
+		case "Mirror": return mirror$1(walk(n.target, pred, repl, memo), {
 			normal: n.normal,
 			at: n.at
 		});
-		case "Compound": return compound$1(n.children.map((c) => walk(c, pred, repl)));
-		case "Instance": return instance$1(walk(n.source, pred, repl), n.placements, n.fuse);
+		case "Compound": return compound$1(n.children.map((c) => walk(c, pred, repl, memo)));
+		case "Instance": return instance$1(walk(n.source, pred, repl, memo), n.placements, n.fuse);
 		case "Extrude":
 		case "Revolve":
 		case "Loft":
@@ -4690,27 +4701,35 @@ function rebuildChildren(n, pred, repl) {
 		case "Color":
 		case "Fillet":
 		case "Chamfer":
-		case "Shell": return rebuildFeature(n, pred, repl);
+		case "Shell": return rebuildFeature(n, pred, repl, memo);
 	}
 }
-function rebuildFeature(n, pred, repl) {
+function rebuildFeature(n, pred, repl, memo) {
 	switch (n.kind) {
-		case "Extrude": return extrude$1(walk(n.profile, pred, repl), n.vector);
-		case "Revolve": return revolve$1(walk(n.profile, pred, repl), n.angle, {
+		case "Extrude": return extrude$1(walk(n.profile, pred, repl, memo), n.vector);
+		case "Revolve": return revolve$1(walk(n.profile, pred, repl, memo), n.angle, {
 			axis: n.axis,
 			at: n.at
 		});
-		case "Loft": return loft$1(n.sections.map((s) => walk(s, pred, repl)), { ruled: n.ruled });
-		case "Sweep": return sweep$2(walk(n.profile, pred, repl), walk(n.spine, pred, repl), { frenet: n.frenet });
-		case "Color": return color(walk(n.target, pred, repl), [...n.color]);
-		case "Fillet": return fillet$1(walk(n.target, pred, repl), n.ref, n.radius);
-		case "Chamfer": return chamfer$1(walk(n.target, pred, repl), n.ref, n.distance);
-		case "Shell": return shell$1(walk(n.target, pred, repl), n.refs, n.thickness);
+		case "Loft": return loft$1(n.sections.map((s) => walk(s, pred, repl, memo)), { ruled: n.ruled });
+		case "Sweep": return sweep$2(walk(n.profile, pred, repl, memo), walk(n.spine, pred, repl, memo), { frenet: n.frenet });
+		case "Color": return color(walk(n.target, pred, repl, memo), [...n.color]);
+		case "Fillet": return fillet$1(walk(n.target, pred, repl, memo), n.ref, n.radius);
+		case "Chamfer": return chamfer$1(walk(n.target, pred, repl, memo), n.ref, n.distance);
+		case "Shell": return shell$1(walk(n.target, pred, repl, memo), n.refs, n.thickness);
 	}
 }
+/** Visits each DISTINCT node once (identity-deduplicated), so a shared
+*  subtree is reported once and a self-referencing DAG walks in linear time. */
 function forEachNode(root, fn) {
-	fn(root);
-	for (const child of childrenOf(root)) forEachNode(child, fn);
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (seen.has(node)) return;
+		seen.add(node);
+		fn(node);
+		for (const child of childrenOf(node)) visit(child);
+	};
+	visit(root);
 }
 function childrenOf(n) {
 	switch (n.kind) {

package/dist/brepjs.js

@@ -4538,7 +4538,15 @@ function foldBuildVec(dim, comps) {
 		nums[2]
 	]);
 }
+var optimized = /* @__PURE__ */ new WeakMap();
 function optimizeNode(n) {
+	const cached = optimized.get(n);
+	if (cached !== void 0) return cached;
+	const out = rewriteNode(n);
+	optimized.set(n, out);
+	return out;
+}
+function rewriteNode(n) {
 	switch (n.kind) {
 		case "Box": return box$2(foldExpr(n.x), foldExpr(n.y), foldExpr(n.z));
 		case "Sphere": return sphere$2(foldExpr(n.radius));
@@ -4656,13 +4664,16 @@ function optimizeTranslate(target, vector) {
 //#endregion
 //#region src/csg/edit.ts
 function replaceNode(root, pred, replacement) {
-	return walk(root, pred, replacement);
+	return walk(root, pred, replacement, /* @__PURE__ */ new Map());
 }
-function walk(node, pred, repl) {
-	if (pred(node)) return repl;
-	return rebuildChildren(node, pred, repl);
+function walk(node, pred, repl, memo) {
+	const cached = memo.get(node);
+	if (cached !== void 0) return cached;
+	const out = pred(node) ? repl : rebuildChildren(node, pred, repl, memo);
+	memo.set(node, out);
+	return out;
 }
-function rebuildChildren(n, pred, repl) {
+function rebuildChildren(n, pred, repl, memo) {
 	switch (n.kind) {
 		case "Box":
 		case "Sphere":
@@ -4676,23 +4687,23 @@ function rebuildChildren(n, pred, repl) {
 		case "Empty":
 		case "Path":
 		case "Profile": return n;
-		case "Fuse": return fuse$1(walk(n.a, pred, repl), walk(n.b, pred, repl), n.tolerance);
-		case "Cut": return cut$1(walk(n.a, pred, repl), walk(n.b, pred, repl), n.tolerance);
-		case "Intersect": return intersect$1(walk(n.a, pred, repl), walk(n.b, pred, repl), n.tolerance);
-		case "FuseAll": return fuseAll$1(n.shapes.map((c) => walk(c, pred, repl)), n.tolerance);
-		case "CutAll": return cutAll$1(walk(n.base, pred, repl), n.tools.map((c) => walk(c, pred, repl)), n.tolerance);
-		case "Translate": return translate$1(walk(n.target, pred, repl), n.vector);
-		case "Rotate": return rotate$1(walk(n.target, pred, repl), n.angle, {
+		case "Fuse": return fuse$1(walk(n.a, pred, repl, memo), walk(n.b, pred, repl, memo), n.tolerance);
+		case "Cut": return cut$1(walk(n.a, pred, repl, memo), walk(n.b, pred, repl, memo), n.tolerance);
+		case "Intersect": return intersect$1(walk(n.a, pred, repl, memo), walk(n.b, pred, repl, memo), n.tolerance);
+		case "FuseAll": return fuseAll$1(n.shapes.map((c) => walk(c, pred, repl, memo)), n.tolerance);
+		case "CutAll": return cutAll$1(walk(n.base, pred, repl, memo), n.tools.map((c) => walk(c, pred, repl, memo)), n.tolerance);
+		case "Translate": return translate$1(walk(n.target, pred, repl, memo), n.vector);
+		case "Rotate": return rotate$1(walk(n.target, pred, repl, memo), n.angle, {
 			axis: n.axis,
 			at: n.at
 		});
-		case "Scale": return scale$2(walk(n.target, pred, repl), n.factor, { center: n.center });
-		case "Mirror": return mirror$1(walk(n.target, pred, repl), {
+		case "Scale": return scale$2(walk(n.target, pred, repl, memo), n.factor, { center: n.center });
+		case "Mirror": return mirror$1(walk(n.target, pred, repl, memo), {
 			normal: n.normal,
 			at: n.at
 		});
-		case "Compound": return compound$1(n.children.map((c) => walk(c, pred, repl)));
-		case "Instance": return instance$1(walk(n.source, pred, repl), n.placements, n.fuse);
+		case "Compound": return compound$1(n.children.map((c) => walk(c, pred, repl, memo)));
+		case "Instance": return instance$1(walk(n.source, pred, repl, memo), n.placements, n.fuse);
 		case "Extrude":
 		case "Revolve":
 		case "Loft":
@@ -4700,27 +4711,35 @@ function rebuildChildren(n, pred, repl) {
 		case "Color":
 		case "Fillet":
 		case "Chamfer":
-		case "Shell": return rebuildFeature(n, pred, repl);
+		case "Shell": return rebuildFeature(n, pred, repl, memo);
 	}
 }
-function rebuildFeature(n, pred, repl) {
+function rebuildFeature(n, pred, repl, memo) {
 	switch (n.kind) {
-		case "Extrude": return extrude$1(walk(n.profile, pred, repl), n.vector);
-		case "Revolve": return revolve$1(walk(n.profile, pred, repl), n.angle, {
+		case "Extrude": return extrude$1(walk(n.profile, pred, repl, memo), n.vector);
+		case "Revolve": return revolve$1(walk(n.profile, pred, repl, memo), n.angle, {
 			axis: n.axis,
 			at: n.at
 		});
-		case "Loft": return loft$1(n.sections.map((s) => walk(s, pred, repl)), { ruled: n.ruled });
-		case "Sweep": return sweep$2(walk(n.profile, pred, repl), walk(n.spine, pred, repl), { frenet: n.frenet });
-		case "Color": return color(walk(n.target, pred, repl), [...n.color]);
-		case "Fillet": return fillet$1(walk(n.target, pred, repl), n.ref, n.radius);
-		case "Chamfer": return chamfer$1(walk(n.target, pred, repl), n.ref, n.distance);
-		case "Shell": return shell$1(walk(n.target, pred, repl), n.refs, n.thickness);
+		case "Loft": return loft$1(n.sections.map((s) => walk(s, pred, repl, memo)), { ruled: n.ruled });
+		case "Sweep": return sweep$2(walk(n.profile, pred, repl, memo), walk(n.spine, pred, repl, memo), { frenet: n.frenet });
+		case "Color": return color(walk(n.target, pred, repl, memo), [...n.color]);
+		case "Fillet": return fillet$1(walk(n.target, pred, repl, memo), n.ref, n.radius);
+		case "Chamfer": return chamfer$1(walk(n.target, pred, repl, memo), n.ref, n.distance);
+		case "Shell": return shell$1(walk(n.target, pred, repl, memo), n.refs, n.thickness);
 	}
 }
+/** Visits each DISTINCT node once (identity-deduplicated), so a shared
+*  subtree is reported once and a self-referencing DAG walks in linear time. */
 function forEachNode(root, fn) {
-	fn(root);
-	for (const child of childrenOf(root)) forEachNode(child, fn);
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (seen.has(node)) return;
+		seen.add(node);
+		fn(node);
+		for (const child of childrenOf(node)) visit(child);
+	};
+	visit(root);
 }
 function childrenOf(n) {
 	switch (n.kind) {

package/dist/csg/edit.d.ts

@@ -1,5 +1,7 @@
 import { IRNode } from './types.js';
 export type NodePredicate = (node: IRNode) => boolean;
 export declare function replaceNode(root: IRNode, pred: NodePredicate, replacement: IRNode): IRNode;
+/** Visits each DISTINCT node once (identity-deduplicated), so a shared
+ *  subtree is reported once and a self-referencing DAG walks in linear time. */
 export declare function forEachNode(root: IRNode, fn: (node: IRNode) => void): void;
 export declare function nodeCount(root: IRNode): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs",
-  "version": "18.151.2",
+  "version": "18.152.0",
   "description": "Web CAD library with pluggable geometry kernel",
   "keywords": [
     "cad",