brepjs-bim 0.4.0 → 0.6.0

package/dist/brepjs-bim.cjs

@@ -6350,6 +6350,14 @@ var BimModel = class {
 		if (key !== void 0 && this.#usedStableKeys.has(key)) return (0, brepjs.err)(specError("DUPLICATE_STABLE_KEY", `BimModel: duplicate stableKey '${key}'`));
 		return (0, brepjs.ok)(void 0);
 	}
+	#checkOpeningKeys(options) {
+		const filler = this.#checkStableKey(options);
+		if (!filler.ok) return filler;
+		const opening = this.#checkStableKey({ stableKey: options?.openingStableKey });
+		if (!opening.ok) return opening;
+		if (options?.stableKey !== void 0 && options.stableKey === options.openingStableKey) return (0, brepjs.err)(specError("DUPLICATE_STABLE_KEY", `BimModel: stableKey and openingStableKey are both '${options.stableKey}'`));
+		return (0, brepjs.ok)(void 0);
+	}
 	addWall(spec, options) {
 		const keyCheck = this.#checkStableKey(options);
 		if (!keyCheck.ok) return keyCheck;
@@ -6641,7 +6649,9 @@ var BimModel = class {
 		});
 		return (0, brepjs.ok)(id);
 	}
-	addDoor(spec) {
+	addDoor(spec, options) {
+		const keyCheck = this.#checkOpeningKeys(options);
+		if (!keyCheck.ok) return keyCheck;
 		const wall = this.#elements.get(spec.wallLocalId);
 		if (wall === void 0 || wall.category !== "WALL") return (0, brepjs.err)(specError("DOOR_WALL_NOT_FOUND", `No wall found for localId ${spec.wallLocalId}`));
 		if (spec.offsetAlongWall + spec.width > wall.spec.length) return (0, brepjs.err)(specError("DOOR_EXCEEDS_WALL_BOUNDS", "Door (offsetAlongWall + width) exceeds wall length"));
@@ -6656,13 +6666,13 @@ var BimModel = class {
 		const cutResult = this.#cutWallGeometry(wall, openingSpec);
 		if (!cutResult.ok) return (0, brepjs.err)(cutResult.error);
 		this.#replaceWallGeometry(wall, cutResult.value);
-		const openingId = this.#makeElement("OPENING", openingSpec, null);
+		const openingId = this.#makeElement("OPENING", openingSpec, null, options?.openingStableKey);
 		this.#makeRel({
 			kind: "VOIDS_WALL",
 			wallLocalId: spec.wallLocalId,
 			openingLocalId: openingId
 		});
-		const doorId = this.#makeElement("DOOR", spec, null);
+		const doorId = this.#makeElement("DOOR", spec, null, options?.stableKey);
 		this.#makeRel({
 			kind: "FILLS_OPENING",
 			openingLocalId: openingId,
@@ -6675,7 +6685,9 @@ var BimModel = class {
 		});
 		return (0, brepjs.ok)(doorId);
 	}
-	addWindow(spec) {
+	addWindow(spec, options) {
+		const keyCheck = this.#checkOpeningKeys(options);
+		if (!keyCheck.ok) return keyCheck;
 		const wall = this.#elements.get(spec.wallLocalId);
 		if (wall === void 0 || wall.category !== "WALL") return (0, brepjs.err)(specError("WINDOW_WALL_NOT_FOUND", `No wall found for localId ${spec.wallLocalId}`));
 		if (spec.offsetAlongWall + spec.width > wall.spec.length) return (0, brepjs.err)(specError("WINDOW_EXCEEDS_WALL_BOUNDS", "Window (offsetAlongWall + width) exceeds wall length"));
@@ -6690,13 +6702,13 @@ var BimModel = class {
 		const cutResult = this.#cutWallGeometry(wall, openingSpec);
 		if (!cutResult.ok) return (0, brepjs.err)(cutResult.error);
 		this.#replaceWallGeometry(wall, cutResult.value);
-		const openingId = this.#makeElement("OPENING", openingSpec, null);
+		const openingId = this.#makeElement("OPENING", openingSpec, null, options?.openingStableKey);
 		this.#makeRel({
 			kind: "VOIDS_WALL",
 			wallLocalId: spec.wallLocalId,
 			openingLocalId: openingId
 		});
-		const windowId = this.#makeElement("WINDOW", spec, null);
+		const windowId = this.#makeElement("WINDOW", spec, null, options?.stableKey);
 		this.#makeRel({
 			kind: "FILLS_OPENING",
 			openingLocalId: openingId,
@@ -6709,7 +6721,9 @@ var BimModel = class {
 		});
 		return (0, brepjs.ok)(windowId);
 	}
