flo-mat 4.1.4 → 5.0.1

package/__tests__/cp-node/fs/get-salience.spec.ts

@@ -1,7 +1,72 @@
 import { expect, test } from '@jest/globals';
+import { distanceBetween } from 'flo-vector2d';
 import { getSalience } from '../../../src/cp-node/fs/get-salience.js';
+import { getBoundaryBeziersBetween } from '../../../src/cp-node/fs/get-boundary-beziers-between.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getAllOnLoop_ByLoop } from '../../../src/cp-node/fs/get-all-on-loop-by-loop.js';
+import { getRealProngCount } from '../../../src/cp-node/fs/get-real-prong-count.js';
+import { getMats1 } from '../../get-mats1.js';
+import { getMatsWithHole } from '../../get-mats-with-hole.js';
+import { cpNodesByIdOn } from '../../helpers/cp-node-by-id.js';
 
-test.skip('getSalience [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('getSalience', function() {
+    const { cpNode } = getMats1()[0];
+    const byId = cpNodesByIdOn(cpNode);
+
+    // Salience = (boundary length from this contact point forward to the next
+    // contact point on the circle) / (straight distance between them).
+
+    {
+        // 2-prong {10,11} touching [46,8] and a point on the other edge of the
+        // corner [24,8]: from id 11 the boundary runs to the corner and on to
+        // [46,8] - two equal tangent lengths of 22.
+        const cp = byId(11);
+        const d = distanceBetween(cp.pointOnShape.p, cp.nextOnCircle.pointOnShape.p);
+        expect(getSalience(cp)).toBeCloseTo(44/d, 9);
+    }
+    {
+        // 3-prong {142,143,144}: from [46,8] (id 144) forward to [117,8]
+        // (id 142) the boundary goes round the top of the rectangle:
+        // 46 + 71 + 46 = 163, against a chord of 71.
+        expect(getSalience(byId(144))).toBeCloseTo(163/71, 9);
+    }
+
+    // the boundary is never shorter than the chord
+    for (const cp of getAllOnLoop(cpNode)) {
+        if (getRealProngCount(cp) < 2) { continue; }  // 1-prongs: see below
+        const s = getSalience(cp);
+        expect(Number.isFinite(s)).toBe(true);
+        expect(s).toBeGreaterThanOrEqual(1);
+    }
+
+    // 1-prongs (two nodes at the same point): the terminating node has no
+    // boundary between itself and its twin - salience 0 - while the twin has
+    // the entire boundary - salience Infinity. Ids 0 and 1 at the corner
+    // [24,8] are such a pair.
+    expect(getSalience(byId(0))).toBe(0);
+    expect(getSalience(byId(1))).toBe(Infinity);
+    for (const cp of getAllOnLoop(cpNode)) {
+        if (getRealProngCount(cp) >= 2) { continue; }
+        const s = getSalience(cp);
+        expect(Number.isNaN(s)).toBe(false);
+        expect(s === 0 || s === Infinity).toBe(true);
+    }
+});
+
+
+test('getSalience - hole closers', function() {
+    const { cpNode } = getMatsWithHole()[0];
+
+    // a stretch of boundary passing a hole closer has infinite salience
+    const cpNodes = getAllOnLoop_ByLoop(cpNode).flat();
+    let infinite = 0;
+    for (const cp of cpNodes) {
+        const { hasHoleCloser } = getBoundaryBeziersBetween(cp, cp.nextOnCircle);
+        if (hasHoleCloser) {
+            infinite++;
+            expect(getSalience(cp)).toBe(Infinity);
+        }
+    }
+    expect(infinite).toBeGreaterThan(0);
 });

package/__tests__/cp-node/fs/get-vertex-forward-children.spec.ts

@@ -1,7 +1,44 @@
 import { expect, test } from '@jest/globals';
 import { getVertexForwardChildren } from '../../../src/cp-node/fs/get-vertex-forward-children.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getAllOnCircle } from '../../../src/cp-node/fs/get-all-on-circle.js';
+import { isTerminating } from '../../../src/cp-node/fs/is-terminating.js';
+import { getMats1 } from '../../get-mats1.js';
+import { cpNodesByIdOn } from '../../helpers/cp-node-by-id.js';
 
