fluidcad 0.0.32 → 0.0.33

package/lib/dist/features/rib.js

@@ -0,0 +1,321 @@
+import { Face } from "../common/face.js";
+import { ExtrudeBase } from "./extrude-base.js";
+import { ExtrudeOps } from "../oc/extrude-ops.js";
+import { Explorer } from "../oc/explorer.js";
+import { FaceQuery } from "../oc/face-query.js";
+import { RibOps } from "../oc/rib-ops.js";
+import { WireOps } from "../oc/wire-ops.js";
+import { requireShapes } from "../common/operand-check.js";
+export class Rib extends ExtrudeBase {
+    _thickness;
+    _spine;
+    _parallel = false;
+    _extend = false;
+    constructor(thickness, spine, extrudable) {
+        super(extrudable);
+        this._thickness = thickness;
+        this._spine = spine;
+    }
+    get thickness() {
+        return this._thickness;
+    }
+    get spine() {
+        return this._spine;
+    }
+    parallel() {
+        this._parallel = true;
+        return this;
+    }
+    extend() {
+        this._extend = true;
+        return this;
+    }
+    validate() {
+        requireShapes(this._spine, "spine", "rib");
+    }
+    build(context) {
+        const p = context.getProfiler();
+        const plane = this.extrudable.getPlane();
+        const originalSpineWire = p.record('Get spine wire', () => this.getSpineWire(this._spine));
+        let spineWire = originalSpineWire;
+        const scopeObjects = this.resolveFusionScope(context.getSceneObjects());
+        const scopeShapes = scopeObjects.flatMap(o => o.getShapes({}, 'solid'));
+        if (scopeShapes.length === 0) {
+            throw new Error("Rib requires target solids in the scene or via .scope()");
+        }
+        if (this._extend) {
+            spineWire = p.record('Extend spine', () => RibOps.extendSpineWire(spineWire, scopeShapes, plane));
+        }
+        // Sign convention:
+        //   thickness > 0 → extrude OPPOSITE to the sketch normal (typical
+        //                    "into the cavity" direction when the sketch sits
+        //                    on top of a parent face).
+        //   thickness < 0 → extrude IN the sketch normal direction.
+        // Same applies for parallel mode (the perpendicular-in-plane direction
+        // gets the same sign flip).
+        const dirSign = -Math.sign(this._thickness);
+        let direction;
+        let distance;
+        if (this._parallel) {
+            const perpDir = RibOps.computeSpinePerpendicularDirection(spineWire, plane);
+            direction = perpDir.multiply(dirSign);
+            distance = p.record('Compute extrude distance', () => RibOps.computeExtrudeDistanceAlongDirection(direction, plane.origin, scopeShapes));
+        }
+        else {
+            direction = plane.normal.multiply(dirSign);
+            distance = p.record('Compute extrude distance', () => RibOps.computeExtrudeDistance(plane, scopeShapes));
+        }
+        // Parallel + draft uses a tapered loft (firstFace lies on the spine
+        // plane by construction, exact thickness preserved). Everything else
+        // builds a plain prism from the rib profile face.
+        const useTaperedLoft = this._parallel && this.getDraft() !== null;
+        const profileFace = useTaperedLoft
+            ? null
+            : p.record('Make rib profile', () => this._parallel
+                ? RibOps.makeRibProfileParallel(spineWire, this._thickness, plane)
+                : RibOps.makeRibProfile(spineWire, this._thickness, plane));
+        const vec = direction.multiply(distance);
+        const { solid, firstFace, lastFace } = p.record('Extrude rib', () => {
+            if (useTaperedLoft) {
+                const draft = this.getDraft();
+                const angleRad = (draft[0] * Math.PI) / 180;
+                return RibOps.makeTaperedRibPrism(spineWire, this._thickness, plane, direction, distance, angleRad);
+            }
+            return ExtrudeOps.makePrismFromVec(profileFace, vec);
+        });
+        const ribSolid = solid;
+        const ribFirstFace = firstFace;
+        const ribLastFace = lastFace;
+        this.extrudable.removeShapes(this);
+        if (this._spine !== this.extrudable) {
+            this._spine.removeShapes(this);
+        }
+        const conformed = p.record('Conform rib', () => RibOps.conformRibToScope(ribSolid, scopeShapes, originalSpineWire, ribFirstFace, ribLastFace, direction));
+        let classified = {
+            startFaces: conformed.startFaces,
+            endFaces: conformed.endFaces,
+            sideFaces: conformed.sideFaces,
+            internalFaces: conformed.internalFaces,
+            capFaces: [],
+        };
+        let conformedSolids = conformed.solids;
+        // Draft is applied AFTER conformance so the prism walls are already
+        // bounded by the cavity. Drafting the over-extended pre-conform
+        // prism caused OCC to fail (walls would cross within the over-
+        // extension); the conformed rib is finite, so OCC handles strong
+        // drafts cleanly.
+        //
+        // Parallel mode skips this entirely — its prism was built tapered
+        // by `RibOps.makeTaperedRibPrism`, so the conformed result is
+        // already drafted with an exact (no-drift) start-face thickness.
+        // Normal mode uses OCC's draft with the sketch plane as the neutral
+        // plane (which already coincides with the prism base, so no shift
+        // is required).
+        if (!this._parallel && this.getDraft() && conformedSolids.length === 1 && classified.startFaces.length > 0) {
+            const draft = this.getDraft();
+            let angle = draft[0];
+            const draftPlane = plane;
+            // Mirrors the dirSign reversal above: in normal mode the OCC
+            // pull direction is the unsigned plane.normal, which now matches
+            // the extrude direction only when thickness < 0 (since extrude
+            // direction = plane.normal * -sign(thickness)). Negate the angle
+            // to flip OCC's outward bias to the user-facing "+ draft narrows
+            // the tip" convention.
+            if (this._thickness < 0) {
+                angle = -angle;
+            }
+            const rad = (deg) => deg * Math.PI / 180;
+            const draftResult = p.record('Apply draft', () => {
+                // Use the first start face as the OCC "firstFace" param (pivot
+                // anchor). When the conformance trimmed the original end face
+                // into the cavity (so endFaces is empty), the tip is already
+                // captured as an internal face — we pass startFaces[0] as the
+                // "lastFace" placeholder so its IsSame check is a no-op (it'll
+                // also match firstFace and so be excluded once). The actual tip
+                // surface stays excluded via the internalFaces argument.
+                const startRep = classified.startFaces[0];
+                const endRep = classified.endFaces[0] ?? startRep;
+                // Faces of the rib that sit flush with a scope face (the rib's
+                // mounting face — typically a cap that meets the cavity wall)
+                // must not be tilted. Drafting them either tears the rib away
+                // from the parent (negative draft) or makes OCC fail outright
+                // (positive draft) because there's no material outside the wall
+                // for the tilt to extend into.
+                const wallTouchingFaces = findScopeCoincidentFaces(classified.sideFaces, scopeShapes);
+                // The rib's "cap" faces (perpendicular to the spine direction)
+                // close the slab at the spine endpoints. Drafting them tilts
+                // them inward and shrinks the rib's length along the spine,
+                // which the user doesn't expect — only the long wall faces
+                // (perpendicular to spine direction) should taper.
+                const spineStart = originalSpineWire.getFirstVertex().toPoint();
+                const spineEnd = originalSpineWire.getLastVertex().toPoint();
+                const spineDir = spineStart.vectorTo(spineEnd).normalize();
+                const capFaces = findFacesAlignedWith(classified.sideFaces, spineDir);
+                const excludes = [
+                    ...classified.startFaces.slice(1),
+                    ...classified.endFaces.slice(classified.endFaces[0] === endRep ? 1 : 0),
+                    ...classified.internalFaces,
+                    ...wallTouchingFaces,
+                    ...capFaces,
+                ];
+                return ExtrudeOps.applyDraftOnSideFaces(conformedSolids[0], startRep, endRep, draftPlane, rad(angle), excludes);
+            });
+            const remap = (faces) => {
+                const out = [];
+                for (const f of faces) {
+                    for (const r of draftResult.remapFace(f)) {
+                        out.push(r);
+                    }
+                }
+                return out;
+            };
+            classified = {
+                startFaces: remap(classified.startFaces),
+                endFaces: remap(classified.endFaces),
+                sideFaces: remap(classified.sideFaces),
+                internalFaces: remap(classified.internalFaces),
+                capFaces: [],
+            };
+            conformedSolids = [draftResult.solid];
+        }
+        if (this._operationMode === 'new') {
+            this.setState('start-faces', classified.startFaces);
+            this.setState('end-faces', classified.endFaces);
+            this.setState('side-faces', classified.sideFaces);
+            this.setState('internal-faces', classified.internalFaces);
+            this.setState('cap-faces', classified.capFaces);
+            this.addShapes(conformedSolids);
+            this.recordShapeFacesAndEdgesAsAdditions(conformedSolids);
+            this.classifyExtrudeEdges();
+            return;
+        }
+        this.finalizeAndFuse(conformedSolids, classified, context);
+    }
+    getSpineWire(pathObj) {
+        const shapes = pathObj.getShapes({ excludeMeta: false });
+        const edges = shapes.flatMap(s => s.getSubShapes('edge'));
+        return WireOps.makeWireFromEdges(edges);
+    }
+    getDependencies() {
+        const deps = [];
+        if (this.extrudable) {
+            deps.push(this.extrudable);
+        }
+        if (this._spine) {
+            deps.push(this._spine);
+        }
+        return deps;
+    }
+    createCopy(remap) {
+        const extrudable = this.extrudable
+            ? (remap.get(this.extrudable) || this.extrudable)
+            : undefined;
+        const spine = remap.get(this._spine) || this._spine;
+        const copy = new Rib(this._thickness, spine, extrudable).syncWith(this);
+        copy._parallel = this._parallel;
+        copy._extend = this._extend;
+        return copy;
+    }
+    compareTo(other) {
+        if (!(other instanceof Rib)) {
+            return false;
+        }
+        if (!super.compareTo(other)) {
+            return false;
+        }
+        if (this._thickness !== other._thickness) {
+            return false;
+        }
+        if (!this._spine.compareTo(other._spine)) {
+            return false;
+        }
+        if (this.extrudable && other.extrudable && !this.extrudable.compareTo(other.extrudable)) {
+            return false;
+        }
+        if (this._parallel !== other._parallel) {
+            return false;
+        }
+        if (this._extend !== other._extend) {
+            return false;
+        }
+        return true;
+    }
+    getType() {
+        return "rib";
+    }
+    serialize() {
+        return {
+            thickness: this._thickness,
+            spine: this._spine.serialize(),
+            extrudable: this.extrudable?.serialize(),
+            operationMode: this._operationMode !== 'add' ? this._operationMode : undefined,
+            parallel: this._parallel || undefined,
+            extend: this._extend || undefined,
+            draft: this._draft,
+        };
+    }
+}
+// Faces of the rib whose surface sits flush with a face of any scope
+// shape (planar coincidence). These are the rib's mounting faces — they
+// must not be tilted by draft; tilting them either tears the rib away
+// from the parent (negative draft) or makes OCC's draft fail (positive
+// draft), since there's no material outside the parent wall for the
+// tilt to extend into.
+// Rib faces whose surface normal is parallel to `direction` — for the
+// rib's draft step this picks out the "cap" faces at the spine endpoints
+// (perpendicular to the spine direction). They cap the slab length and
+// shouldn't tilt under draft; only the wall faces, whose normals are
+// perpendicular to spineDir, take the taper.
+function findFacesAlignedWith(faces, direction) {
+    const out = [];
+    for (const f of faces) {
+        if (FaceQuery.getSurfaceType(f) !== "plane") {
+            continue;
+        }
+        const pl = FaceQuery.getSurfacePlane(f);
+        if (1 - Math.abs(pl.normal.dot(direction)) < 1e-4) {
+            out.push(f);
+        }
+    }
+    return out;
+}
+function findScopeCoincidentFaces(ribSideFaces, scopeShapes) {
+    const out = [];
+    const scopePlanarFaces = [];
+    for (const scope of scopeShapes) {
+        const rawFaces = Explorer.findShapes(scope.getShape(), Explorer.getOcShapeType("face"));
+        for (const rf of rawFaces) {
+            const wrapped = Face.fromTopoDSFace(Explorer.toFace(rf));
+            if (FaceQuery.getSurfaceType(wrapped) !== "plane") {
+                continue;
+            }
+            const pl = FaceQuery.getSurfacePlane(wrapped);
+            scopePlanarFaces.push({ face: wrapped, origin: pl.origin, normal: pl.normal });
+        }
+    }
+    const tol = 1e-4;
+    for (const rf of ribSideFaces) {
+        if (FaceQuery.getSurfaceType(rf) !== "plane") {
+            continue;
+        }
+        const rPl = FaceQuery.getSurfacePlane(rf);
+        for (const { origin: sOrigin, normal: sNormal } of scopePlanarFaces) {
+            // Parallel test: |normal · normal'| ≈ 1
+            if (1 - Math.abs(rPl.normal.dot(sNormal)) > 1e-6) {
+                continue;
+            }
+            // Coincidence test: perpendicular distance from one plane's origin
+            // to the other plane is below tolerance. (FaceQuery.getSignedPlaneDistance
+            // routes through gp_Pln.Distance, which returns 0 for parallel-but-
+            // separated planes — useless for coincidence — so we compute it
+            // directly here.)
+            const offset = sOrigin.vectorTo(rPl.origin);
+            const d = Math.abs(offset.dot(sNormal));
+            if (d <= tol) {
+                out.push(rf);
+                break;
+            }
+        }
+    }
+    return out;
+}

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 injectFromMembershipSets;
     private collectFromSceneObjects;
     private getAllShapes;
     getDependencies(): SceneObject[];

