fluidcad 0.0.31 → 0.0.32

package/lib/dist/core/extrude.d.ts

@@ -1,4 +1,5 @@
 import { IExtrude, ISceneObject } from "./interfaces.js";
+import { FaceFilterBuilder } from "../filters/face/face-filter.js";
 interface ExtrudeFunction {
     /**
      * Extrudes the last sketch with a default distance.
@@ -33,15 +34,27 @@ interface ExtrudeFunction {
     /**
      * Extrudes up to the first intersecting face.
      * @param face - The literal `'first-face'`
-     * @param target - The sketch or face-bearing scene object to extrude
+     * @param filters - Optional face filters to narrow the candidate set
+     */
+    (face: 'first-face', ...filters: FaceFilterBuilder[]): IExtrude;
+    /**
+     * Extrudes up to the first intersecting face.
+     * @param face - The literal `'first-face'`
+     * @param filtersAndTarget - Optional face filters followed by the target to extrude
      */
-    (face: 'first-face', target?: ISceneObject): IExtrude;
+    (face: 'first-face', ...filtersAndTarget: [...FaceFilterBuilder[], ISceneObject]): IExtrude;
     /**
      * Extrudes up to the last intersecting face.
      * @param face - The literal `'last-face'`
-     * @param target - The sketch or face-bearing scene object to extrude
+     * @param filters - Optional face filters to narrow the candidate set
+     */
+    (face: 'last-face', ...filters: FaceFilterBuilder[]): IExtrude;
+    /**
+     * Extrudes up to the last intersecting face.
+     * @param face - The literal `'last-face'`
+     * @param filtersAndTarget - Optional face filters followed by the target to extrude
      */
-    (face: 'last-face', target?: ISceneObject): IExtrude;
+    (face: 'last-face', ...filtersAndTarget: [...FaceFilterBuilder[], ISceneObject]): IExtrude;
 }
 declare const _default: ExtrudeFunction;
 export default _default;

package/lib/dist/core/extrude.js

@@ -4,6 +4,7 @@ import { Extrude } from "../features/extrude.js";
 import { ExtrudeTwoDistances } from "../features/extrude-two-distances.js";
 import { ExtrudeToFace } from "../features/extrude-to-face.js";
 import { SelectSceneObject } from "../features/select.js";
+import { FaceFilterBuilder } from "../filters/face/face-filter.js";
 function isExtrudable(obj) {
     return obj instanceof SceneObject && obj.isExtrudable();
 }