-test.skip('getVertexForwardChildren [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('getVertexForwardChildren', function() {
+    const { cpNode } = getMats1()[0];
+    const byId = cpNodesByIdOn(cpNode);
+    const childIds = (id: number) => getVertexForwardChildren(byId(id)).map(cp => cp.id);
+
+    // Seen as a vertex entered via the given node (its `prevOnCircle` being
+    // the edge back to the parent), the forward children are the far ends of
+    // the other edges, in on-circle order.
+    expect(childIds(144)).toEqual([147, 148]);  // 3-prong: two children
+    expect(childIds(142)).toEqual([148, 11]);   // same 3-prong, entered differently
+    expect(childIds(147)).toEqual([2, 4]);      // 3-prong towards two leaves
+    expect(childIds(10)).toEqual([144]);        // 2-prong: one child
+    expect(childIds(1)).toEqual([10]);          // leaf, leaving
+    expect(childIds(0)).toEqual([]);            // leaf, entered - no children
+
+    for (const cp of getAllOnLoop(cpNode)) {
+        const children = getVertexForwardChildren(cp);
+
+        // one child per non-terminating node on the circle other than the one
+        // leading back
+        const ring = getAllOnCircle(cp);
+        const expected = ring
+            .filter(c => c !== cp.prevOnCircle && !isTerminating(c))
+            .map(c => c.next);
+        expect(children.length).toBe(expected.length);
+        expect(children.every((c, i) => c === expected[i])).toBe(true);
+
+        for (const child of children) {
+            // a child is reached by an edge from this vertex...
+            expect(child.prev.pointOnShape.circle).toBe(cp.pointOnShape.circle);
+            // ...to a different vertex
+            expect(child.pointOnShape.circle).not.toBe(cp.pointOnShape.circle);
+        }
+    }
 });

package/__tests__/cp-node/fs/insert-cp-node.spec.ts

@@ -1,7 +1,91 @@
 import { expect, test } from '@jest/globals';
+import { RbTree } from 'flo-ll-rb-tree';
+import type { CpNode } from '../../../src/cp-node/cp-node.js';
+import type { PointOnShape } from '../../../src/point-on-shape/point-on-shape.js';
 import { insertCpNode } from '../../../src/cp-node/fs/insert-cp-node.js';
+import { cpNodeComparator } from '../../../src/cp-node/fs/cp-node-comparator.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getMats1 } from '../../get-mats1.js';
+import { cpNodesByIdOn } from '../../helpers/cp-node-by-id.js';
 