package/lib/dist/features/select.js

@@ -3,6 +3,7 @@ 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";
+import { TopologyIndex } from "../oc/topology-index.js";
 export class SelectSceneObject extends SceneObject {
     filters;
     constraintObject;
@@ -50,8 +51,39 @@ export class SelectSceneObject extends SceneObject {
         if (this.type === "edge") {
             this.injectScopeFaces(filters, sceneObjects);
         }
-        const filteredShapes = this.applyFilters(allShapes, filters);
-        this.addShapes(filteredShapes);
+        const fromFilters = this.injectFromMembershipSets(filters);
+        try {
+            const filteredShapes = this.applyFilters(allShapes, filters);
+            this.addShapes(filteredShapes);
+        }
+        finally {
+            for (const { filter, set } of fromFilters) {
+                filter.setMembershipSet(null);
+                set.delete();
+            }
+        }
+    }
+    injectFromMembershipSets(filters) {
+        const allocated = [];
+        for (const builder of filters) {
+            for (const filter of builder.getFilters()) {
+                if (filter instanceof FromSceneObjectFilter) {
+                    const shapeType = filter.getShapeType();
+                    const rawShapes = [];
+                    for (const obj of filter.getSceneObjects()) {
+                        for (const owner of obj.getShapes()) {
+                            for (const sub of owner.getSubShapes(shapeType)) {
+                                rawShapes.push(sub.getShape());
+                            }
+                        }
+                    }
+                    const set = TopologyIndex.buildShapeSet(rawShapes);
+                    filter.setMembershipSet(set);
+                    allocated.push({ filter, set });
+                }
+            }
+        }
+        return allocated;
     }
     collectFromSceneObjects(filters) {
         const objects = [];
@@ -70,8 +102,17 @@ export class SelectSceneObject extends SceneObject {
     }
     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));