-	addSlabOpening(input) {
+	addSlabOpening(input, options) {
+		const keyCheck = this.#checkStableKey(options);
+		if (!keyCheck.ok) return keyCheck;
 		const slab = this.#elements.get(input.slabLocalId);
 		if (slab === void 0 || slab.category !== "SLAB") return (0, brepjs.err)(specError("SLAB_OPENING_SLAB_NOT_FOUND", `No slab found for localId ${input.slabLocalId}`));
 		if (input.offsetX + input.sizeX > slab.spec.length) return (0, brepjs.err)(specError("SLAB_OPENING_EXCEEDS_SLAB_BOUNDS", "Opening (offsetX + sizeX) exceeds slab length"));
@@ -6739,7 +6753,7 @@ var BimModel = class {
 		const cutResult = this.#cutSlabGeometry(slab, openingSpec);
 		if (!cutResult.ok) return (0, brepjs.err)(cutResult.error);
 		this.#replaceSlabGeometry(slab, cutResult.value);
-		const openingId = this.#makeElement("OPENING", openingSpec, null);
+		const openingId = this.#makeElement("OPENING", openingSpec, null, options?.stableKey);
 		this.#makeRel({
 			kind: "VOIDS_SLAB",
 			slabLocalId: input.slabLocalId,
@@ -16479,8 +16493,11 @@ function assignNum(target, key, value) {
 * while the IR path serves the viewport and dedup. GlobalIds derive from
 * families key paths (stable under reordering), not insertion order.
 *
-* v1 scope: Storey containers and Wall/Slab elements. Openings, fills, and
-* relationship wiring (IfcRelVoidsElement) follow with the opening writer.
+* Scope: Storey containers, Wall/Slab elements, and wall openings — a
+* fill-role void (Door/Window family) maps onto addDoor/addWindow, which cut
+* the wall and wire IfcRelVoidsElement + IfcRelFillsElement; the opening and
+* filler GlobalIds derive from the synthesized key paths. Anonymous (non-fill)
+* voids stay IR-only and never reach the spec path.
 */
 var SPEC_DEFAULTS = {
 	origin: [
@@ -16506,36 +16523,58 @@ var GEOMETRY_PROPS = /* @__PURE__ */ new Set([
 	"transform",
 	"psets"
 ]);
-/** Fold the resolved geometry's OUTER literal translate chain into the spec
-*  placement origin, so IfcLocalPlacement matches the IR world frame no
-*  matter where the transform came from (family-internal or prop-level).
-*  Parameter-driven translations cannot fold and keep the default origin. */
-function composedOrigin(el) {
-	const out = [...el.props["origin"] ?? [
+/** Total of the resolved geometry's OUTER literal translate chain. The
+*  transform vocabulary is translate-only, so frame differences are exact
+*  subtractions. Parameter-driven translations stop the peel. */
+function peelTranslates(node) {
+	const total = [
 		0,
 		0,
 		0
-	]];
+	];
 	let moved = false;
-	let node = el.geometry;
-	while (node.kind === "Translate") {
-		const v = node.vector;
+	let cur = node;
+	while (cur.kind === "Translate") {
+		const v = cur.vector;
 		if (v.kind !== "Vec3Lit") break;
-		out[0] += v.value[0];
-		out[1] += v.value[1];
-		out[2] += v.value[2];
+		total[0] += v.value[0];
+		total[1] += v.value[1];
+		total[2] += v.value[2];
 		moved = true;
-		node = node.target;
+		cur = cur.target;
 	}
-	return moved || el.props["origin"] !== void 0 ? out : void 0;
+	return {
+		total,
+		moved
+	};
+}
+/** Fold the resolved geometry's outer translate chain into the spec placement
+*  origin, so IfcLocalPlacement matches the IR world frame no matter where the
+*  transform came from (family-internal or prop-level). */
+function composedOrigin(el) {
+	const base = el.props["origin"] ?? [
+		0,
+		0,
+		0
+	];
+	const { total, moved } = peelTranslates(el.geometry);
+	if (!moved && el.props["origin"] === void 0) return void 0;
+	return [
+		base[0] + total[0],
+		base[1] + total[1],
+		base[2] + total[2]
+	];
+}
+function stripGeometryProps(props) {
+	const out = {};
+	for (const [k, v] of Object.entries(props)) if (!GEOMETRY_PROPS.has(k)) out[k] = v;
+	return out;
 }
 function specInput(el) {
-	const fromProps = {};
-	for (const [k, v] of Object.entries(el.props)) if (!GEOMETRY_PROPS.has(k)) fromProps[k] = v;
 	const origin = composedOrigin(el);
 	return {
 		...SPEC_DEFAULTS,
-		...fromProps,
+		...stripGeometryProps(el.props),
 		...origin ? { origin } : {},
 		...collectSpecProps(el)
 	};
@@ -16554,6 +16593,56 @@ function collectSpecProps(el) {
 	delete out["psets"];
 	return out;
 }
+function addFill(model, fill, input, identity) {
+	if (fill.type === "Door") {
+		const parsed = parseDoorSpec(input);
+		if (!parsed.ok) return parsed;
+		return model.addDoor(parsed.value, identity);
+	}
+	if (fill.type === "Window") {
+		const parsed = parseWindowSpec(input);
+		if (!parsed.ok) return parsed;
+		return model.addWindow(parsed.value, identity);
+	}
+	return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_FILL", `familiesToBim: no fill mapping for element type '${fill.type}' at '${fill.keyPath}'`));
+}
+/** Map a wall's synthesized Opening children onto addDoor/addWindow. The
+*  wall-relative offsets come from the void geometry's frame minus the host's:
+*  exact because both carry the same outer host transform. */
+function addOpenings(model, host, wallId, containerId, idByKeyPath) {
+	const hostT = peelTranslates(host.geometry).total;
+	for (const opening of host.children) {
+		if (opening.type !== "Opening") continue;
+		const fill = opening.children[0];
+		if (fill === void 0) return (0, brepjs.err)(specError("FAMILIES_OPENING_NO_FILL", `familiesToBim: opening '${opening.keyPath}' has no fill element`));
+		const keyed = requireKeyed(opening);
+		if (!keyed.ok) return keyed;
+		const fillT = peelTranslates(opening.geometry).total;
+		const added = addFill(model, fill, {
+			materialName: SPEC_DEFAULTS.materialName,
+			...stripGeometryProps(fill.props),
+			wallLocalId: wallId,
+			offsetAlongWall: fillT[0] - hostT[0],
+			offsetFromFloor: fillT[2] - hostT[2]
+		}, {
+			stableKey: fill.keyPath,
+			openingStableKey: opening.keyPath
+		});
+		if (!added.ok) return added;
+		model.placeIn(added.value, containerId);
+		idByKeyPath.set(fill.keyPath, added.value);
+		const fillsRel = model.getAllRelationships().find((r) => r.kind === "FILLS_OPENING" && r.fillerLocalId === added.value);
+		if (fillsRel !== void 0) idByKeyPath.set(opening.keyPath, fillsRel.openingLocalId);
+	}
+	return (0, brepjs.ok)(void 0);
+}
+/** Every element that mints an IFC identity needs an explicit key: an
+*  index-fallback path is order-dependent, which would silently break the
+*  reorder-stable GlobalId contract. */
+function requireKeyed(el) {
+	if (el.keyed) return (0, brepjs.ok)(void 0);
+	return (0, brepjs.err)(specError("FAMILIES_UNKEYED_ELEMENT", `familiesToBim: '${el.keyPath}' has no explicit key — IFC identity needs order-independent key paths (add a key to the element)`));
+}
 /**
 * Project a resolved families tree into an eager BimModel. The caller owns
 * the returned model (`using`); families stays domain-neutral — this adapter
@@ -16570,6 +16659,8 @@ function familiesToBim(root, options) {
 	const walk = (el, storeyId) => {
 		let containerId = storeyId;
 		if (el.type === "Storey") {
+			const keyed = requireKeyed(el);
+			if (!keyed.ok) return keyed;
 			const id = model.addStorey({
 				name: el.attributes["name"] ?? el.keyPath,
 				elevation: el.props["elevation"] ?? 0
@@ -16578,6 +16669,8 @@ function familiesToBim(root, options) {
 			idByKeyPath.set(el.keyPath, id);
 			containerId = id;
 		} else if (el.type === "Wall" || el.type === "Slab") {
+			const keyed = requireKeyed(el);
+			if (!keyed.ok) return keyed;
 			const parsed = el.type === "Wall" ? parseWallSpec(specInput(el)) : parseSlabSpec(specInput(el));
 			if (!parsed.ok) return parsed;
 			const added = el.type === "Wall" ? model.addWall(parsed.value, { stableKey: el.keyPath }) : model.addSlab(parsed.value, { stableKey: el.keyPath });
@@ -16585,8 +16678,14 @@ function familiesToBim(root, options) {
 			idByKeyPath.set(el.keyPath, added.value);
 			if (containerId === null) return (0, brepjs.err)(specError("FAMILIES_NO_STOREY", `familiesToBim: '${el.keyPath}' has no Storey ancestor — IFC elements need spatial containment`));
 			model.placeIn(added.value, containerId);
-		} else if (el.type !== "Opening" && el.type !== "Group" && el.geometry.kind !== "Empty") return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}'`));
+			if (el.type === "Wall") {
+				const opened = addOpenings(model, el, added.value, containerId, idByKeyPath);
+				if (!opened.ok) return opened;
+			}
+		} else if (el.type === "Opening") return (0, brepjs.err)(specError("FAMILIES_OPENING_OUTSIDE_WALL", `familiesToBim: opening '${el.keyPath}' is not hosted by a Wall — only wall openings are mapped`));
+		else if (el.type !== "Group" && el.geometry.kind !== "Empty") return (0, brepjs.err)(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}'`));
 		for (const child of el.children) {
+			if (el.type === "Wall" && child.type === "Opening") continue;
 			const r = walk(child, containerId);
 			if (!r.ok) return r;
 		}

package/dist/brepjs-bim.js

@@ -6327,6 +6327,14 @@ var BimModel = class {
 		if (key !== void 0 && this.#usedStableKeys.has(key)) return err(specError("DUPLICATE_STABLE_KEY", `BimModel: duplicate stableKey '${key}'`));
 		return ok(void 0);
 	}
+	#checkOpeningKeys(options) {
+		const filler = this.#checkStableKey(options);
+		if (!filler.ok) return filler;
+		const opening = this.#checkStableKey({ stableKey: options?.openingStableKey });
+		if (!opening.ok) return opening;
+		if (options?.stableKey !== void 0 && options.stableKey === options.openingStableKey) return err(specError("DUPLICATE_STABLE_KEY", `BimModel: stableKey and openingStableKey are both '${options.stableKey}'`));
+		return ok(void 0);
+	}
 	addWall(spec, options) {
 		const keyCheck = this.#checkStableKey(options);
 		if (!keyCheck.ok) return keyCheck;
@@ -6618,7 +6626,9 @@ var BimModel = class {
 		});
 		return ok(id);
 	}
-	addDoor(spec) {
+	addDoor(spec, options) {
+		const keyCheck = this.#checkOpeningKeys(options);
+		if (!keyCheck.ok) return keyCheck;
 		const wall = this.#elements.get(spec.wallLocalId);
 		if (wall === void 0 || wall.category !== "WALL") return err(specError("DOOR_WALL_NOT_FOUND", `No wall found for localId ${spec.wallLocalId}`));
 		if (spec.offsetAlongWall + spec.width > wall.spec.length) return err(specError("DOOR_EXCEEDS_WALL_BOUNDS", "Door (offsetAlongWall + width) exceeds wall length"));
@@ -6633,13 +6643,13 @@ var BimModel = class {
 		const cutResult = this.#cutWallGeometry(wall, openingSpec);
 		if (!cutResult.ok) return err(cutResult.error);
 		this.#replaceWallGeometry(wall, cutResult.value);
-		const openingId = this.#makeElement("OPENING", openingSpec, null);
+		const openingId = this.#makeElement("OPENING", openingSpec, null, options?.openingStableKey);
 		this.#makeRel({
 			kind: "VOIDS_WALL",
 			wallLocalId: spec.wallLocalId,
 			openingLocalId: openingId
 		});
-		const doorId = this.#makeElement("DOOR", spec, null);
+		const doorId = this.#makeElement("DOOR", spec, null, options?.stableKey);
 		this.#makeRel({
 			kind: "FILLS_OPENING",
 			openingLocalId: openingId,
@@ -6652,7 +6662,9 @@ var BimModel = class {
 		});
 		return ok(doorId);
 	}
-	addWindow(spec) {
+	addWindow(spec, options) {
+		const keyCheck = this.#checkOpeningKeys(options);
+		if (!keyCheck.ok) return keyCheck;
 		const wall = this.#elements.get(spec.wallLocalId);
 		if (wall === void 0 || wall.category !== "WALL") return err(specError("WINDOW_WALL_NOT_FOUND", `No wall found for localId ${spec.wallLocalId}`));
 		if (spec.offsetAlongWall + spec.width > wall.spec.length) return err(specError("WINDOW_EXCEEDS_WALL_BOUNDS", "Window (offsetAlongWall + width) exceeds wall length"));
@@ -6667,13 +6679,13 @@ var BimModel = class {
 		const cutResult = this.#cutWallGeometry(wall, openingSpec);
 		if (!cutResult.ok) return err(cutResult.error);
 		this.#replaceWallGeometry(wall, cutResult.value);
-		const openingId = this.#makeElement("OPENING", openingSpec, null);
+		const openingId = this.#makeElement("OPENING", openingSpec, null, options?.openingStableKey);
 		this.#makeRel({
 			kind: "VOIDS_WALL",
 			wallLocalId: spec.wallLocalId,
 			openingLocalId: openingId
 		});
-		const windowId = this.#makeElement("WINDOW", spec, null);
+		const windowId = this.#makeElement("WINDOW", spec, null, options?.stableKey);
 		this.#makeRel({
 			kind: "FILLS_OPENING",
 			openingLocalId: openingId,
@@ -6686,7 +6698,9 @@ var BimModel = class {
 		});
 		return ok(windowId);
 	}
-	addSlabOpening(input) {
+	addSlabOpening(input, options) {
+		const keyCheck = this.#checkStableKey(options);
+		if (!keyCheck.ok) return keyCheck;
 		const slab = this.#elements.get(input.slabLocalId);
 		if (slab === void 0 || slab.category !== "SLAB") return err(specError("SLAB_OPENING_SLAB_NOT_FOUND", `No slab found for localId ${input.slabLocalId}`));
 		if (input.offsetX + input.sizeX > slab.spec.length) return err(specError("SLAB_OPENING_EXCEEDS_SLAB_BOUNDS", "Opening (offsetX + sizeX) exceeds slab length"));
@@ -6716,7 +6730,7 @@ var BimModel = class {
 		const cutResult = this.#cutSlabGeometry(slab, openingSpec);
 		if (!cutResult.ok) return err(cutResult.error);
 		this.#replaceSlabGeometry(slab, cutResult.value);
-		const openingId = this.#makeElement("OPENING", openingSpec, null);
+		const openingId = this.#makeElement("OPENING", openingSpec, null, options?.stableKey);
 		this.#makeRel({
 			kind: "VOIDS_SLAB",
 			slabLocalId: input.slabLocalId,
@@ -16456,8 +16470,11 @@ function assignNum(target, key, value) {
 * while the IR path serves the viewport and dedup. GlobalIds derive from
 * families key paths (stable under reordering), not insertion order.
 *
-* v1 scope: Storey containers and Wall/Slab elements. Openings, fills, and
-* relationship wiring (IfcRelVoidsElement) follow with the opening writer.
+* Scope: Storey containers, Wall/Slab elements, and wall openings — a
+* fill-role void (Door/Window family) maps onto addDoor/addWindow, which cut
+* the wall and wire IfcRelVoidsElement + IfcRelFillsElement; the opening and
+* filler GlobalIds derive from the synthesized key paths. Anonymous (non-fill)
+* voids stay IR-only and never reach the spec path.
 */
 var SPEC_DEFAULTS = {
 	origin: [
@@ -16483,36 +16500,58 @@ var GEOMETRY_PROPS = /* @__PURE__ */ new Set([
 	"transform",
 	"psets"
 ]);
-/** Fold the resolved geometry's OUTER literal translate chain into the spec
-*  placement origin, so IfcLocalPlacement matches the IR world frame no
-*  matter where the transform came from (family-internal or prop-level).
-*  Parameter-driven translations cannot fold and keep the default origin. */
-function composedOrigin(el) {
-	const out = [...el.props["origin"] ?? [
+/** Total of the resolved geometry's OUTER literal translate chain. The
+*  transform vocabulary is translate-only, so frame differences are exact
+*  subtractions. Parameter-driven translations stop the peel. */
+function peelTranslates(node) {
+	const total = [
 		0,
 		0,
 		0
-	]];
+	];
 	let moved = false;
-	let node = el.geometry;
-	while (node.kind === "Translate") {
-		const v = node.vector;
+	let cur = node;
+	while (cur.kind === "Translate") {
+		const v = cur.vector;
 		if (v.kind !== "Vec3Lit") break;
-		out[0] += v.value[0];
-		out[1] += v.value[1];
-		out[2] += v.value[2];
+		total[0] += v.value[0];
+		total[1] += v.value[1];
+		total[2] += v.value[2];
 		moved = true;
-		node = node.target;
+		cur = cur.target;
 	}
-	return moved || el.props["origin"] !== void 0 ? out : void 0;
+	return {
+		total,
+		moved
+	};
+}
+/** Fold the resolved geometry's outer translate chain into the spec placement
+*  origin, so IfcLocalPlacement matches the IR world frame no matter where the
+*  transform came from (family-internal or prop-level). */
+function composedOrigin(el) {
+	const base = el.props["origin"] ?? [
+		0,
+		0,
+		0
+	];
+	const { total, moved } = peelTranslates(el.geometry);
+	if (!moved && el.props["origin"] === void 0) return void 0;
+	return [
+		base[0] + total[0],
+		base[1] + total[1],
+		base[2] + total[2]
+	];
+}
+function stripGeometryProps(props) {
+	const out = {};
+	for (const [k, v] of Object.entries(props)) if (!GEOMETRY_PROPS.has(k)) out[k] = v;
+	return out;
 }
 function specInput(el) {
-	const fromProps = {};
-	for (const [k, v] of Object.entries(el.props)) if (!GEOMETRY_PROPS.has(k)) fromProps[k] = v;
 	const origin = composedOrigin(el);
 	return {
 		...SPEC_DEFAULTS,
-		...fromProps,
+		...stripGeometryProps(el.props),
 		...origin ? { origin } : {},
 		...collectSpecProps(el)
 	};
@@ -16531,6 +16570,56 @@ function collectSpecProps(el) {
 	delete out["psets"];
 	return out;
 }
+function addFill(model, fill, input, identity) {
+	if (fill.type === "Door") {
+		const parsed = parseDoorSpec(input);
+		if (!parsed.ok) return parsed;
+		return model.addDoor(parsed.value, identity);
+	}
+	if (fill.type === "Window") {
+		const parsed = parseWindowSpec(input);
+		if (!parsed.ok) return parsed;
+		return model.addWindow(parsed.value, identity);
+	}
+	return err(specError("FAMILIES_UNSUPPORTED_FILL", `familiesToBim: no fill mapping for element type '${fill.type}' at '${fill.keyPath}'`));
+}
+/** Map a wall's synthesized Opening children onto addDoor/addWindow. The
+*  wall-relative offsets come from the void geometry's frame minus the host's:
+*  exact because both carry the same outer host transform. */
+function addOpenings(model, host, wallId, containerId, idByKeyPath) {
+	const hostT = peelTranslates(host.geometry).total;
+	for (const opening of host.children) {
+		if (opening.type !== "Opening") continue;
+		const fill = opening.children[0];
+		if (fill === void 0) return err(specError("FAMILIES_OPENING_NO_FILL", `familiesToBim: opening '${opening.keyPath}' has no fill element`));
+		const keyed = requireKeyed(opening);
+		if (!keyed.ok) return keyed;
+		const fillT = peelTranslates(opening.geometry).total;
+		const added = addFill(model, fill, {
+			materialName: SPEC_DEFAULTS.materialName,
+			...stripGeometryProps(fill.props),
+			wallLocalId: wallId,
+			offsetAlongWall: fillT[0] - hostT[0],
+			offsetFromFloor: fillT[2] - hostT[2]
+		}, {
+			stableKey: fill.keyPath,
+			openingStableKey: opening.keyPath
+		});
+		if (!added.ok) return added;
+		model.placeIn(added.value, containerId);
+		idByKeyPath.set(fill.keyPath, added.value);
+		const fillsRel = model.getAllRelationships().find((r) => r.kind === "FILLS_OPENING" && r.fillerLocalId === added.value);
+		if (fillsRel !== void 0) idByKeyPath.set(opening.keyPath, fillsRel.openingLocalId);
+	}
+	return ok(void 0);
+}
+/** Every element that mints an IFC identity needs an explicit key: an
+*  index-fallback path is order-dependent, which would silently break the
+*  reorder-stable GlobalId contract. */
+function requireKeyed(el) {
+	if (el.keyed) return ok(void 0);
+	return err(specError("FAMILIES_UNKEYED_ELEMENT", `familiesToBim: '${el.keyPath}' has no explicit key — IFC identity needs order-independent key paths (add a key to the element)`));
+}
 /**
 * Project a resolved families tree into an eager BimModel. The caller owns
 * the returned model (`using`); families stays domain-neutral — this adapter
@@ -16547,6 +16636,8 @@ function familiesToBim(root, options) {
 	const walk = (el, storeyId) => {
 		let containerId = storeyId;
 		if (el.type === "Storey") {
+			const keyed = requireKeyed(el);
+			if (!keyed.ok) return keyed;
 			const id = model.addStorey({
 				name: el.attributes["name"] ?? el.keyPath,
 				elevation: el.props["elevation"] ?? 0
@@ -16555,6 +16646,8 @@ function familiesToBim(root, options) {
 			idByKeyPath.set(el.keyPath, id);
 			containerId = id;
 		} else if (el.type === "Wall" || el.type === "Slab") {
+			const keyed = requireKeyed(el);
+			if (!keyed.ok) return keyed;
 			const parsed = el.type === "Wall" ? parseWallSpec(specInput(el)) : parseSlabSpec(specInput(el));
 			if (!parsed.ok) return parsed;
 			const added = el.type === "Wall" ? model.addWall(parsed.value, { stableKey: el.keyPath }) : model.addSlab(parsed.value, { stableKey: el.keyPath });
@@ -16562,8 +16655,14 @@ function familiesToBim(root, options) {
 			idByKeyPath.set(el.keyPath, added.value);
 			if (containerId === null) return err(specError("FAMILIES_NO_STOREY", `familiesToBim: '${el.keyPath}' has no Storey ancestor — IFC elements need spatial containment`));
 			model.placeIn(added.value, containerId);
-		} else if (el.type !== "Opening" && el.type !== "Group" && el.geometry.kind !== "Empty") return err(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}'`));
+			if (el.type === "Wall") {
+				const opened = addOpenings(model, el, added.value, containerId, idByKeyPath);
+				if (!opened.ok) return opened;
+			}
+		} else if (el.type === "Opening") return err(specError("FAMILIES_OPENING_OUTSIDE_WALL", `familiesToBim: opening '${el.keyPath}' is not hosted by a Wall — only wall openings are mapped`));
+		else if (el.type !== "Group" && el.geometry.kind !== "Empty") return err(specError("FAMILIES_UNSUPPORTED_TYPE", `familiesToBim: no spec mapping for element type '${el.type}' at '${el.keyPath}'`));
 		for (const child of el.children) {
+			if (el.type === "Wall" && child.type === "Opening") continue;
 			const r = walk(child, containerId);
 			if (!r.ok) return r;
 		}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { BimModel } from './model/bimModel.js';
+export { BimModel, type ElementIdentityOptions, type OpeningIdentityOptions, } from './model/bimModel.js';
 export type { BimTreeNode, BimTreeSummary } from './model/treeSummary.js';
 export { placedSolids } from './elementFns/placedGeometry.js';
 export { toIfc, toIfcValidated } from './serialize/toIfc.js';

package/dist/model/bimModel.d.ts

@@ -28,6 +28,11 @@ import { ProjectSpec, SiteSpec, BuildingSpec, StoreySpec } from '../specs/spatia
 export interface ElementIdentityOptions {
     readonly stableKey?: string | undefined;
 }
+/** Identity options for adders that create TWO elements: `stableKey` names
+ *  the filler (door/window), `openingStableKey` the synthesized opening. */
+export interface OpeningIdentityOptions extends ElementIdentityOptions {
+    readonly openingStableKey?: string | undefined;
+}
 export declare class BimModel {
     #private;
     init(spec: ProjectSpec): Result<LocalId, BimError>;
@@ -126,9 +131,9 @@ export declare class BimModel {
      * {@link ProxySpec.solid}).
      */
     addProxy(spec: ProxySpec): Result<LocalId, BimError>;
-    addDoor(spec: DoorSpec): Result<LocalId, BimError>;
-    addWindow(spec: WindowSpec): Result<LocalId, BimError>;
-    addSlabOpening(input: SlabOpeningInput): Result<LocalId, BimError>;
+    addDoor(spec: DoorSpec, options?: OpeningIdentityOptions): Result<LocalId, BimError>;
+    addWindow(spec: WindowSpec, options?: OpeningIdentityOptions): Result<LocalId, BimError>;
+    addSlabOpening(input: SlabOpeningInput, options?: ElementIdentityOptions): Result<LocalId, BimError>;
     getDoors(): BimElement<'DOOR'>[];
     getWindows(): BimElement<'WINDOW'>[];
     aggregate(parentId: LocalId, childId: LocalId): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs-bim",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "BIM layer for brepjs — IFC4-aligned parametric building elements",
   "keywords": [
     "bim",