-test.skip('insertCpNode [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+/** A point on the shape (on the curve of the given node at `t`) with a zero disk. */
+function posOnCurveOf(cpNode: CpNode, t: number, p: number[]): PointOnShape {
+    return {
+        curve: cpNode.pointOnShape.curve, t, p,
+        pDd: [[0,p[0]],[0,p[1]]], isSource: true,
+        circle: { center: p, radius: 0 }, order: 0, order2: 0
+    };
+}
+
+
+test('insertCpNode', function() {
+    const { cpNode } = getMats1()[0];
+    const byId = cpNodesByIdOn(cpNode);
+    const all = getAllOnLoop(cpNode);
+    const cpTree = new RbTree<CpNode>(cpNodeComparator);
+    for (const cp of all) { cpTree.insert(cp); }
+    const lastInsertId = { id: 1000 };
+
+    // insert between [24,8] (id 1, end of curve 0) and [46,8] (id 10, end of
+    // curve 1) a point halfway along curve 1
+    const pred = byId(1);
+    const succ = byId(10);
+    const pos = posOnCurveOf(succ, 0.5, [35, 8]);
+    const inserted = insertCpNode(false, false, false, cpTree, pos, pred, succ, lastInsertId)!;
+
+    expect(inserted).toBeDefined();
+    expect(inserted.id).toBe(1000);
+    expect(lastInsertId.id).toBe(1001);
+    expect(inserted.pointOnShape).toBe(pos);
+    expect(inserted.isHoleClosing).toBe(false);
+    expect(inserted.isIntersection).toBe(false);
+    // linked into the loop...
+    expect(inserted.prev).toBe(pred);
+    expect(inserted.next).toBe(succ);
+    expect(pred.next).toBe(inserted);
+    expect(succ.prev).toBe(inserted);
+    expect(getAllOnLoop(cpNode).length).toBe(all.length + 1);
+    // ...and into the tree, in order
+    expect(cpTree.find(inserted)?.datum).toBe(inserted);
+    expect(cpTree.size).toBe(all.length + 1);
+    const inOrder = cpTree.toArr();
+    expect(inOrder.length).toBe(all.length + 1);
+    expect(inOrder[inOrder.indexOf(pred) + 1]).toBe(inserted);
+    expect(inOrder[inOrder.indexOf(inserted) + 1]).toBe(succ);
+    // the on-circle edges are left for the caller to set
+    expect(inserted.nextOnCircle).toBeUndefined();
+    expect(inserted.prevOnCircle).toBeUndefined();
+
+    {
+        // A point on curve 3 does not belong between ids 1 and 10 - refused
+        // unless told to insert regardless. (At t=0.25 - not t=0.5 where id
+        // 145 already sits, which the tree would treat as a duplicate.)
+        const wrongPos = posOnCurveOf(byId(145), 0.25, [63.75, 54]);
+        const r = insertCpNode(false, false, false, cpTree, wrongPos, pred, inserted, lastInsertId);
+        expect(r).toBeUndefined();
+        expect(pred.next).toBe(inserted);
+        expect(cpTree.size).toBe(all.length + 1);
+        expect(lastInsertId.id).toBe(1001);
+
+        const forced = insertCpNode(true, true, true, cpTree, wrongPos, pred, inserted, lastInsertId)!;
+        expect(forced).toBeDefined();
+        expect(forced.id).toBe(1001);
+        expect(forced.isHoleClosing).toBe(true);
+        expect(forced.isIntersection).toBe(true);
+        expect(pred.next).toBe(forced);
+        expect(forced.next).toBe(inserted);
+        expect(inserted.prev).toBe(forced);
+        expect(cpTree.size).toBe(all.length + 2);
+    }
+
+    {
+        // without a predecessor the node starts a loop of its own
+        const emptyTree = new RbTree<CpNode>(cpNodeComparator);
+        const lone = insertCpNode(false, false, false, emptyTree, pos, undefined, undefined, lastInsertId)!;
+        expect(lone.next).toBe(lone);
+        expect(lone.prev).toBe(lone);
+        expect(emptyTree.size).toBe(1);
+        expect(emptyTree.toArr()[0]).toBe(lone);
+    }
 });

package/__tests__/cp-node/fs/is-special.spec.ts

@@ -10,7 +10,7 @@ test('isSpecial', function() {
     const allOnLoop = getAllOnLoop(cpNode);
 
     for (const n of allOnLoop) {
-        const expected = getRealProngCount(n) !== 2 && !n.isHoleClosing;
+        const expected = getRealProngCount(n) !== 2 || n.isHoleClosing;
         expect(isSpecial(n)).toBe(expected);
     }
 });

package/__tests__/cp-node/fs/remove-cp-node.spec.ts

@@ -1,7 +1,46 @@
 import { expect, test } from '@jest/globals';
+import { RbTree } from 'flo-ll-rb-tree';
+import type { CpNode } from '../../../src/cp-node/cp-node.js';
+import type { MatMeta } from '../../../src/mat/mat-meta.js';
 import { removeCpNode } from '../../../src/cp-node/fs/remove-cp-node.js';
+import { cpNodeComparator } from '../../../src/cp-node/fs/cp-node-comparator.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getMats1 } from '../../get-mats1.js';
+import { cpNodesByIdOn } from '../../helpers/cp-node-by-id.js';
 
-test.skip('removeCpNode [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('removeCpNode', function() {
+    const { cpNode } = getMats1()[0];
+    const byId = cpNodesByIdOn(cpNode);
+    const all = getAllOnLoop(cpNode);
+
+    const loop = cpNode.pointOnShape.curve.loop;
+    const cpTree = new RbTree<CpNode>(cpNodeComparator);
+    for (const cp of all) { cpTree.insert(cp); }
+    const meta = { cpTrees: new Map([[loop, cpTree]]) } as unknown as MatMeta;
+
+    const cp = byId(10);
+    const prev = cp.prev;  // id 1
+    const next = cp.next;  // id 144
+    expect(cpTree.find(cp)?.datum).toBe(cp);
+
+    removeCpNode(cp, meta);
+
+    // (compare `CpNode`s by identity / id only - they are circular structures
+    // that must not be deep-compared)
+
+    // unlinked from the loop...
+    expect(prev.next).toBe(next);
+    expect(next.prev).toBe(prev);
+    const remaining = getAllOnLoop(cpNode);
+    expect(remaining.length).toBe(all.length - 1);
+    expect(remaining.includes(cp)).toBe(false);
+    // ...and from the tree, with everything else still there
+    expect(cpTree.find(cp)).toBeUndefined();
+    expect(cpTree.size).toBe(all.length - 1);
+    const expectedIds = all.filter(c => c !== cp).sort(cpNodeComparator).map(c => c.id);
+    expect(cpTree.toArr().map(c => c.id)).toEqual(expectedIds);
+    // the removed node itself is left untouched
+    expect(cp.prev).toBe(prev);
+    expect(cp.next).toBe(next);
 });

