brepjs-bim 0.24.0 → 0.24.2

package/dist/elementFns/placedGeometry.d.ts

@@ -1,7 +1,7 @@
 import { ValidSolid, Result } from 'brepjs';
 import { AnyBimElement } from '../types/bimTypes.js';
 import { BimError } from '../errors/bimError.js';
-import { FrameInput } from '../import/placement.js';
+import { FrameInput } from '../placementFrame.js';
 export interface PlacedGeometryTestHooks {
     readonly afterPlaced?: ((solid: ValidSolid) => void) | undefined;
 }

package/dist/familiesAdapter.d.ts

@@ -9,9 +9,16 @@ export interface FamiliesToBimOptions {
     readonly siteName?: string | undefined;
     readonly buildingName?: string | undefined;
     /**
-     * Materializes exact evaluated Product Bodies for supported typed routes
-     * such as Earthworks Fill. Supplying this option does not opt unsupported
-     * products into the proxy fallback.
+     * Materializes exact evaluated Product Bodies for supported typed routes.
+     * Earthworks Fill always retains that Body. Civil-semantic walls and railings
+     * require this evaluator (or `proxyEvaluator`) before projection: absence
+     * returns FAMILIES_PRODUCT_BODY_EVALUATOR_REQUIRED with the element path and
+     * mapped category, and does not fall back to a parametric envelope.
+     * Conventional archetype walls and railings stay specification-authoritative
+     * and do not require an evaluator. When present, civil walls and railings
+     * compare the evaluated Body with their post-opening parametric Body and
+     * retain the authored Body when they differ. Supplying this option does not
+     * opt unsupported products into the proxy fallback.
      */
     readonly bodyEvaluator?: csg.Evaluator | undefined;
     /**
@@ -44,6 +51,11 @@ export interface FamiliesBimResult {
      */
     readonly proxied: readonly ProxiedElement[];
 }
+export interface FamiliesAdapterTestHooks {
+    readonly afterCivilProductBody?: ((model: BimModel, localId: LocalId, element: ResolvedElement) => void) | undefined;
+}
+/** Package-internal deterministic failure seam for projection ownership tests. */
+export declare function setFamiliesAdapterTestHooksForTesting(hooks: FamiliesAdapterTestHooks | null): void;
 /**
  * Project a resolved families tree into an eager BimModel. The caller owns
  * the returned model (`using`); families stays domain-neutral — this adapter

package/dist/familiesFrame.d.ts

@@ -0,0 +1,11 @@
+import { Result } from 'brepjs';
+import { TransformOp } from 'brepjs-families';
+import { BimError } from './errors/bimError.js';
+import { RigidFrame } from './placementFrame.js';
+export declare function frameFromOps(ops: readonly TransformOp[]): Result<RigidFrame, BimError>;
+/** Private projection control flow: the outer adapter converts this back to Result. */
+export declare class FrameProjectionError extends Error {
+    readonly error: BimError;
+    constructor(error: BimError);
+}
+export declare function requireFrame(result: Result<RigidFrame, BimError>): RigidFrame;

package/dist/familiesProductBody.d.ts

@@ -0,0 +1,40 @@
+import { Result, Solid, ValidSolid, csg } from 'brepjs';
+import { ResolvedElement } from 'brepjs-families';
+import { BimError } from './errors/bimError.js';
+import { ProductBody } from './types/productBody.js';
+import { RigidFrame } from './placementFrame.js';
+type ExactProductBody = Extract<ProductBody, {
+    readonly kind: 'EXACT';
+}>;
+type ParametricProductBody = Extract<ProductBody, {
+    readonly kind: 'PARAMETRIC';
+}>;
+export type CivilProductBodySelection = {
+    readonly kind: 'PARAMETRIC';
+} | {
+    readonly kind: 'EXACT';
+    readonly body: ExactProductBody;
+};
+export interface CivilProductBodyInput {
+    readonly element: ResolvedElement;
+    readonly category: 'WALL' | 'RAILING';
+    readonly evaluator: csg.Evaluator;
+    readonly productWorldFrame: RigidFrame;
+    /** Borrowed model-owned comparison candidate after registered openings. */
+    readonly parametricBody: ParametricProductBody;
+}
+export interface FamiliesProductBodyTestHooks {
+    readonly afterCopy?: ((itemIndex: number, solid: Solid, source: Solid) => void) | undefined;
+    readonly beforeLocalize?: ((itemIndex: number, solid: ValidSolid) => void) | undefined;
+    readonly afterLocalized?: ((itemIndex: number, solid: ValidSolid) => void) | undefined;
+    readonly beforeCoincidence?: ((exact: ExactProductBody, parametric: ParametricProductBody) => void) | undefined;
+}
+/** Package-internal deterministic failure seams for exact ownership tests. */
+export declare function setFamiliesProductBodyTestHooksForTesting(hooks: FamiliesProductBodyTestHooks | null): void;
+/**
+ * Evaluates a civil Product Body, clones and localizes every borrowed source,
+ * then proves whether the registered-opening parametric Body is coincident.
+ * An EXACT result is caller-owned until takeExactProductBody() succeeds.
+ */
+export declare function selectCivilProductBody(input: CivilProductBodyInput): Result<CivilProductBodySelection, BimError>;
+export {};

