@flighthq/binpack 0.3.0 → 0.3.1-next.1041.35b950c

package/dist/explainUnpackedRectangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explainUnpackedRectangles.d.ts","sourceRoot":"","sources":["../src/explainUnpackedRectangles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,4BAA4B,EAE7B,MAAM,0BAA0B,CAAC;AAalC,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,SAAS,QAAQ,CAAC,iBAAiB,CAAC,EAAE,EAClD,OAAO,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,GACjC,4BAA4B,EAAE,CAqBhC"}
+{"version":3,"file":"explainUnpackedRectangles.d.ts","sourceRoot":"","sources":["../src/explainUnpackedRectangles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAEjB,4BAA4B,EAE7B,MAAM,0BAA0B,CAAC;AAalC,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,SAAS,QAAQ,CAAC,iBAAiB,CAAC,EAAE,EAClD,OAAO,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,GACjC,4BAA4B,EAAE,CAiChC"}

package/dist/explainUnpackedRectangles.js

@@ -16,11 +16,24 @@ export function explainUnpackedRectangles(rectangles, options) {
     const result = packRectangles(rectangles, options);
     if (result.unpacked.length === 0)
         return [];
-    const unpacked = new Set(result.unpacked);
+    // `unpacked` is a MULTISET, not a set. packRectangles treats two rectangles sharing an id as distinct
+    // pieces, so an id appears once per piece that failed — and matching on mere membership emitted an
+    // entry for every rectangle carrying an unpacked id, which is two explanations for one failure when
+    // only one of a duplicate pair fits. Consuming a count keeps the entry count equal to the failure
+    // count, which is what the contract above promises.
+    //
+    // WHICH duplicate a given entry describes is input order, and that is the honest limit: the packer
+    // sorts by area before placing and reports bare ids, so an id cannot identify a piece the packer
+    // treats as distinct. The count is right; the attribution between same-id pieces is positional.
+    const outstanding = new Map();
+    for (const id of result.unpacked)
+        outstanding.set(id, (outstanding.get(id) ?? 0) + 1);
     const explanations = [];
     for (const rectangle of rectangles) {
-        if (!unpacked.has(rectangle.id))
+        const remaining = outstanding.get(rectangle.id) ?? 0;
+        if (remaining === 0)
             continue;
+        outstanding.set(rectangle.id, remaining - 1);
         explanations.push({
             id: rectangle.id,
             reason: getUnpackedReason(rectangle, usableWidth, usableHeight, allowRotation),

package/dist/explainUnpackedRectangles.js.map

@@ -1 +1 @@
-{"version":3,"file":"explainUnpackedRectangles.js","sourceRoot":"","sources":["../src/explainUnpackedRectangles.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/E,0GAA0G;AAC1G,2GAA2G;AAC3G,sFAAsF;AACtF,EAAE;AACF,wGAAwG;AACxG,wGAAwG;AACxG,kFAAkF;AAClF,EAAE;AACF,+FAA+F;AAC/F,MAAM,UAAU,yBAAyB,CACvC,UAAkD,EAClD,OAAkC;IAElC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IACtD,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,QAAQ,IAAI,2BAA2B,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IACpF,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,2BAA2B,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IAEtF,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE5C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAmC,EAAE,CAAC;IACxD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAAE,SAAS;QAC1C,YAAY,CAAC,IAAI,CAAC;YAChB,EAAE,EAAE,SAAS,CAAC,EAAE;YAChB,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,CAAC;YAC9E,WAAW;YACX,YAAY;SACb,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,yGAAyG;AACzG,qGAAqG;AACrG,+BAA+B;AAC/B,SAAS,iBAAiB,CACxB,SAAsC,EACtC,WAAmB,EACnB,YAAoB,EACpB,aAAsB;IAEtB,IAAI,WAAW,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,iBAAiB,CAAC;IACpE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;QAC9E,IAAI,CAAC,aAAa;YAAE,OAAO,WAAW,CAAC;QACvC,gGAAgG;QAChG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,CAAC;YAAE,OAAO,WAAW,CAAC;IACpG,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa,EAAE,MAAc,EAAE,WAAmB,EAAE,YAAoB;IAC1F,OAAO,KAAK,IAAI,WAAW,IAAI,MAAM,IAAI,YAAY,CAAC;AACxD,CAAC"}
+{"version":3,"file":"explainUnpackedRectangles.js","sourceRoot":"","sources":["../src/explainUnpackedRectangles.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/E,0GAA0G;AAC1G,2GAA2G;AAC3G,sFAAsF;AACtF,EAAE;AACF,wGAAwG;AACxG,wGAAwG;AACxG,kFAAkF;AAClF,EAAE;AACF,+FAA+F;AAC/F,MAAM,UAAU,yBAAyB,CACvC,UAAkD,EAClD,OAAkC;IAElC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IACtD,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,QAAQ,IAAI,2BAA2B,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IACpF,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,2BAA2B,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IAEtF,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE5C,sGAAsG;IACtG,mGAAmG;IACnG,oGAAoG;IACpG,kGAAkG;IAClG,oDAAoD;IACpD,EAAE;IACF,mGAAmG;IACnG,iGAAiG;IACjG,gGAAgG;IAChG,MAAM,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAC;IACnD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,QAAQ;QAAE,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,MAAM,YAAY,GAAmC,EAAE,CAAC;IACxD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,SAAS,KAAK,CAAC;YAAE,SAAS;QAC9B,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;QAC7C,YAAY,CAAC,IAAI,CAAC;YAChB,EAAE,EAAE,SAAS,CAAC,EAAE;YAChB,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,CAAC;YAC9E,WAAW;YACX,YAAY;SACb,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,yGAAyG;AACzG,qGAAqG;AACrG,+BAA+B;AAC/B,SAAS,iBAAiB,CACxB,SAAsC,EACtC,WAAmB,EACnB,YAAoB,EACpB,aAAsB;IAEtB,IAAI,WAAW,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,iBAAiB,CAAC;IACpE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;QAC9E,IAAI,CAAC,aAAa;YAAE,OAAO,WAAW,CAAC;QACvC,gGAAgG;QAChG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,CAAC;YAAE,OAAO,WAAW,CAAC;IACpG,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa,EAAE,MAAc,EAAE,WAAmB,EAAE,YAAoB;IAC1F,OAAO,KAAK,IAAI,WAAW,IAAI,MAAM,IAAI,YAAY,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/binpack",
-  "version": "0.3.0",
+  "version": "0.3.1-next.1041.35b950c",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/geometry": "0.3.0",
-    "@flighthq/types": "0.3.0"
+    "@flighthq/geometry": "0.3.1-next.1041.35b950c",
+    "@flighthq/types": "0.3.1-next.1041.35b950c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/explainUnpackedRectangles.test.ts

@@ -1,6 +1,8 @@
+import type { RectangleId } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import { explainUnpackedRectangles } from './explainUnpackedRectangles';
+import { packRectangles } from './packRectangles';
 
 describe('explainUnpackedRectangles', () => {
   it('returns nothing when everything was placed', () => {
@@ -54,3 +56,72 @@ describe('explainUnpackedRectangles', () => {
     expect(explanation).toMatchObject({ id: 'a', usableWidth: 90, usableHeight: 90 });
   });
 });
+
+describe('explainUnpackedRectangles cross-checked against packRectangles', () => {
+  // The two functions must agree about the same input: an explanation per failure, no more and no less.
+  // They can disagree because they identify pieces differently — the packer treats two rectangles sharing
+  // an id as DISTINCT and reports bare ids, so a membership test cannot tell one failure from two.
+  it('returns exactly one entry per unpacked piece when two rectangles share an id', () => {
+    const rectangles = [
+      { id: 'a', width: 60, height: 60 },
+      { id: 'a', width: 60, height: 60 },
+    ];
+    const options = { growable: false, maxHeight: 64, maxWidth: 64 } as const;
+
+    const result = packRectangles(rectangles, options);
+    // One of the pair fits and the other does not, which is the case a set-based match gets wrong.
+    expect(result.placements).toHaveLength(1);
+    expect(result.unpacked).toEqual(['a']);
+
+    expect(explainUnpackedRectangles(rectangles, options)).toHaveLength(1);
+  });
+
+  it('returns one entry per failure when BOTH duplicates fail', () => {
+    const rectangles = [
+      { id: 'a', width: 500, height: 500 },
+      { id: 'a', width: 500, height: 500 },
+    ];
+    const options = { growable: false, maxHeight: 64, maxWidth: 64 } as const;
+
+    expect(packRectangles(rectangles, options).unpacked).toEqual(['a', 'a']);
+    expect(explainUnpackedRectangles(rectangles, options)).toHaveLength(2);
+  });
+
+  it('agrees with packRectangles across seeded inputs, counting ids rather than assuming uniqueness', () => {
+    for (let seed = 1; seed <= 30; seed += 1) {
+      const random = makeRandom(seed);
+      const count = 1 + Math.floor(random() * 12);
+      const rectangles = Array.from({ length: count }, (_, index) => ({
+        // Ids collide on purpose: half the seeds draw from a pool smaller than the rectangle count, so
+        // duplicate ids are the common case here rather than the exotic one.
+        id: seed % 2 === 0 ? `id-${index % 3}` : `id-${index}`,
+        width: 1 + Math.floor(random() * 80),
+        height: 1 + Math.floor(random() * 80),
+      }));
+      const options = { growable: false, maxHeight: 96, maxWidth: 96 } as const;
+      const label = `seed ${seed}`;
+
+      const unpacked = packRectangles(rectangles, options).unpacked;
+      const explained = explainUnpackedRectangles(rectangles, options);
+
+      expect(explained.length, label).toBe(unpacked.length);
+      expect(countById(explained.map((entry) => entry.id)), label).toEqual(countById(unpacked));
+    }
+  });
+});
+
+function countById(ids: readonly RectangleId[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const id of ids) counts[String(id)] = (counts[String(id)] ?? 0) + 1;
+  return counts;
+}
+
+// A small deterministic PRNG, so a failure names a seed a reader can re-run rather than a shape that
+// vanishes on the next run.
+function makeRandom(seed: number): () => number {
+  let state = seed * 1103515245 + 12345;
+  return () => {
+    state = (state * 1103515245 + 12345) % 2147483648;
+    return state / 2147483648;
+  };
+}

package/src/packRectangles.test.ts

@@ -1,4 +1,4 @@
-import type { PackableRectangle, PackedRectangle } from '@flighthq/types/contract';
+import type { PackableRectangle, PackedRectangle, RectangleId } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
 import { BIN_PACK_DEFAULT_MAX_EXTENT, getPackResultOccupancy, packRectangles } from './packRectangles';
@@ -286,7 +286,13 @@ describe('packRectangles properties', () => {
       const count = 1 + Math.floor(random() * 25);
       const rects: PackableRectangle[] = [];
       for (let i = 0; i < count; i++) {
-        rects.push({ id: i, width: 1 + Math.floor(random() * 60), height: 1 + Math.floor(random() * 60) });
+        // Every fifth seed draws ids from a pool smaller than the rectangle count, so DUPLICATE IDS are
+        // exercised rather than left exotic — the packer treats same-id rectangles as distinct pieces,
+        // and duplicates are exactly where an identity check and a count check stop agreeing. Same-id
+        // pieces are given the same size so a size assertion keyed by id still names one shape.
+        const id = seed % 5 === 0 ? i % 3 : i;
+        const size = makeRandom(seed * 1000 + (id as number));
+        rects.push({ id, width: 1 + Math.floor(size() * 60), height: 1 + Math.floor(size() * 60) });
       }
       const padding = Math.floor(random() * 4);
       const border = Math.floor(random() * 4);
@@ -296,8 +302,34 @@ describe('packRectangles properties', () => {
       const result = packRectangles(rects, options);
       const label = `seed ${seed} (${heuristic})`;
 
-      // Every input is accounted for exactly once.
+      // Every input is accounted for exactly once — BY IDENTITY, not by count. A count is satisfied by
+      // placing one piece twice and losing another, which is the corruption this package can actually
+      // produce and the one that reaches an atlas as two sprites sharing pixels.
       expect(result.placements.length + result.unpacked.length, label).toBe(rects.length);
+      expect(countIds([...result.placements.map((placement) => placement.id), ...result.unpacked]), label).toEqual(
+        countIds(rects.map((rect) => rect.id)),
+      );
+
+      // Every placement carries ITS OWN size, swapped exactly when it says it was turned. A packer that
+      // reports `rotated` without swapping places correctly and describes the placement wrongly, and the
+      // overlap and bounds assertions below both pass for it.
+      const sizes = new Map<number, { height: number; width: number }>();
+      for (const rect of rects) sizes.set(rect.id as number, { height: rect.height, width: rect.width });
+      for (const placement of result.placements) {
+        const source = sizes.get(placement.id as number)!;
+        const expected = placement.rotated
+          ? { height: source.width, width: source.height }
+          : { height: source.height, width: source.width };
+        expect({ height: placement.height, width: placement.width }, `${label}: ${String(placement.id)}`).toEqual(
+          expected,
+        );
+      }
+
+      // The occupancy helper must describe the placements it is derived from, not a stale or parallel
+      // accounting of them.
+      const placedArea = result.placements.reduce((total, placement) => total + placement.width * placement.height, 0);
+      const reportedArea = result.width * result.height;
+      expect(getPackResultOccupancy(result), label).toBeCloseTo(reportedArea > 0 ? placedArea / reportedArea : 0, 12);
 
       for (const placement of result.placements) {
         // Inside the bin, honouring the border on every side.
@@ -326,3 +358,9 @@ describe('packRectangles properties', () => {
     }
   });
 });
+
+function countIds(ids: readonly RectangleId[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const id of ids) counts[String(id)] = (counts[String(id)] ?? 0) + 1;
+  return counts;
+}