package/__tests__/find-2-prong/calc-seperation-tolerance.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from '@jest/globals';
+import { calcSquaredSeperationTolerance } from '../../src/find-2-prong/calc-seperation-tolerance.js';
+
+
+/**
+ * Reference: the squared chord `(2r·sin(θ/2))²` with `θ` from the law of
+ * cosines formulation, computed via `1 - cos θ` to avoid cancellation.
+ */
+function refSquaredChord(R: number, r: number, δ: number) {
+    const oneMinusCos = (R*δ + δ*δ/2) / ((R - r)*(r + δ));
+    const θ = 2*Math.asin(Math.sqrt(oneMinusCos/2));
+    return (2*r*Math.sin(θ/2))**2;
+}
+
+
+test('calcSquaredSeperationTolerance', function() {
+    // a spread of osculating radii, MAT radii and (tiny) distance tolerances
+    const cases: [number, number, number][] = [
+        [100, 50, 2**-34], [100, 99, 2**-34], [1000, 0.5, 2**-30],
+        [100, 99.999, 2**-34], [37.3, 12.1, 2**-40], [2**20, 1000, 2**-24],
+    ];
+    for (const [R, r, δ] of cases) {
+        const d2 = calcSquaredSeperationTolerance(R, r, δ);
+        expect(Number.isFinite(d2)).toBe(true);
+        expect(d2).toBeGreaterThan(0);
+        // agrees with the trigonometric reference
+        expect(d2 / refSquaredChord(R, r, δ)).toBeCloseTo(1, 12);
+    }
+
+    // the closer the MAT radius gets to the osculating radius (a near
+    // 1-prong) the larger the separation required
+    const grow = [10, 50, 90, 99, 99.9].map(r => calcSquaredSeperationTolerance(100, r, 2**-34));
+    for (let i=1; i<grow.length; i++) { expect(grow[i]).toBeGreaterThan(grow[i-1]); }
+
+    // ...and a larger error tolerance requires more separation too
+    expect(calcSquaredSeperationTolerance(100, 50, 2**-30))
+        .toBeGreaterThan(calcSquaredSeperationTolerance(100, 50, 2**-34));
+
+    // the enlarged MAT circle reaching the osculating circle: reject everything
+    expect(calcSquaredSeperationTolerance(100, 100, 2**-34)).toBe(Infinity);
+    expect(calcSquaredSeperationTolerance(100, 100 - 2**-40, 2**-34)).toBe(Infinity);
+    expect(calcSquaredSeperationTolerance(100, 120, 2**-34)).toBe(Infinity);
+
+    // sanity: a concrete value (R=100, r=50, δ=2**-34), chord ~ 1.079e-4
+    expect(Math.sqrt(calcSquaredSeperationTolerance(100, 50, 2**-34))).toBeCloseTo(1.078959e-4, 9);
+});

package/__tests__/find-2-prong/get-medial/dd-get-medial-point-coeffs-same-curve.spec.ts

@@ -5,6 +5,8 @@ import { ddGetMedialPointCoeffsBez2_SameCurve } from '../../../src/get-medial-po
 import { ddGetMedialPointCoeffsBez3_SameCurve } from '../../../src/get-medial-points/double-double/dd-get-medial-point-coeffs-bez3-same-curve.js';
 import { ddNormal } from 'flo-bezier3';
 