package/dist/ifc-writer/tessellationWriter.d.ts

@@ -1,6 +1,6 @@
 import { ValidSolid } from 'brepjs';
 import { IfcWriter } from './ifcWriter.js';
-import { FrameInput } from '../import/placement.js';
+import { FrameInput } from '../placementFrame.js';
 import { NonEmpty } from '../types/productBody.js';
 export interface TessellationResult {
     readonly productDefinitionShapeId: number;

package/dist/import/placement.d.ts

@@ -1,30 +1,5 @@
-import { MatrixTransform } from 'brepjs';
+import { Mat4x4, Vec3 } from '../placementFrame.js';
 import { SpfReader } from './spfReader.js';
-/**
- * Column-major 4x4 transform, matching the layout web-ifc and OCCT use:
- * column c, row r lives at index c*4 + r. Columns 0-2 are the basis vectors
- * (axisX, axisY, axisZ); column 3 is the translation; the bottom row is
- * [0,0,0,1].
- */
-export type Mat4x4 = readonly [
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number
-];
-export type Vec3 = readonly [number, number, number];
 /** A placement decomposed into origin + the two stored IFC axes (Z, X). */
 export interface WorldPlacement {
     /** Translation in millimetres (file units scaled to mm). */
@@ -78,26 +53,6 @@ export declare function composeWorldPlacement(reader: SpfReader, placementExpres
  * always a proper rotation.
  */
 export declare function readAxis2Placement3D(reader: SpfReader, placementExpressId: number, scale: number): Mat4x4 | null;
-/** An (origin, axisX, axisZ) frame in mm — the authoring/display side of a placement. */
-export interface FrameInput {
-    readonly origin: Vec3;
-    readonly axisX: Vec3;
-    readonly axisZ: Vec3;
-}
-/**
- * Builds a row-major MatrixTransform (for brepjs `applyMatrix`) from an
- * (origin, axisX, axisZ) frame, using the SAME IFC orthonormalization as
- * {@link readAxis2Placement3D}: z = normalize(axisZ); x = normalize(axisX
- * projected onto the plane ⊥ z); y = z × x. The basis vectors are the matrix
- * columns, so the row-major linear array is [Xx,Yx,Zx, Xy,Yy,Zy, Xz,Yz,Zz];
- * translation = origin (mm). This is the display-side counterpart to the IFC
- * writer's Axis2Placement3D (Axis=Z, RefDirection=X) so on-screen placement and
- * the IFC export agree.
- */
-export declare function placementToMatrix(f: FrameInput): MatrixTransform;
-/** Decomposes a column-major matrix into origin (mm) + IFC axes (Z, X). */
-export declare function decomposePlacement(m: Mat4x4): WorldPlacement;
-export declare function identityMatrix(): Mat4x4;
 /**
  * Reads the IfcMapConversion georeferencing offset (Eastings/Northings/
  * OrthogonalHeight, scaled to mm) and true-north rotation. Returns null when

package/dist/import/spfReader.d.ts

@@ -33,11 +33,11 @@ export declare class SpfReader {
     /** Uppercased IFC entity name of the instance (e.g. `IFCWALL`). */
     typeNameOf(expressId: number): string;
     getLineType(expressId: number): number;
-    /** Builds web-ifc's internal GUID→expressId index; call before guid lookups. */
+    /** Builds a JS-owned index without web-ifc's unreleased per-type native vectors. */
     buildGuidMap(): void;
-    /** expressId for a GlobalId, or undefined. Requires {@link buildGuidMap} first. */
+    /** expressId for a GlobalId, or undefined. Builds the index on first lookup. */
     expressIdFromGuid(guid: string): number | undefined;
-    /** GlobalId for an express id, or undefined. Requires {@link buildGuidMap} first. */
+    /** GlobalId for an express id, or undefined. Builds the index on first lookup. */
     guidFromExpressId(expressId: number): string | undefined;
     /**
      * Composed world transform (column-major 16-float matrix) for a placement

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { placedSolids } from './elementFns/placedGeometry.js';
 export { bodySolids } from './types/productBody.js';
 export type { NonEmpty, ProductBody } from './types/productBody.js';
 export type { PlacedSolidsOptions } from './elementFns/placedGeometry.js';
-export type { FrameInput } from './import/placement.js';
+export type { FrameInput } from './placementFrame.js';
 export { toIfc, toIfcValidated } from './serialize/toIfc.js';
 export type { ValidatedIfcResult } from './serialize/toIfc.js';
 export { setIfcWasmLocateFile } from './ifcRuntime.js';

package/dist/placementFrame.d.ts

@@ -1,36 +1,47 @@
-import { TransformOp } from 'brepjs-families';
-import { FrameInput, Mat4x4, Vec3, WorldPlacement } from './import/placement.js';
-export type Frame = Mat4x4;
-export declare const IDENTITY_FRAME: Frame;
-/** Column-major 4x4 multiply: `a . b` (apply b first, then a). */
-export declare function frameMul(a: Frame, b: Frame): Frame;
-export declare function translationFrame(v: Vec3): Frame;
-/**
- * Builds a frame from an authored `(origin, axisX, axisZ)` placement, using the
- * same IFC orthonormalization as `placementToMatrix`/`readAxis2Placement3D`:
- * z = normalize(axisZ); x = normalize(axisX projected perpendicular to z);
- * y = z x. Lets a civil node authored with explicit axis props enter the same
- * frame pipeline as a `tRotate` chain.
- */
-export declare function frameFromPlacement(f: FrameInput): Frame;
-/**
- * Rotation by `angleDeg` about `axis` (default +Z) through pivot `at` (default
- * origin), matching `csg.rotate` (Rodrigues; right-handed about the axis). With
- * a pivot the motion is `T(at) . R . T(-at)`, i.e. `p -> at + R(p - at)`.
- */
-export declare function rotationFrame(angleDeg: number, axis?: Vec3, at?: Vec3): Frame;
-/**
- * Composes an authored `TransformOp` chain into one frame, matching families'
- * `applyOps`: `ops[0]` is innermost (applied first). For `[A, B]` the composed
- * motion is `B . A`, so a point transforms as `B(A(p))`.
- */
-export declare function frameFromOps(ops: readonly TransformOp[]): Frame;
-/** Rigid inverse of `[R | t]`: `[R^T | -R^T t]`. */
-export declare function frameInverse(f: Frame): Frame;
-/** Decomposes a frame into origin (mm) + IFC axes (axisX, axisZ). */
-export declare function decomposeFrame(f: Frame): WorldPlacement;
-/** Translation column of a frame. */
-export declare function frameOrigin(f: Frame): Vec3;
-/** True when the rotation part is the identity (within tolerance): a pure
- *  translation, so the existing translation-only placement path suffices. */
-export declare function isPureTranslation(f: Frame, eps?: number): boolean;
+import { Result, MatrixTransform } from 'brepjs';
+import { BimError } from './errors/bimError.js';
+export type Vec3 = readonly [number, number, number];
+export type Mat4x4 = readonly [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+export interface FrameInput {
+    readonly origin: Vec3;
+    readonly axisX: Vec3;
+    readonly axisZ: Vec3;
+}
+/** Construction is private; every exposed matrix is an immutable snapshot. */
+declare class RigidFrame {
+    #private;
+    private constructor();
+    get matrix(): Mat4x4;
+    static fromMatrix(input: unknown): Result<RigidFrame, BimError>;
+}
+export type { RigidFrame };
+export declare function frameFromMatrix(input: unknown): Result<RigidFrame, BimError>;
+export declare function frameFromPlacement(input: unknown): Result<RigidFrame, BimError>;
+export declare function decomposeFrame(frame: RigidFrame): FrameInput;
+export declare function rotationFrame(angleDeg: number, axis?: unknown, at?: unknown): Result<RigidFrame, BimError>;
+export declare const IDENTITY_FRAME: RigidFrame;
+export declare function translationFrame(v: unknown): Result<RigidFrame, BimError>;
+/** Right operand acts first. Revalidate the result, including translation overflow. */
+export declare function frameMul(a: RigidFrame, b: RigidFrame): Result<RigidFrame, BimError>;
+export declare function frameInverse(frame: RigidFrame): Result<RigidFrame, BimError>;
+export declare function frameOrigin(frame: RigidFrame): Vec3;
+export declare function isPureTranslation(frame: RigidFrame): boolean;
+/** Row-major linear transform for native geometry consumers of a validated frame. */
+export declare function frameToMatrix(frame: RigidFrame): MatrixTransform;

package/dist/rigidPlacement.d.ts

@@ -1,4 +1,4 @@
 import { AnyShape, Dimension } from 'brepjs';
-import { FrameInput } from './import/placement.js';
+import { RigidFrame } from './placementFrame.js';
 /** Applies a rigid placement as a location so the source BRep is not rebuilt. */
-export declare function locateShapeInFrame<T extends AnyShape<Dimension>>(shape: T, frame: FrameInput): T;
+export declare function locateShapeInFrame<T extends AnyShape<Dimension>>(shape: T, frame: RigidFrame): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs-bim",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "BIM layer for brepjs — IFC4-aligned parametric building elements",
   "keywords": [
     "bim",
@@ -57,9 +57,9 @@
     "typescript-eslint": "*",
     "vite": "^8.0.0",
     "vite-plugin-dts": "^5.0.0",
-    "vitest": "^4.0.0",
+    "vitest": "^5.0.0",
     "web-ifc": "^0.0.77",
-    "zod": "^4.4.3"
+    "zod": "4.6.4"
   },
   "dependencies": {
     "brepjs-families": ">=0.1.0 <1.0.0"