-        return scopeShapes.filter(shape => !exludedShapes.some(exShape => exShape.isSame(shape)));
+        const flatExcluded = exludedShapes.flatMap(s => s.getSubShapes(this.type));
+        if (flatExcluded.length === 0) {
+            return scopeShapes;
+        }
+        const excludedSet = TopologyIndex.buildShapeSet(flatExcluded.map(s => s.getShape()));
+        try {
+            return scopeShapes.filter(shape => !excludedSet.Contains(shape.getShape()));
+        }
+        finally {
+            excludedSet.delete();
+        }
     }
     getDependencies() {
         const deps = [];
@@ -97,16 +138,37 @@ export class SelectSceneObject extends SceneObject {
         return new SelectSceneObject(mirroredFilters, this.constraintObject);
     }
     injectScopeFaces(filters, sceneObjects) {
-        let scopeFaces = null;
+        let scopeSolids = null;
+        let extraFaces = null;
+        let faceByHash = null;
         for (const builder of filters) {
             for (const filter of builder.getFilters()) {
                 if (filter instanceof BelongsToFaceFilter || filter instanceof NotBelongsToFaceFilter) {
-                    if (!scopeFaces) {
-                        scopeFaces = this.constraintObject
-                            ? this.constraintObject.getShapes().flatMap(s => s.getSubShapes("face"))
-                            : sceneObjects.flatMap(obj => obj.getShapes({}, 'solid').flatMap(s => s.getSubShapes("face")));
+                    if (!scopeSolids) {
+                        if (this.constraintObject) {
+                            const constraintShapes = this.constraintObject.getShapes();
+                            scopeSolids = constraintShapes.filter(s => s.isSolid());
+                            // Faces directly in the constraint (not part of a solid) need the
+                            // legacy linear-scan path since they don't have a cached index.
+                            extraFaces = constraintShapes
+                                .filter(s => !s.isSolid())
+                                .flatMap(s => s.getSubShapes("face"));
+                        }
+                        else {
+                            scopeSolids = sceneObjects.flatMap(obj => obj.getShapes({}, 'solid'));
+                            extraFaces = [];
+                        }
+                        faceByHash = new Map();
+                        for (const solid of scopeSolids) {
+                            for (const face of solid.getFaces()) {
+                                addToBucket(faceByHash, face);
+                            }
+                        }
+                        for (const face of extraFaces) {
+                            addToBucket(faceByHash, face);
+                        }
                     }
-                    filter.setScopeFaces(scopeFaces);
+                    filter.setScopeIndex(scopeSolids, extraFaces, faceByHash);
                 }
             }
         }
@@ -158,3 +220,12 @@ export class SelectSceneObject extends SceneObject {
         };
     }
 }
+function addToBucket(faceByHash, face) {
+    const hash = face.getShape().HashCode(2147483647);
+    let bucket = faceByHash.get(hash);
+    if (!bucket) {
+        bucket = [];
+        faceByHash.set(hash, bucket);
+    }
+    bucket.push(face);
+}

package/lib/dist/filters/edge/belongs-to-face.d.ts

@@ -1,22 +1,25 @@
 import { Matrix4 } from "../../math/matrix4.js";
 import { Edge, Face } from "../../common/shapes.js";
+import { Solid } from "../../common/solid.js";
 import { FilterBase } from "../filter-base.js";
 import { FilterBuilderBase } from "../filter-builder-base.js";
-export declare class BelongsToFaceFilter extends FilterBase<Edge> {
-    private faceFilterBuilders;
-    private scopeFaces;
+declare abstract class BelongsToFaceFilterBase extends FilterBase<Edge> {
+    protected faceFilterBuilders: FilterBuilderBase<Face>[];
+    protected scopeSolids: Solid[];
+    protected scopeFaces: Face[];
+    protected faceByHash: Map<number, Face[]>;
     constructor(faceFilterBuilders: FilterBuilderBase<Face>[]);
-    setScopeFaces(faces: Face[]): void;
+    setScopeIndex(solids: Solid[], extraFaces: Face[], faceByHash: Map<number, Face[]>): void;
+    protected findContainingFaces(edge: Edge): Face[];
+}
+export declare class BelongsToFaceFilter extends BelongsToFaceFilterBase {
     match(shape: Edge): boolean;
     compareTo(other: BelongsToFaceFilter): boolean;
     transform(matrix: Matrix4): BelongsToFaceFilter;
 }
-export declare class NotBelongsToFaceFilter extends FilterBase<Edge> {
-    private faceFilterBuilders;
-    private scopeFaces;
-    constructor(faceFilterBuilders: FilterBuilderBase<Face>[]);
-    setScopeFaces(faces: Face[]): void;
+export declare class NotBelongsToFaceFilter extends BelongsToFaceFilterBase {
     match(shape: Edge): boolean;
     compareTo(other: NotBelongsToFaceFilter): boolean;
     transform(matrix: Matrix4): NotBelongsToFaceFilter;
 }
+export {};

package/lib/dist/filters/edge/belongs-to-face.js

@@ -1,16 +1,53 @@
+import { Face } from "../../common/shapes.js";
+import { Explorer } from "../../oc/explorer.js";
+import { TopologyIndex } from "../../oc/topology-index.js";
 import { FilterBase } from "../filter-base.js";
-export class BelongsToFaceFilter extends FilterBase {
+class BelongsToFaceFilterBase extends FilterBase {
     faceFilterBuilders;
+    scopeSolids = [];
     scopeFaces = [];
+    faceByHash = new Map();
     constructor(faceFilterBuilders) {
         super();
         this.faceFilterBuilders = faceFilterBuilders;
     }
-    setScopeFaces(faces) {
-        this.scopeFaces = faces;
+    setScopeIndex(solids, extraFaces, faceByHash) {
+        this.scopeSolids = solids;
+        this.scopeFaces = extraFaces;
+        this.faceByHash = faceByHash;
     }
+    findContainingFaces(edge) {
+        const edgeShape = edge.getShape();
+        const seen = new Set();
+        const result = [];
+        for (const solid of this.scopeSolids) {
+            const index = solid.getEdgeToFacesIndex();
+            const rawFaces = TopologyIndex.seekShapes(index, edgeShape);
+            for (const raw of rawFaces) {
+                const wrapper = resolveFaceWrapper(raw, this.faceByHash);
+                if (wrapper && !seen.has(wrapper)) {
+                    seen.add(wrapper);
+                    result.push(wrapper);
+                }
+            }
+        }
+        if (this.scopeFaces.length > 0) {
+            for (const face of this.scopeFaces) {
+                if (seen.has(face)) {
+                    continue;
+                }
+                if (face.hasEdge(edgeShape) !== null) {
+                    seen.add(face);
+                    result.push(face);
+                }
+            }
+        }
+        return result;
+    }
+}
+export class BelongsToFaceFilter extends BelongsToFaceFilterBase {
     match(shape) {
-        const containingFaces = this.scopeFaces.filter(face => face.hasEdge(shape.getShape()) !== null);
+        const containingFaces = this.findContainingFaces(shape);
         return this.faceFilterBuilders.every(builder => {
             const filters = builder.getFilters();
             return containingFaces.some(face => filters.every(f => f.match(face)));
@@ -32,18 +69,9 @@ export class BelongsToFaceFilter extends FilterBase {
         return new BelongsToFaceFilter(transformed);
     }
 }
-export class NotBelongsToFaceFilter extends FilterBase {
-    faceFilterBuilders;
-    scopeFaces = [];
-    constructor(faceFilterBuilders) {
-        super();
-        this.faceFilterBuilders = faceFilterBuilders;
-    }
-    setScopeFaces(faces) {
-        this.scopeFaces = faces;
-    }
+export class NotBelongsToFaceFilter extends BelongsToFaceFilterBase {
     match(shape) {
-        const containingFaces = this.scopeFaces.filter(face => face.hasEdge(shape.getShape()) !== null);
+        const containingFaces = this.findContainingFaces(shape);
         return !this.faceFilterBuilders.every(builder => {
             const filters = builder.getFilters();
             return containingFaces.some(face => filters.every(f => f.match(face)));
@@ -65,3 +93,24 @@ export class NotBelongsToFaceFilter extends FilterBase {
         return new NotBelongsToFaceFilter(transformed);
     }
 }
+function resolveFaceWrapper(rawFace, faceByHash) {
+    const hash = rawFace.HashCode(2147483647);
+    const bucket = faceByHash.get(hash);
+    if (bucket) {
+        for (const candidate of bucket) {
+            if (candidate.getShape().IsSame(rawFace)) {
+                return candidate;
+            }
+        }
+    }
+    // Not in scope (e.g. neighbor face from another part / out-of-scope solid).
+    // Wrap on the fly so the face filters can still evaluate it.
+    const wrapped = Face.fromTopoDSFace(Explorer.toFace(rawFace));
+    if (!bucket) {
+        faceByHash.set(hash, [wrapped]);
+    }
+    else {
+        bucket.push(wrapped);
+    }
+    return wrapped;
+}

package/lib/dist/filters/filter-builder-base.d.ts

@@ -1,12 +1,37 @@
 import { Shape } from "../common/shapes.js";
 import { FilterBase } from "./filter-base.js";
+export type IndexSelector = {
+    type: 'first';
+} | {
+    type: 'last';
+} | {
+    type: 'at';
+    index: number;
+};
 export declare class FilterBuilderBase<TShape extends Shape = Shape> {
     protected filters: FilterBase<TShape>[];
     protected _withTangents: boolean;
+    protected _indexSelector?: IndexSelector;
     filter(filter: FilterBase<TShape>): this;
     /**
      * Expands the selection to include all shapes transitively connected
      * by tangency (G1 continuity) to the initially matched shapes.
      */
     withTangents(): this;
+    /**
+     * Selects the first matching shape (in iteration order). If called multiple
+     * times on the same builder, the last positional call wins.
+     */
+    first(): this;
+    /**
+     * Selects the last matching shape (in iteration order). If called multiple
+     * times on the same builder, the last positional call wins.
+     */
+    last(): this;
+    /**
+     * Selects the matching shape at the given zero-based index.
+     * Out-of-range indices yield no match. Negative indices are not supported;
+     * use {@link last} for the final element.
+     */
+    at(index: number): this;
 }