+const { abs, floor } = Math;
+
 
 function toDdVec(v: number[]): number[][] {
     return v.map(x => [0, x]);
@@ -17,7 +19,7 @@ function ddPolyToDouble(poly: number[][]): number[] {
 function normalizedPoly(poly: number[]): number[] {
     let m = 0;
     for (const x of poly) {
-        const ax = Math.abs(x);
+        const ax = abs(x);
         if (ax > m) { m = ax; }
     }
 
@@ -34,8 +36,8 @@ function randomNumberIn01(seed: number): number {
 
 function randomSignedValue(seed: number): number {
     const sign = randomNumberIn01(seed) < 0.5 ? -1 : 1;
-    const exponent = Math.floor(randomNumberIn01(seed + 1) * 61) - 30;
-    const mantissa = 1 + Math.floor(randomNumberIn01(seed + 2) * 2**20);
+    const exponent = floor(randomNumberIn01(seed + 1) * 61) - 30;
+    const mantissa = 1 + floor(randomNumberIn01(seed + 2) * 2**20);
 
     return sign * mantissa * 2**exponent;
 }
@@ -67,7 +69,7 @@ test.skip('dd same-curve coefficients match flo-bezier3 double coefficients', fu
 
         const n2Dd = ddNormal(ps2, t);
         let v2 = [n2Dd[0][1], n2Dd[1][1]];
-        if (Math.abs(v2[0]) + Math.abs(v2[1]) < 2**-20) {
+        if (abs(v2[0]) + abs(v2[1]) < 2**-20) {
             v2 = [v2[0] + 1, v2[1] - 1];
         }
         const v2Dd = toDdVec(v2);
@@ -89,7 +91,7 @@ test.skip('dd same-curve coefficients match flo-bezier3 double coefficients', fu
 
         const n3Dd = ddNormal(ps3, t);
         let v3 = [n3Dd[0][1], n3Dd[1][1]];
-        if (Math.abs(v3[0]) + Math.abs(v3[1]) < 2**-20) {
+        if (abs(v3[0]) + abs(v3[1]) < 2**-20) {
             v3 = [v3[0] + 1, v3[1] - 1];
         }
         const v3Dd = toDdVec(v3);

package/__tests__/find-2-prong/get-medial/dd-get-medial-point-coeffs.spec.ts

@@ -3,6 +3,8 @@ import { getMedialPointCoeffs } from 'flo-bezier3';
 import { ddGetMedialPointCoeffs } from '../../../src/get-medial-points/double-double/dd-get-medial-point-coeffs.js';
 import { squares } from 'squares-rng';
 
+const { floor, abs } = Math;
+
 
 function toDdVec(v: number[]): number[][] {
     return v.map(x => [0, x]);
@@ -19,7 +21,7 @@ function randomNumberIn01(seed: number): number {
 
 function randomSignedValue(seed: number): number {
     const sign = randomNumberIn01(seed) < 0.5 ? -1 : 1;
-    const exponent = Math.floor(randomNumberIn01(seed + 1) * 81) - 40;
+    const exponent = floor(randomNumberIn01(seed + 1) * 81) - 40;
     const mantissa = 1 + randomNumberIn01(seed + 2);
 
     return sign * mantissa * 2**exponent;
@@ -46,7 +48,7 @@ test('ddGetMedialPointCoeffs matches flo-bezier3 double coefficients', function(
             let v = randomPoint(seed); seed += 11;
 
             // Keep the direction away from near-zero vectors.
-            if (Math.abs(v[0]) + Math.abs(v[1]) < 2**-20) {
+            if (abs(v[0]) + abs(v[1]) < 2**-20) {
                 v = [v[0] + 1, v[1] - 1];
             }
 

package/__tests__/find-2-prong/get-medial/get-closest-points.spec.ts

@@ -44,7 +44,7 @@ test('getClosestPoints', function() {
     const def = deflate(H,t);//?
     // def = [47279295, -157379071.5, 100304568, -23598664.03125, 1904993.75390625]
 
-    const r = getClosestPoint(maxPowerOf2, nnorm, nnormDd, yPos, for1Prong, angle, curvePiece);
+    const r = getClosestPoint(maxPowerOf2, nnormDd, yPos, for1Prong, angle, curvePiece);
 
     r;//?
 

package/__tests__/floyd-warshall/get-graph.spec.ts

@@ -0,0 +1,100 @@
+import { expect, test } from '@jest/globals';
+import type { CpNode } from '../../src/cp-node/cp-node.js';
+import { getGraph } from '../../src/floyd-warshall/get-graph.js';
+import { getAllOnLoop } from '../../src/cp-node/fs/get-all-on-loop.js';
+import { getAllOnCircle } from '../../src/cp-node/fs/get-all-on-circle.js';
+import { isVertexSpecial } from '../../src/cp-node/fs/is-vertex-special.js';
+import { getPathsFromStr } from 'flo-boolean';
+import { findMats } from '../../src/find-mat/find-mats.js';
+import { getMats1 } from '../get-mats1.js';
+
+
+/** One `CpNode` per special vertex (leaves, 3-prongs, hole closers). */
+function getSpecialVertices(cpNode: CpNode): CpNode[] {
+    const seen = new Set<CpNode>();
+    const vertices: CpNode[] = [];
+    for (const cp of getAllOnLoop(cpNode)) {
+        if (seen.has(cp)) { continue; }
+        for (const c of getAllOnCircle(cp)) { seen.add(c); }
+        if (isVertexSpecial(cp)) { vertices.push(cp); }
+    }
+    return vertices;
+}
+
+
+function checkGraph(graph: number[][], V: number, symmetricLengths: boolean) {
+    expect(graph.length).toBe(V);
+    for (let i=0; i<V; i++) {
+        expect(graph[i].length).toBe(V);
+        expect(graph[i][i]).toBe(0);
+        let adjacent = 0;
+        for (let j=0; j<V; j++) {
+            const d = graph[i][j];
+            // symmetric adjacency...
+            expect(Number.isFinite(graph[j][i])).toBe(Number.isFinite(d));
+            // ...and symmetric lengths (up to the summation order of the edge
+            // lengths) - except across hole closers, where the two directions
+            // currently accumulate slightly different lengths (pre-existing)
+            if (symmetricLengths && Number.isFinite(d)) {
+                expect(d).toBeCloseTo(graph[j][i], 9);
+            }
+            expect(d >= 0).toBe(true);
+            if (i !== j && Number.isFinite(d)) { adjacent++; }
+        }
+        // the MAT is connected: every special vertex has a neighbour
+        expect(adjacent).toBeGreaterThan(0);
+    }
+}
+
+
+test('getGraph - single loop fixture', function() {
+    const { cpNode } = getMats1()[0];
+    const vertices = getSpecialVertices(cpNode);
+    // 5 leaves + 3 3-prongs
+    expect(vertices.length).toBe(8);
+
+    const graph = getGraph(vertices);
+    checkGraph(graph, vertices.length, true);
+
+    // the 3-prong {142,143,144} (center [81.5,-12.64]) is adjacent to the
+    // 3-prong at [81.5,18.5] by a straight vertical edge of length 31.14...
+    const i = vertices.findIndex(v => v.pointOnShape.circle.center[1] === 18.5);
+    const j = vertices.findIndex(v => v.pointOnShape.circle.center[1] === -12.641417453935567);
+    expect(i).toBeGreaterThanOrEqual(0);
+    expect(j).toBeGreaterThanOrEqual(0);
+    expect(graph[i][j]).toBeCloseTo(18.5 + 12.641417453935567, 9);
+});
+
+
+test('getGraph - shape with a hole (hole closers are skipped via their twins)', function() {
+    // (not the SAT-processed fixture: the SAT culls all the spurs of a square
+    // frame, leaving only a cycle of 2-prongs and thus no special vertices)
+    const loops = getPathsFromStr(
+        'M0 0 L100 0 L100 100 L0 100 Z ' +
+        'M30 30 L30 70 L70 70 L70 30 Z'
+    );
+    const { cpNode } = findMats(loops, { applySat: false, simplify: false })[0];
+    const vertices = getSpecialVertices(cpNode).filter(v => !v.isHoleClosing);
+    // 4 outer-corner leaves + 4 3-prongs where the spurs meet the ring
+    expect(vertices.length).toBe(8);
+
+    // must terminate (the walk over a hole closer continues on the other loop)
+    const graph = getGraph(vertices);
+    checkGraph(graph, vertices.length, false);
+
+    // the 4 leaves are each adjacent to exactly one 3-prong (their spur)...
+    const leaves = vertices.filter(v => v.pointOnShape.circle.radius === 0);
+    expect(leaves.length).toBe(4);
+    for (const leaf of leaves) {
+        const i = vertices.indexOf(leaf);
+        const finite = graph[i].filter((d, j) => j !== i && Number.isFinite(d));
+        expect(finite.length).toBe(1);
+    }
+    // ...and each 3-prong to its spur leaf and its two ring neighbours
+    for (const v of vertices) {
+        if (v.pointOnShape.circle.radius === 0) { continue; }
+        const i = vertices.indexOf(v);
+        const finite = graph[i].filter((d, j) => j !== i && Number.isFinite(d));
+        expect(finite.length).toBe(3);
+    }
+});

package/__tests__/get-mats-with-hole.ts

@@ -0,0 +1,28 @@
+import type { Mat } from "../src/mat/mat.js";
+import { getPathsFromStr } from 'flo-boolean';
+import { findMats } from "../src/find-mat/find-mats.js";
+
+
+// Cache - the tests using this fixture must not mutate it.
+let mats: Mat[] | undefined = undefined;
+
+/**
+ * A square with a square hole - forces hole-closing 2-prongs (which `getMats1`
+ * does not have). Unlike `getMats1` this is calculated and thus susceptible to
+ * small perturbations in the algorithm, so only test *structural* properties
+ * against it.
+ */
+function getMatsWithHole(): Mat[] {
+    if (mats) { return mats; }
+
+    const loops = getPathsFromStr(
+        'M0 0 L100 0 L100 100 L0 100 Z ' +
+        'M30 30 L30 70 L70 70 L70 30 Z'
+    );
+    mats = findMats(loops, {});
+
+    return mats;
+}
+
+
+export { getMatsWithHole }

package/__tests__/get-mats1.spec.ts

@@ -0,0 +1,61 @@
+import { expect, test } from '@jest/globals';
+import type { Circle } from '../src/geometry/circle.js';
+import { getMats1, cpNodeStringifyable1 } from './get-mats1.js';
+import { getAllOnCircle } from '../src/cp-node/fs/get-all-on-circle.js';
+import { getAllOnLoop_ByLoop } from '../src/cp-node/fs/get-all-on-loop-by-loop.js';
+
+
+test('`getMats1` fixture: one `Circle` object per on-circle ring', function() {
+    {
+        // The stringifyable literal itself (before `fromStringifyable` 
+        // normalizes anything) must already share one `Circle` object per
+        // on-circle ring and no `Circle` object across rings.
+        const { cpNodes } = cpNodeStringifyable1;
+        const byId = new Map(cpNodes.map(cp => [cp.id, cp]));
+
+        const seen = new Set<number>();
+        const ringOfCircle = new Map<Circle, number[]>();
+        for (const cpNode of cpNodes) {
+            if (seen.has(cpNode.id)) { continue; }
+
+            // walk the ring via the `nextOnCircle` ids
+            const ring: number[] = [];
+            let cp = cpNode;
+            do {
+                ring.push(cp.id);
+                seen.add(cp.id);
+                cp = byId.get(cp.nextOnCircle as number)!;
+            } while (cp !== cpNode);
+
+            const { circle } = cpNode.pointOnShape;
+            for (const id of ring) {
+                expect(byId.get(id)!.pointOnShape.circle).toBe(circle);
+            }
+            expect(ringOfCircle.has(circle)).toBe(false);
+            ringOfCircle.set(circle, ring);
+        }
+
+        expect(ringOfCircle.size).toBe(10);
+    }
+    {
+        // ...and so does the `CpNode` graph built from it
+        const { cpNode } = getMats1()[0];
+        const cpNodes = getAllOnLoop_ByLoop(cpNode).flat();
+
+        const seen = new Set<typeof cpNode>();
+        const circles = new Set<Circle>();
+        for (const cp of cpNodes) {
+            if (seen.has(cp)) { continue; }
+
+            const { circle } = cp.pointOnShape;
+            for (const cp_ of getAllOnCircle(cp)) {
+                seen.add(cp_);
+                expect(cp_.pointOnShape.circle).toBe(circle);
+            }
+            expect(circles.has(circle)).toBe(false);
+            circles.add(circle);
+        }
+
+        expect(circles.size).toBe(10);
+    }
+});