@@ -25,16 +26,17 @@ function build(context) {
         if (params.length === 0) {
             return new Extrude(defaultDistance, extrudable);
         }
+        if (params[0] === 'first-face' || params[0] === 'last-face') {
+            const rest = params.slice(1);
+            if (!rest.every(a => a instanceof FaceFilterBuilder)) {
+                throw new Error("Invalid parameter for extrude function.");
+            }
+            return new ExtrudeToFace(params[0], extrudable, rest);
+        }
         if (params.length === 1) {
             if (typeof params[0] === 'number') {
                 return new Extrude(params[0], extrudable);
             }
-            else if (params[0] === 'first-face') {
-                return new ExtrudeToFace('first-face', extrudable);
-            }
-            else if (params[0] === 'last-face') {
-                return new ExtrudeToFace('last-face', extrudable);
-            }
             else if (params[0] instanceof SceneObject) {
                 context.addSceneObject(params[0]);
                 return new ExtrudeToFace(params[0], extrudable);

package/lib/dist/core/interfaces.d.ts

@@ -11,11 +11,6 @@ export interface ISceneObject {
      * @param value - The display name to assign.
      */
     name(value: string): this;
-    /**
-     * Marks this object as construction geometry. Guide objects are excluded from
-     * final geometry output unless explicitly included.
-     */
-    guide(): this;
     /**
      * Marks this object as reusable. Reusable objects retain their shapes when
      * consumed by features (e.g., extrude, revolve), allowing multiple features
@@ -107,6 +102,12 @@ export interface IAxis extends ISceneObject {
 export interface ISelect extends ISceneObject {
 }
 export interface IGeometry extends ISceneObject {
+    /**
+     * Marks this sketch geometry as construction geometry. Guide geometries are
+     * excluded from the final sketch output (e.g., extrude, revolve) unless
+     * explicitly included.
+     */
+    guide(): this;
     /**
      * Returns a lazy-evaluated vertex at the start point of this geometry element.
      */
@@ -665,6 +666,15 @@ export interface IMirror extends IBooleanOperation {
      */
     exclude(...objects: ISceneObject[]): this;
 }
+export interface IMirror2D extends IGeometry {
+    /**
+     * Excludes the given sketch geometries from the mirror operation. Useful
+     * when mirroring "everything" but a few specific geometries should be
+     * skipped, or when narrowing an explicit target list.
+     * @param objects - The sketch geometries to exclude from mirroring.
+     */
+    exclude(...objects: ISceneObject[]): this;
+}
 export interface ITranslate extends ISceneObject {
     /**
      * Excludes the given objects from the translate operation. Useful when

package/lib/dist/core/mirror.d.ts

@@ -1,29 +1,29 @@
 import { PlaneLike } from "../math/plane.js";
 import { AxisLike } from "../math/axis.js";
-import { IMirror, ISceneObject } from "./interfaces.js";
+import { IMirror, IMirror2D, ISceneObject } from "./interfaces.js";
 interface MirrorFunction {
     /**
     * [2D] Mirror all sketch geometries across a given line.
     * @param line The line to mirror across
     */
-    (line: ISceneObject): IMirror;
+    (line: ISceneObject): IMirror2D;
     /**
     * [2D] Mirror all sketch geometries across a given axis.
     * @param axis The local axis to mirror across
     */
-    (axis: AxisLike): IMirror;
+    (axis: AxisLike): IMirror2D;
     /**
     * [2D] Mirror given sketch geometries across a given line.
     * @param line The line to mirror across
     * @param geometries The geometries to mirror
     */
-    (line: ISceneObject, ...geometries: ISceneObject[]): IMirror;
+    (line: ISceneObject, ...geometries: ISceneObject[]): IMirror2D;
     /**
     * [2D] Mirror given sketch geometries across a given axis.
     * @param axis The local axis to mirror across
     * @param geometries The geometries to mirror
     */
-    (axis: AxisLike, ...geometries: ISceneObject[]): IMirror;
+    (axis: AxisLike, ...geometries: ISceneObject[]): IMirror2D;
     /**
     * [3D] Mirror all scene shapes across a given plane.
     * @param plane The plane to mirror across

package/lib/dist/features/2d/line.d.ts

@@ -1,3 +1,4 @@
+import { SceneObject } from "../../common/scene-object.js";
 import { LazyVertex } from "../lazy-vertex.js";
 import { PlaneObjectBase } from "../plane-renderable-base.js";
 import { GeometrySceneObject } from "./geometry.js";
@@ -6,6 +7,7 @@ export declare class LineTo extends GeometrySceneObject {
     private targetPlane;
     constructor(endPoint: LazyVertex, targetPlane?: PlaneObjectBase);
     build(): void;
+    createCopy(remap: Map<SceneObject, SceneObject>): SceneObject;
     compareTo(other: LineTo): boolean;
     getType(): string;
     getUniqueType(): string;

package/lib/dist/features/2d/line.js

@@ -30,6 +30,10 @@ export class LineTo extends GeometrySceneObject {
             this.targetPlane.removeShapes(this);
         }
     }
+    createCopy(remap) {
+        const targetPlane = this.targetPlane ? (remap.get(this.targetPlane) || this.targetPlane) : null;
+        return new LineTo(this.endPoint, targetPlane);
+    }
     compareTo(other) {
         if (!(other instanceof LineTo)) {
             return false;

package/lib/dist/features/extrude-to-face.d.ts

@@ -2,9 +2,11 @@ import { BuildSceneObjectContext, SceneObject } from "../common/scene-object.js"
 import { ExtrudeBase } from "./extrude-base.js";
 import { Extrudable } from "../helpers/types.js";
 import { Point } from "../math/point.js";
+import { FaceFilterBuilder } from "../filters/face/face-filter.js";
 export declare class ExtrudeToFace extends ExtrudeBase {
     face: SceneObject | 'first-face' | 'last-face';
-    constructor(face: SceneObject | 'first-face' | 'last-face', source?: Extrudable | SceneObject);
+    private faceFilters;
+    constructor(face: SceneObject | 'first-face' | 'last-face', source?: Extrudable | SceneObject, faceFilters?: FaceFilterBuilder[]);
     build(context: BuildSceneObjectContext): void;
     private createAdvancedExtrude;
     private resizePlanarFace;
@@ -20,6 +22,7 @@ export declare class ExtrudeToFace extends ExtrudeBase {
     private createSimpleExtrude;
     private getFace;
     private getFirstOrLastFace;
+    private collectFromSceneObjects;
     getDependencies(): SceneObject[];
     createCopy(remap: Map<SceneObject, SceneObject>): SceneObject;
     compareTo(other: ExtrudeToFace): boolean;
@@ -39,6 +42,7 @@ export declare class ExtrudeToFace extends ExtrudeBase {
         draft: [number, number];
         endOffset: number;
         face: string;
+        faceFilterCount: number;
         thin: [number, number] | [number];
     };
 }

package/lib/dist/features/extrude-to-face.js

@@ -11,11 +11,15 @@ import { Explorer } from "../oc/explorer.js";
 import { FaceMaker2 } from "../oc/face-maker2.js";
 import { ThinFaceMaker } from "../oc/thin-face-maker.js";
 import { Point } from "../math/point.js";
+import { ShapeFilter } from "../filters/filter.js";
+import { FromSceneObjectFilter } from "../filters/from-object.js";
 export class ExtrudeToFace extends ExtrudeBase {
     face;
-    constructor(face, source) {
+    faceFilters;
+    constructor(face, source, faceFilters = []) {
         super(source);
         this.face = face;
+        this.faceFilters = faceFilters;
     }
     build(context) {
         const allSceneObjects = context.getSceneObjects();
@@ -252,12 +256,31 @@ export class ExtrudeToFace extends ExtrudeBase {
                 }
             }
         }
-        const result = FaceQuery.findFaceByDistance(allFaces, plane, mode);
+        let candidates = allFaces;
+        if (this.faceFilters.length > 0) {
+            candidates = new ShapeFilter(allFaces, ...this.faceFilters).apply();
+        }
+        const result = FaceQuery.findFaceByDistance(candidates, plane, mode);
         if (!result) {
             throw new Error(`No face found for '${mode}-face' extrusion`);
         }
         return result;
     }
+    collectFromSceneObjects() {
+        const objects = [];
+        for (const builder of this.faceFilters) {
+            for (const filter of builder.getFilters()) {
+                if (filter instanceof FromSceneObjectFilter) {
+                    for (const obj of filter.getSceneObjects()) {
+                        if (!objects.includes(obj)) {
+                            objects.push(obj);
+                        }
+                    }
+                }
+            }
+        }
+        return objects;
+    }
     getDependencies() {
         const deps = [];
         const source = this.getSource();
@@ -267,6 +290,11 @@ export class ExtrudeToFace extends ExtrudeBase {
         if (this.face instanceof SceneObject) {
             deps.push(this.face);
         }
+        for (const obj of this.collectFromSceneObjects()) {
+            if (!deps.includes(obj)) {
+                deps.push(obj);
+            }
+        }
         return deps;
     }
     createCopy(remap) {
@@ -275,7 +303,8 @@ export class ExtrudeToFace extends ExtrudeBase {
             : this.face;
         const source = this.getSource();
         const remapped = source ? (remap.get(source) || source) : undefined;
-        return new ExtrudeToFace(newFace, remapped).syncWith(this);
+        const remappedFilters = this.faceFilters.map(f => f.remap(remap));
+        return new ExtrudeToFace(newFace, remapped, remappedFilters).syncWith(this);
     }
     compareTo(other) {
         if (!(other instanceof ExtrudeToFace)) {
@@ -292,15 +321,27 @@ export class ExtrudeToFace extends ExtrudeBase {
         if (thisSource && otherSource && !thisSource.compareTo(otherSource)) {
             return false;
         }
-        if (typeof (this.face) !== typeof (other.face)) {
-            return false;
+        if (this.face instanceof SceneObject) {
+            if (!(other.face instanceof SceneObject)) {
+                return false;
+            }
+            if (!this.face.compareTo(other.face)) {
+                return false;
+            }
         }
-        if (this.face instanceof SceneObject && other.face instanceof SceneObject && !this.face.compareTo(other.face)) {
-            return false;
+        else {
+            if (this.face !== other.face) {
+                return false;
+            }
         }
-        if (this.face !== other.face) {
+        if (this.faceFilters.length !== other.faceFilters.length) {
             return false;
         }
+        for (let i = 0; i < this.faceFilters.length; i++) {
+            if (!this.faceFilters[i].equals(other.faceFilters[i])) {
+                return false;
+            }
+        }
         return true;
     }
     getUniqueType() {
@@ -316,6 +357,7 @@ export class ExtrudeToFace extends ExtrudeBase {
             draft: this.getDraft(),
             endOffset: this.getEndOffset(),
             face: typeof (this.face) === 'string' ? this.face : 'selection',
+            faceFilterCount: this.faceFilters.length,
             thin: this._thin,
             ...this.serializePickFields(),
         };

package/lib/dist/features/extrude.js

@@ -5,8 +5,11 @@ import { FaceMaker2 } from "../oc/face-maker2.js";
 import { BooleanOps } from "../oc/boolean-ops.js";
 import { EdgeOps } from "../oc/edge-ops.js";
 import { Explorer } from "../oc/explorer.js";
-import { ExtrudeThroughAll } from "./infinite-extrude.js";
 import { ThinFaceMaker } from "../oc/thin-face-maker.js";
+/** Finite stand-in for "infinity" in through-all cuts. Truly infinite prisms
+ *  (via OC's `Inf=true` flag) silently fail inside `BRepAlgoAPI_Cut` — verified
+ *  experimentally — so use a large finite extrusion instead. */
+const THROUGH_ALL_LENGTH = 100000;
 export class Extrude extends ExtrudeBase {
     distance;
     constructor(distance, source) {
@@ -257,36 +260,24 @@ export class Extrude extends ExtrudeBase {
         const scope = this.resolveFusionScope(context.getSceneObjects());
         let toolShapes;
         const isThroughAll = this.distance === 0;
-        if (this._symmetric) {
-            // Symmetric cut: create tool centered on sketch plane
-            if (isThroughAll) {
-                if (this.isFaceSourced()) {
-                    throw new Error("through-all is not supported with a face-sourced extrude");
-                }
-                const extrudeThroughAll = new ExtrudeThroughAll(this.extrudable, true, true, faces);
-                toolShapes = extrudeThroughAll.build();
-            }
-            else {
-                const extruder1 = new Extruder(faces, plane, -this.distance / 2, this.getDraft(), this.getEndOffset());
-                const extrusions1 = extruder1.extrude();
-                const extruder2 = new Extruder(faces, plane, this.distance / 2, this.getDraft(), this.getEndOffset());
-                const extrusions2 = extruder2.extrude();
-                const all = [...extrusions1, ...extrusions2];
-                const halvesFuse = BooleanOps.fuse(all);
-                toolShapes = halvesFuse.result;
-                halvesFuse.dispose();
-            }
+        const draft = this.getDraft();
+        if (isThroughAll && this.isFaceSourced()) {
+            throw new Error("through-all is not supported with a face-sourced extrude");
         }
-        else if (isThroughAll) {
-            if (this.isFaceSourced()) {
-                throw new Error("through-all is not supported with a face-sourced extrude");
-            }
-            const extrudeThroughAll = new ExtrudeThroughAll(this.extrudable, false, true, faces);
-            toolShapes = extrudeThroughAll.build();
+        if (this._symmetric) {
+            // Symmetric cut: create tool centered on sketch plane, fusing two halves
+            // (one on each side). For through-all, each half uses THROUGH_ALL_LENGTH.
+            const halfDistance = isThroughAll ? THROUGH_ALL_LENGTH : this.distance / 2;
+            const extruder1 = new Extruder(faces, plane, -halfDistance, draft, this.getEndOffset());
+            const extruder2 = new Extruder(faces, plane, halfDistance, draft, this.getEndOffset());
+            const all = [...extruder1.extrude(), ...extruder2.extrude()];
+            const halvesFuse = BooleanOps.fuse(all);
+            toolShapes = halvesFuse.result;
+            halvesFuse.dispose();
         }
         else {
-            const distance = -this.distance;
-            const extruder = new Extruder(faces, plane, distance, this.getDraft(), this.getEndOffset());
+            const distance = isThroughAll ? -THROUGH_ALL_LENGTH : -this.distance;
+            const extruder = new Extruder(faces, plane, distance, draft, this.getEndOffset());
             toolShapes = extruder.extrude();
         }
         this.getSource()?.removeShapes(this);

package/lib/dist/features/rotate.js

@@ -90,7 +90,7 @@ export class Rotate extends SceneObject {
             return false;
         }
         for (let i = 0; i < thisTargetObjects.length; i++) {
-            if (thisTargetObjects[i] !== otherTargetObjects[i]) {
+            if (!thisTargetObjects[i].compareTo(otherTargetObjects[i])) {
                 return false;
             }
         }
@@ -98,7 +98,7 @@ export class Rotate extends SceneObject {
             return false;
         }
         for (let i = 0; i < this._excludedObjects.length; i++) {
-            if (this._excludedObjects[i] !== other._excludedObjects[i]) {
+            if (!this._excludedObjects[i].compareTo(other._excludedObjects[i])) {
                 return false;
             }
         }

package/lib/dist/features/select.d.ts

@@ -11,6 +11,7 @@ export declare class SelectSceneObject extends SceneObject implements ISelect {
     private shapes;
     constructor(filters: FilterBuilderBase<Shape>[], constraintObject?: SceneObject);
     build(context: BuildSceneObjectContext): void;
+    private collectFromSceneObjects;
     private getAllShapes;
     getDependencies(): SceneObject[];
     createCopy(remap: Map<SceneObject, SceneObject>): SceneObject;

package/lib/dist/features/select.js

@@ -2,6 +2,7 @@ import { FaceFilterBuilder } from "../filters/face/face-filter.js";
 import { ShapeFilter } from "../filters/filter.js";
 import { SceneObject } from "../common/scene-object.js";
 import { BelongsToFaceFilter, NotBelongsToFaceFilter } from "../filters/edge/belongs-to-face.js";
+import { FromSceneObjectFilter } from "../filters/from-object.js";
 export class SelectSceneObject extends SceneObject {
     filters;
     constraintObject;
@@ -32,30 +33,57 @@ export class SelectSceneObject extends SceneObject {
                 sceneObjects = context.getSceneObjectsFromTo(parent, this);
             }
         }
+        // Objects passed explicitly via `from(...)` bypass the part scope so that
+        // cross-part selection works (e.g. select(face().from(p1)) from inside p2).
+        if (!this.constraintObject) {
+            const fromObjects = this.collectFromSceneObjects(filters);
+            if (fromObjects.length > 0) {
+                sceneObjects = sceneObjects.slice();
+                for (const obj of fromObjects) {
+                    if (!sceneObjects.includes(obj)) {
+                        sceneObjects.push(obj);
+                    }
+                }
+            }
+        }
         const allShapes = this.constraintObject ? this.constraintObject.getShapes() : this.getAllShapes(sceneObjects, excludedObjects);
         if (this.type === "edge") {
             this.injectScopeFaces(filters, sceneObjects);
         }
         const filteredShapes = this.applyFilters(allShapes, filters);
-        console.log(`SelectSceneObject: shapes after filtering: ${filteredShapes[0]}`);
         this.addShapes(filteredShapes);
     }
+    collectFromSceneObjects(filters) {
+        const objects = [];
+        for (const builder of filters) {
+            for (const filter of builder.getFilters()) {
+                if (filter instanceof FromSceneObjectFilter) {
+                    for (const obj of filter.getSceneObjects()) {
+                        if (!objects.includes(obj)) {
+                            objects.push(obj);
+                        }
+                    }
+                }
+            }
+        }
+        return objects;
+    }
     getAllShapes(scope, exludedShapes) {
         const scopeShapes = scope.flatMap(obj => obj.getShapes({}, 'solid').map(s => s.getSubShapes(this.type)).flat());
         exludedShapes = exludedShapes.flatMap(s => s.getSubShapes(this.type));
-        const finalShapes = scopeShapes.filter(shape => !exludedShapes.some(exShape => exShape.isSame(shape)));
-        console.log('=== Scope Objects:', scope.length, ' Shapes:', scopeShapes.length);
-        console.log('=== Excluded Shapes:', exludedShapes.length);
-        console.log('=== Final Shapes after exclusion:', finalShapes.length);
-        let allShapes = [];
-        for (const shape of finalShapes) {
-            allShapes.push(shape);
-        }
-        console.log('SelectSceneObject: total shapes collected for filtering:', allShapes.length);
-        return allShapes;
+        return scopeShapes.filter(shape => !exludedShapes.some(exShape => exShape.isSame(shape)));
     }
     getDependencies() {
-        return this.constraintObject ? [this.constraintObject] : [];
+        const deps = [];
+        if (this.constraintObject) {
+            deps.push(this.constraintObject);
+        }
+        for (const obj of this.collectFromSceneObjects(this.filters)) {
+            if (!deps.includes(obj)) {
+                deps.push(obj);
+            }
+        }
+        return deps;
     }
     createCopy(remap) {
         const remappedConstraint = this.constraintObject

package/lib/dist/features/simple-extruder.js

@@ -73,13 +73,16 @@ export class Extruder {
                     remainingFaces.push(f);
                 }
             }
-            // Use the firstFace from the solid to detect inner wires
-            // Inner wires (CCW) indicate holes — side faces sharing edges with them are internal
+            // Use the firstFace from the solid to detect inner wires. Test against
+            // the face's actual outward normal — for negative-distance extrudes the
+            // firstFace's outward normal flips relative to plane.normal, which would
+            // otherwise invert outer/inner detection and swap side/internal faces.
             const resolvedFirst = firstFace;
+            const outwardNormal = resolvedFirst.calculateNormal();
             const innerWireEdgeShapes = [];
             const wires = resolvedFirst.getWires();
             for (const wire of wires) {
-                if (!wire.isCW(this.plane.normal)) {
+                if (wire.isCW(outwardNormal)) {
                     for (const edge of wire.getEdges()) {
                         innerWireEdgeShapes.push(edge);
                     }

package/lib/dist/filters/face/above-below.d.ts

@@ -0,0 +1,20 @@
+import { Matrix4 } from "../../math/matrix4.js";
+import { Face } from "../../common/shapes.js";
+import { FilterBase } from "../filter-base.js";
+import { PlaneObjectBase } from "../../features/plane-renderable-base.js";
+export declare class AboveFacePlaneFilter extends FilterBase<Face> {
+    private plane;
+    private partial;
+    constructor(plane: PlaneObjectBase, partial?: boolean);
+    match(shape: Face): boolean;
+    compareTo(other: AboveFacePlaneFilter): boolean;
+    transform(matrix: Matrix4): AboveFacePlaneFilter;
+}
+export declare class BelowFacePlaneFilter extends FilterBase<Face> {
+    private plane;
+    private partial;
+    constructor(plane: PlaneObjectBase, partial?: boolean);
+    match(shape: Face): boolean;
+    compareTo(other: BelowFacePlaneFilter): boolean;
+    transform(matrix: Matrix4): BelowFacePlaneFilter;
+}

package/lib/dist/filters/face/above-below.js

@@ -0,0 +1,57 @@
+import { FilterBase } from "../filter-base.js";
+import { EdgeOps } from "../../oc/edge-ops.js";
+import { PlaneObject } from "../../features/plane.js";
+function getBoundaryPoints(face) {
+    return face.getEdges().flatMap(edge => [
+        EdgeOps.getVertexPoint(EdgeOps.getFirstVertex(edge)),
+        EdgeOps.getVertexPoint(EdgeOps.getLastVertex(edge)),
+    ]);
+}
+export class AboveFacePlaneFilter extends FilterBase {
+    plane;
+    partial;
+    constructor(plane, partial = false) {
+        super();
+        this.plane = plane;
+        this.partial = partial;
+    }
+    match(shape) {
+        const plane = this.plane.getPlane();
+        const flags = getBoundaryPoints(shape).map(p => plane.signedDistanceToPoint(p) > 0);
+        if (flags.length === 0) {
+            return false;
+        }
+        return this.partial ? flags.some(Boolean) : flags.every(Boolean);
+    }
+    compareTo(other) {
+        return this.plane.compareTo(other.plane) && this.partial === other.partial;
+    }
+    transform(matrix) {
+        const transformedPlane = this.plane.getPlane().applyMatrix(matrix);
+        return new AboveFacePlaneFilter(new PlaneObject(transformedPlane), this.partial);
+    }
+}
+export class BelowFacePlaneFilter extends FilterBase {
+    plane;
+    partial;
+    constructor(plane, partial = false) {
+        super();
+        this.plane = plane;
+        this.partial = partial;
+    }
+    match(shape) {
+        const plane = this.plane.getPlane();
+        const flags = getBoundaryPoints(shape).map(p => plane.signedDistanceToPoint(p) < 0);
+        if (flags.length === 0) {
+            return false;
+        }
+        return this.partial ? flags.some(Boolean) : flags.every(Boolean);
+    }
+    compareTo(other) {
+        return this.plane.compareTo(other.plane) && this.partial === other.partial;
+    }
+    transform(matrix) {
+        const transformedPlane = this.plane.getPlane().applyMatrix(matrix);
+        return new BelowFacePlaneFilter(new PlaneObject(transformedPlane), this.partial);
+    }
+}

package/lib/dist/filters/face/face-filter.d.ts

@@ -70,6 +70,14 @@ export declare class FaceFilterBuilder extends FilterBuilderBase<Face> {
      * @param minorRadius - Optional radius of the tube itself.
      */
     notTorus(majorRadius?: number, minorRadius?: number): this;
+    /**
+     * Selects planar (flat) faces.
+     */
+    planar(): this;
+    /**
+     * Excludes planar (flat) faces.
+     */
+    notPlanar(): this;
     /**
      * Selects conical faces.
      */
@@ -119,6 +127,24 @@ export declare class FaceFilterBuilder extends FilterBuilderBase<Face> {
      * @param count - The number of edges to exclude.
      */
     notEdgeCount(count: number): this;
+    /**
+     * Selects faces that are entirely above the given plane (in the direction of its normal).
+     * @param plane - The reference plane.
+     * @param offsetOrOptions - Offset distance, or an options object with `offset` and `partial`.
+     */
+    above(plane: PlaneLike | PlaneObjectBase, offsetOrOptions?: number | {
+        offset?: number;
+        partial?: boolean;
+    }): this;
+    /**
+     * Selects faces that are entirely below the given plane (opposite to its normal direction).
+     * @param plane - The reference plane.
+     * @param offsetOrOptions - Offset distance, or an options object with `offset` and `partial`.
+     */
+    below(plane: PlaneLike | PlaneObjectBase, offsetOrOptions?: number | {
+        offset?: number;
+        partial?: boolean;
+    }): this;
     /**
      * Restricts the selection to faces originating from the given scene objects.
      * Recursive: passing a container picks up faces from its descendants.