@mark1russell7/packing 0.2.2 → 0.2.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/packing",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Rectangle packing: shelf, guillotine and skyline strategies, push cascades and measures of a layout.",
   "keywords": [
     "rectangle-packing",

package/src/adapters.ts

@@ -3,10 +3,12 @@
 import { EPS, type PackInput, type PackOutput } from "./contract.ts";
 import { boundsOf, buildFrame, now, outerOf, readFrame, rectsOf, viaAxes, type Entry } from "./frame.ts";
 import { packFree } from "./free.ts";
+import { clearMoves, moveCount, MOVES } from "./moves.ts";
 import type { SortOrder } from "./order.ts";
 import { pack } from "./pack.ts";
 import { pushCascade } from "./push.ts";
 import { Rect } from "./rect.ts";
+import type { ShelfFit } from "./shelf.ts";
 import { packSkyline } from "./skyline.ts";
 import { spaceOf } from "./space.ts";
 import { assertSupported, cellOf, UnsupportedCell, type PackContext, type SizeSearch, type Strategy, type Supports } from "./strategy.ts";
@@ -17,6 +19,11 @@ export interface LayoutStrategyOptions {
   sortOrder: SortOrder;
   /** The number of widths that the first pass of the size search `log-sweep` tries. */
   samples: number;
+  /**
+   * The rule of `shelf` to choose a shelf: `next`, `first` or `best`. Only `shelf` reads it. Without it, `shelf` packs
+   * as in 0.2.3. With it, the trace also counts `move.firstFit` and `move.bestFit`.
+   */
+  fit?: ShelfFit;
 }
 
 /** The options of the strategy `push`. */
@@ -54,14 +61,28 @@ function supportsOf(cells: { [D in keyof Supports]: readonly Supports[D][number]
   };
 }
 
+/** This function gives the fit of the options of a strategy: only `shelf` reads it. */
+function fitOf(id: "rows" | "skyline" | "shelf", options: Partial<LayoutStrategyOptions>): { fit?: ShelfFit } {
+  return id === "shelf" && options.fit !== undefined ? { fit: options.fit } : {};
+}
+
+/** This function gives the move counts of the trace of a strategy: its own move, and the moves of a shelf fit. */
+function movesOf(id: "rows" | "skyline" | "shelf", fit: { fit?: ShelfFit }): Record<string, number> {
+  const out: Record<string, number> = { [MOVES[id]]: moveCount(MOVES[id]) };
+  if (fit.fit !== undefined) for (const move of [MOVES.firstFit, MOVES.bestFit]) out[move] = moveCount(move);
+  return out;
+}
+
 /** This function packs an input with a fixed size or a fixed width with one strategy of `pack`. */
 function packFixedWidth(id: "rows" | "skyline" | "shelf", input: PackInput, options: LayoutStrategyOptions): PackOutput {
   const start = now();
   const frame = buildFrame(input);
   const rects = rectsOf(frame);
-  if (frame.w > 0) pack(rects, outerOf(frame), { strategy: id, sortOrder: options.sortOrder, space: spaceOf(input, frame) });
+  const fit = fitOf(id, options);
+  clearMoves();
+  if (frame.w > 0) pack(rects, outerOf(frame), { strategy: id, sortOrder: options.sortOrder, space: spaceOf(input, frame), ...fit });
   const output = readFrame(input, frame, []);
-  return { ...output, trace: [{ id, ms: now() - start, measures: { "pack.overflow": output.overflow.length } }] };
+  return { ...output, trace: [{ id, ms: now() - start, measures: { "pack.overflow": output.overflow.length, ...movesOf(id, fit) } }] };
 }
 
 /** This function makes the strategy of one function of `pack`. */
@@ -116,6 +137,7 @@ export const skyline: Strategy<LayoutStrategyOptions> = layoutStrategy("skyline"
 /**
  * The strategy `shelf` uses `packShelf`: rows filled left to right, around the locked items and the fixed obstacles.
  * With the sort order `input`, the rows keep the rank order. Turnable items, groups and item shapes throw `UnsupportedCell`.
+ * The option `fit` selects a shelf rule of roadmap item k21: `next`, `first` or `best`. The default has no `fit`.
  */
 export const shelf: Strategy<LayoutStrategyOptions> = layoutStrategy("shelf", "shelf", ["shelf-nf", "shelf-nfdh"], {
   obstacleMove: ["fixed"],
@@ -135,6 +157,7 @@ export const logSweep: SizeSearch = {
     const o = { ...(inner.defaults as LayoutStrategyOptions), ...(options as Partial<LayoutStrategyOptions> | undefined) };
     const start = now();
     const frame = buildFrame(input);
+    const fit = fitOf(id, o);
     const result = packFree(rectsOf(frame), new Rect<number>(), {
       strategy: id,
       sortOrder: o.sortOrder,
@@ -142,6 +165,7 @@ export const logSweep: SizeSearch = {
       samples: o.samples,
       aspect: input.container.aspect ?? 1,
       aspectWeight: input.container.aspectWeight ?? 1,
+      ...fit,
     });
     const ms = now() - start;
     const runs = result.tried.length + 1;
@@ -150,7 +174,7 @@ export const logSweep: SizeSearch = {
       ...output,
       trace: [
         { id: "log-sweep", ms, measures: { "pack.search.widths": result.tried.length, "pack.search.ms": ms } },
-        { id, ms: ms / runs, measures: { "pack.overflow": output.overflow.length } },
+        { id, ms: ms / runs, measures: { "pack.overflow": output.overflow.length, ...movesOf(id, fit) } },
       ],
     };
   },
@@ -191,8 +215,9 @@ function pushFixedWidth(input: PackInput, options: PushStrategyOptions, previous
   // The cascade: each item in the order of its rank pushes the others, and then it stays
   const inPlay = frame.entries.filter((e) => !pending.includes(e)).map((e) => e.rect);
   const maxShoves = options.maxShovesPerItem * Math.max(1, inPlay.length);
+  let cascaded = 0;
   for (const e of positioned) {
-    pushCascade(e.rect, inPlay, { gap: 0, maxShoves });
+    cascaded += pushCascade(e.rect, inPlay, { gap: 0, maxShoves }).length;
     e.rect.locked = true;
   }
 
@@ -234,7 +259,7 @@ function pushFixedWidth(input: PackInput, options: PushStrategyOptions, previous
   return {
     ...output,
     trace: [
-      { id: "push", ms: pushMs, measures: { "pack.push.moved": moved.length } },
+      { id: "push", ms: pushMs, measures: { "pack.push.moved": moved.length, [MOVES.push]: cascaded } },
       { id: "skyline", ms: now() - skylineStart, measures: { "pack.push.replaced": pending.length, "pack.overflow": output.overflow.length } },
     ],
   };

package/src/free.ts

@@ -1,3 +1,4 @@
+import { clearMoves } from "./moves.ts";
 import { pack, type PackLayoutOptions } from "./pack.ts";
 import { Rect } from "./rect.ts";
 
@@ -85,6 +86,8 @@ export function packFree<T>(rects: Rect<T>[], outer: Rect<T> = new Rect(), optio
 
   const tried: FreeWidthTry[] = [];
   const run = (width: number): FreeWidthTry => {
+    // The counts of the moves come from the last run: the run with the best width
+    clearMoves();
     Rect.resetPacked(rects);
     const box = new Rect<T>();
     box.position.setTo(outer.position);

package/src/index.ts

@@ -3,7 +3,7 @@ export { Rect } from "./rect.ts";
 export { pack, packRows, type PackOptions, type PackLayoutOptions } from "./pack.ts";
 export { packSkyline, lowestWindow, type SkylineOptions } from "./skyline.ts";
 export { freeSpace, type FreeSpace, type FreeSpan, type SpaceRect } from "./space.ts";
-export { packShelf, type ShelfOptions } from "./shelf.ts";
+export { packShelf, SHELF_FITS, type ShelfFit, type ShelfOptions } from "./shelf.ts";
 export { packFree, aspectError, type FreeWidthOptions, type FreeWidthResult, type FreeWidthTry } from "./free.ts";
 export { compareRects, SORT_ORDERS, type SortOrder } from "./order.ts";
 export { pushCascade, type PushOptions } from "./push.ts";

package/src/measures.ts

@@ -13,7 +13,7 @@ export type { Direction } from "@mark1russell7/layout-contract";
 export type MeasureFamily = "density" | "aspect" | "order" | "raggedness" | "overflow" | "stability" | "determinism" | "speed";
 
 /** The id of a measure of the packer. The ids are those of `docs/FORMAT.md`, and `highways` uses the same ids. */
-export type MeasureId = "pack.area" | "pack.fill" | "pack.whitespace" | "pack.aspect" | "pack.aspectError" | "pack.order.inversions" | "pack.order.breaks" | "pack.raggedness" | "pack.overflow" | "pack.overflow.rate" | "pack.overflow.area" | "pack.overflow.forced" | "pack.overflow.forcedArea" | "pack.overflow.excess" | "pack.stability.moved" | "pack.stability.mean" | "pack.stability.q95" | "pack.deterministic" | "pack.search.widths" | "pack.search.ms";
+export type MeasureId = "pack.area" | "pack.fill" | "pack.whitespace" | "pack.aspect" | "pack.aspectError" | "pack.order.inversions" | "pack.order.breaks" | "pack.raggedness" | "pack.overflow" | "pack.overflow.rate" | "pack.overflow.area" | "pack.overflow.forced" | "pack.overflow.forcedArea" | "pack.overflow.excess" | "pack.overflow.forcedAreaMin" | "pack.overflow.excessArea" | "pack.stability.moved" | "pack.stability.mean" | "pack.stability.q95" | "pack.deterministic" | "pack.search.widths" | "pack.search.ms";
 
 /**
  * The facts of one measure: its family, its unit, its direction and its range.
@@ -51,8 +51,17 @@ export interface LayoutMeasures {
   "pack.overflow.rate": number;
   "pack.overflow.area": number;
   "pack.overflow.forced": number;
+  /** The tight lower bound of `pack.overflow.area`. `docs/MEASURES.md` defines it. */
   "pack.overflow.forcedArea": number;
   "pack.overflow.excess": number;
+  /**
+   * This measure is an alias of `pack.overflow.forcedArea`, with the same value.
+   *
+   * @deprecated Use `pack.overflow.forcedArea`. The alias stays until the next minor version.
+   */
+  "pack.overflow.forcedAreaMin": number;
+  /** The overflow area above its bound: `pack.overflow.area` less `pack.overflow.forcedArea`. */
+  "pack.overflow.excessArea": number;
   "pack.search.widths": number;
   "pack.search.ms": number;
 }
@@ -95,6 +104,8 @@ const REL = Object.freeze({ rel: 0.01 });
  * - A share of an area from 0 to 1 has 0.005. A guard has its tolerance.
  * - An area and a ratio of lengths have `{ rel: 0.01 }`: 1% of the larger value.
  * - The time has no minimum effect, because the times of CI change each time.
+ * - `pack.overflow.forcedAreaMin` is a deprecated alias of `pack.overflow.forcedArea`. Its spec is the same, except the id.
+ *   The alias stays until the next minor version.
  */
 export const MEASURE_SPECS: Readonly<Record<MeasureId, MeasureSpec>> = Object.freeze({
   "pack.area": spec("pack.area", "density", "square units", "lower", 0, Infinity, REL),
@@ -111,6 +122,9 @@ export const MEASURE_SPECS: Readonly<Record<MeasureId, MeasureSpec>> = Object.fr
   "pack.overflow.forced": spec("pack.overflow.forced", "overflow", "count", "lower", 0, Infinity, 0),
   "pack.overflow.forcedArea": spec("pack.overflow.forcedArea", "overflow", "share", "lower", 0, 1, 0.005),
   "pack.overflow.excess": spec("pack.overflow.excess", "overflow", "count", "lower", 0, Infinity, 0),
+  // The deprecated alias of pack.overflow.forcedArea, until the next minor version
+  "pack.overflow.forcedAreaMin": spec("pack.overflow.forcedAreaMin", "overflow", "share", "lower", 0, 1, 0.005),
+  "pack.overflow.excessArea": spec("pack.overflow.excessArea", "overflow", "share", "lower", 0, 1, 0.005),
   "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1, 0.02, { floor: 0, tol: 0.02 }),
   "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity, 0.005, { floor: 0, tol: 0.005 }),
   "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity, 0.01, { floor: 0, tol: 0.01 }),
@@ -205,6 +219,8 @@ function traceSum(output: PackOutput, id: string): number {
  * - The time `pack.search.ms` comes from the trace. It is not part of the determinism rule.
  * - The overflow measures count each id once. `pack.overflow.forced` is the lower bound of `overflowBound`.
  * - `pack.overflow.excess` is the overflow less the forced overflow. A container with no fixed side gives 0 for both.
+ * - `pack.overflow.forcedArea` is a lower bound of the overflow area. `pack.overflow.excessArea` is the overflow area above it.
+ * - `pack.overflow.forcedAreaMin` is a deprecated alias of `pack.overflow.forcedArea`, with the same value.
  *
  * @example
  * ```ts
@@ -257,6 +273,8 @@ export function measure(input: PackInput, output: PackOutput, options: MeasureOp
     if (unplaced.has(item.id)) unplacedArea += a;
   }
   const bound = overflowBound(input);
+  const overflowArea = itemArea > 0 ? unplacedArea / itemArea : 0;
+  const forcedArea = itemArea > 0 ? Math.min(1, bound.area / itemArea) : 0;
 
   return {
     "pack.area": hullArea,
@@ -269,15 +287,29 @@ export function measure(input: PackInput, output: PackOutput, options: MeasureOp
     "pack.raggedness": hull.w > 0 ? spread / hull.w : 0,
     "pack.overflow": unplaced.size,
     "pack.overflow.rate": input.items.length > 0 ? unplaced.size / input.items.length : 0,
-    "pack.overflow.area": itemArea > 0 ? unplacedArea / itemArea : 0,
+    "pack.overflow.area": overflowArea,
     "pack.overflow.forced": bound.forced,
-    "pack.overflow.forcedArea": itemArea > 0 ? Math.min(1, bound.area / itemArea) : 0,
+    "pack.overflow.forcedArea": forcedArea,
     "pack.overflow.excess": Math.max(0, unplaced.size - bound.forced),
+    "pack.overflow.forcedAreaMin": forcedArea,
+    "pack.overflow.excessArea": excessAreaOf(overflowArea, forcedArea),
     "pack.search.widths": traceSum(output, "pack.search.widths"),
     "pack.search.ms": traceSum(output, "pack.search.ms"),
   };
 }
 
+/** The float noise of `pack.overflow.excessArea`. A difference below 0 by this value or less becomes 0. */
+const AREA_NOISE = 1e-9;
+
+/**
+ * This function gives the overflow area above its lower bound. A value from `-AREA_NOISE` to 0 becomes 0. A value below
+ * `-AREA_NOISE` stays, because it shows a bug of the bound or of the packer.
+ */
+function excessAreaOf(overflowArea: number, forcedArea: number): number {
+  const excess = overflowArea - forcedArea;
+  return excess < 0 && excess >= -AREA_NOISE ? 0 : excess;
+}
+
 /**
  * This function gives the stability measures of a change pair: the run on the base input and the run on the changed
  * input. The items match by id. The values are not rounded.

package/src/moves.ts

@@ -0,0 +1,47 @@
+// The counts of the characteristic move of each strategy (roadmap item k59, `docs/BENCH.md`, "Activation"). The
+// packers count their move here, and the adapters write the count in `trace.measures`. The counts do not change a layout.
+// The module is internal: the package root does not export it.
+
+/** The id of the characteristic move of each strategy and of each shelf fit. The trace of each strategy has its id, also with the count 0. */
+export const MOVES: Readonly<{
+  rows: "move.gapFill";
+  shelf: "move.stack";
+  skyline: "move.lowerWindow";
+  push: "move.cascade";
+  firstFit: "move.firstFit";
+  bestFit: "move.bestFit";
+}> = Object.freeze({
+  /** A rectangle that the gap fill of `packRow` places in a gap of a row: under a shorter neighbor, or at the row break. */
+  rows: "move.gapFill",
+  /**
+   * A rectangle that `packShelf` puts on an open shelf with a taller rectangle. The strip above it stays empty. With a
+   * `fit`, the move is a rectangle in the strip above a shorter rectangle of a shelf.
+   */
+  shelf: "move.stack",
+  /** A rectangle that the skyline puts in a lower window, not in the leftmost window where it fits. */
+  skyline: "move.lowerWindow",
+  /** A rectangle that a push cascade moves. */
+  push: "move.cascade",
+  /** A rectangle that a shelf fit puts on a shelf that is not the open shelf. The open shelf is the last shelf that the packing opened. */
+  firstFit: "move.firstFit",
+  /** A rectangle that the fit `best` puts on a shelf that is not the first shelf where it fits. */
+  bestFit: "move.bestFit",
+});
+
+const counts = new Map<string, number>();
+
+/** This function adds `n` to the count of a move. */
+export function countMove(id: string, n = 1): void {
+  if (n > 0) counts.set(id, (counts.get(id) ?? 0) + n);
+}
+
+/** This function sets the count of a move to 0. Without an id, it sets each count to 0. */
+export function clearMoves(id?: string): void {
+  if (id === undefined) counts.clear();
+  else counts.delete(id);
+}
+
+/** This function gives the count of a move since the last `clearMoves`. */
+export function moveCount(id: string): number {
+  return counts.get(id) ?? 0;
+}

package/src/pack.ts

@@ -1,6 +1,7 @@
+import { clearMoves, countMove, MOVES } from "./moves.ts";
 import { compareRects, type SortOrder } from "./order.ts";
 import { Rect } from "./rect.ts";
-import { packRowsInSpace, packShelf } from "./shelf.ts";
+import { packRowsInSpace, packShelf, type ShelfFit } from "./shelf.ts";
 import { packSkyline } from "./skyline.ts";
 import type { FreeSpace } from "./space.ts";
 import { Vector } from "./vector.ts";
@@ -23,12 +24,24 @@ export interface PackLayoutOptions extends PackOptions {
    * Use `shelf` with the sort order `input` to keep the order of the array around locked rectangles.
    */
   strategy?: "rows" | "skyline" | "shelf";
+  /** The rule of `shelf` to choose a shelf. Only `shelf` reads it. `ShelfOptions` tells it. Without it, `shelf` packs as in 0.2.3. */
+  fit?: ShelfFit;
 }
 
+/** The depth of the calls of `packInto`. Only the outer gap fill counts its rectangles as moves. */
+let fillDepth = 0;
+
 function packInto<T>(rects: Rect<T>[], region: Rect<T>, offset: Vector, order: SortOrder): void {
   const unpacked = Rect.unpacked(rects);
-  pack(unpacked, region, { sortOrder: order });
-  for (const r of Rect.packed(unpacked)) r.translateBy(offset);
+  fillDepth++;
+  try {
+    pack(unpacked, region, { sortOrder: order });
+  } finally {
+    fillDepth--;
+  }
+  const placed = Rect.packed(unpacked);
+  if (fillDepth === 0) countMove(MOVES.rows, placed.length);
+  for (const r of placed) r.translateBy(offset);
 }
 
 function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean {
@@ -100,7 +113,8 @@ export function packRows<T>(rects: Rect<T>[], outer: Rect<T>, options: PackOptio
   const space = options.space;
   if (space !== undefined && (!space.plain || rects.some((r) => r.locked))) return packRowsInSpace(rects, outer, order, space);
   for (const r of rects) if (r.locked) r.wasPacked = true;
-  while (!packRow(rects, outer, order));
+  // A row that does not fit grows the height and starts again, thus the gap fills of the try before do not count
+  while (!packRow(rects, outer, order)) if (fillDepth === 0) clearMoves(MOVES.rows);
   return outer;
 }
 

package/src/shelf.ts

@@ -1,7 +1,20 @@
+import { countMove, MOVES } from "./moves.ts";
 import { compareRects, type SortOrder } from "./order.ts";
 import type { Rect } from "./rect.ts";
 import { firstFit, type FreeSpace, type FreeSpan } from "./space.ts";
 
+/**
+ * The rule of a shelf packing to choose the shelf of a rectangle. `packShelf` tells each rule.
+ *
+ * - `next`: only the open shelf, the last shelf that the packing opened.
+ * - `first`: the first shelf from the top where the rectangle fits.
+ * - `best`: the shelf with the least height left over above the rectangle.
+ */
+export type ShelfFit = "next" | "first" | "best";
+
+/** This constant lists each shelf fit. */
+export const SHELF_FITS: readonly ShelfFit[] = ["next", "first", "best"];
+
 /** The options of `packShelf` */
 export interface ShelfOptions {
   /** The order of the rectangles before the packing. The default is `height-desc`. */
@@ -11,6 +24,11 @@ export interface ShelfOptions {
    * outer rectangle and the locked rectangles.
    */
   space?: FreeSpace;
+  /**
+   * The rule to choose a shelf. Without it, `packShelf` packs as in 0.2.3. With it, `packShelf` uses its own shelves in
+   * each container shape, and it stacks rectangles in the strips above the shorter rectangles.
+   */
+  fit?: ShelfFit;
 }
 
 /** An obstacle in the coordinates of the outer rectangle */
@@ -59,8 +77,10 @@ function nextTop(obstacles: readonly Box[], top: number, bottom: number): number
  * - It does not change the width. Without `fixedSize`, the height grows to the content. With `fixedSize`, a
  *   rectangle that does not fit is not packed: its `wasPacked` stays `false`.
  * - With a space that is not plain, `packRowsInSpace` packs the rows into the outline of the space and around its holes.
+ * - With `fit`, `packShelvesInSpace` packs the rectangles, in each container shape. A `fit` that is not in `SHELF_FITS` throws a `RangeError`.
  */
 export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOptions = {}): Rect<T> {
+  if (options.fit !== undefined) return packShelvesInSpace(rects, outer, options.sortOrder ?? "height-desc", options.fit, options.space);
   if (options.space !== undefined && !options.space.plain) return packRowsInSpace(rects, outer, options.sortOrder ?? "height-desc", options.space);
   const width = outer.size.x;
   const obstacles: Box[] = [];
@@ -111,6 +131,8 @@ export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOpt
 
     if (outer.fixedSize && rowTop + h > outer.size.y) continue;
 
+    // The move of a shelf: the rectangle joins an open shelf that a taller rectangle made
+    if (!rowEmpty && rowTop + h < rowBottom) countMove(MOVES.shelf);
     rect.position.set(x + outer.position.x, rowTop + outer.position.y);
     rect.wasPacked = true;
     rowEmpty = false;
@@ -226,3 +248,184 @@ export function packRowsInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: Sort
   if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, contentBottom);
   return outer;
 }
+
+/** A shelf of `packShelvesInSpace`, in the coordinates of the outer rectangle. */
+interface Shelf {
+  /** The top edge of the shelf. */
+  top: number;
+  /** The height of the shelf: the height of its first rectangle. Only the last shelf grows. */
+  height: number;
+  /** The x after the last rectangle on the floor of the shelf. The value `Infinity` closes the shelf. */
+  cursor: number;
+  /** The strips above the rectangles on the floor. A later rectangle stacks in a strip. */
+  strips: Strip[];
+}
+
+/** The free strip above a rectangle of a shelf: from `x` to `x + w`, and from `bottom` to the top edge of the next shelf. */
+interface Strip {
+  x: number;
+  w: number;
+  bottom: number;
+}
+
+/** A place for a rectangle on a shelf. `left` is the height of the shelf that stays free above the rectangle. */
+interface Spot {
+  shelf: Shelf;
+  x: number;
+  y: number;
+  left: number;
+  /** The strip of a stacked rectangle. A rectangle on the floor has no strip. */
+  strip?: Strip;
+  /** The value `true` when the rectangle is taller than the last shelf, and the shelf grows. */
+  grow?: boolean;
+}
+
+/**
+ * This function packs rectangles into shelves with a fit: `next`, `first` or `best`. `packShelf` uses it when its
+ * options have a `fit`. It sets the position of each rectangle and gives the outer rectangle.
+ *
+ * - A shelf opens at the bottom edge of the last shelf, at the first x where the rectangle fits in the free space.
+ *   When no x fits, the shelf steps down to `nextY` of the space, as an empty row of `packRowsInSpace` does.
+ * - The first rectangle of a shelf sets its height. A rectangle goes on the floor of a shelf at its cursor, or into
+ *   the strip above a shorter rectangle of the shelf. The strip is the move `move.stack`.
+ * - The fit `next` uses only the open shelf: the last shelf that the packing opened. The fit `first` uses the first
+ *   shelf from the top where the rectangle fits. The fit `best` uses the place with the least height left over.
+ * - In a shelf, the rectangle takes the place with the least height left over. A tie goes to a strip, from left to right.
+ * - When no shelf has a place, the last shelf grows for a taller rectangle, if it fits. Else a new shelf opens.
+ * - A rectangle wider than the outer rectangle overflows. Without `fixedSize`, it goes on a closed shelf of its own at the left edge.
+ * - Each place is in the free space and crosses no locked rectangle. Without a space, the outer rectangle and the
+ *   locked rectangles give the free space.
+ */
+function packShelvesInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder, fit: ShelfFit, space: FreeSpace | undefined): Rect<T> {
+  if (!SHELF_FITS.includes(fit)) throw new RangeError(`The shelf fit "${String(fit)}" is not one of ${SHELF_FITS.join(", ")}.`);
+  const width = outer.size.x;
+  const ox = outer.position.x;
+  const oy = outer.position.y;
+  const limit = outer.fixedSize ? outer.size.y : Infinity;
+  const obstacles: Box[] = [];
+  let contentBottom = 0;
+  for (const rect of rects) {
+    if (!rect.locked) continue;
+    rect.wasPacked = true;
+    const left = rect.position.x - ox;
+    const top = rect.position.y - oy;
+    obstacles.push({ left, top, right: left + rect.size.x, bottom: top + rect.size.y });
+    contentBottom = Math.max(contentBottom, top + rect.size.y);
+  }
+  const whole: readonly FreeSpan[] = [{ start: 0, end: Infinity }];
+  // The x in the band, in the coordinates of the outer rectangle, or Infinity
+  const place = (start: number, w: number, top: number, h: number): number => {
+    const spans = space === undefined ? whole : space.band(top + oy, top + h + oy).map((s) => ({ start: s.start - ox, end: s.end - ox }));
+    return placeInBand(obstacles, spans, start, w, top, top + h);
+  };
+  // The next top edge where the free spans change, or Infinity
+  const stepDown = (top: number, w: number, h: number): number =>
+    Math.min(space === undefined ? Infinity : space.nextY(top + oy, top + h + oy, w) - oy, nextTop(obstacles, top, top + h));
+
+  // The places of a shelf that the sizes allow, by the height left over. A strip comes before the floor on a tie.
+  const spotsOn = (shelf: Shelf, w: number, h: number, grow: boolean): Spot[] => {
+    const ceiling = shelf.top + shelf.height;
+    const spots: Spot[] = [];
+    if (!grow) {
+      for (const strip of shelf.strips) {
+        if (w <= strip.w && strip.bottom + h <= ceiling) spots.push({ shelf, x: strip.x, y: strip.bottom, left: ceiling - strip.bottom - h, strip });
+      }
+    }
+    const tall = grow ? h > shelf.height && shelf.top + h <= limit : h <= shelf.height;
+    if (Number.isFinite(shelf.cursor) && tall) spots.push({ shelf, x: shelf.cursor, y: shelf.top, left: grow ? 0 : shelf.height - h, ...(grow ? { grow } : {}) });
+    return spots.toSorted((a, b) => a.left - b.left);
+  };
+  // The place of a spot in the free space, or undefined. A rectangle on the floor can move right of the cursor.
+  const verify = (spot: Spot, w: number, h: number): Spot | undefined => {
+    const x = place(spot.x, w, spot.y, h);
+    if (spot.strip !== undefined) return x === spot.x ? spot : undefined;
+    return x + w <= width ? { ...spot, x } : undefined;
+  };
+  const firstOn = (shelf: Shelf, w: number, h: number): Spot | undefined => {
+    for (const spot of spotsOn(shelf, w, h, false)) {
+      const found = verify(spot, w, h);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+
+  const shelves: Shelf[] = [];
+  for (const rect of rects.toSorted(compareRects(order))) {
+    if (rect.wasPacked) continue;
+    const w = rect.size.x;
+    const h = rect.size.y;
+    if (!(w > 0 && h > 0)) continue;
+    const open = shelves.at(-1);
+    const floor = open === undefined ? 0 : open.top + open.height;
+
+    if (w > width) {
+      if (outer.fixedSize) continue;
+      // An overflowing rectangle goes on a closed shelf of its own, under the locked rectangles at the left edge
+      let top = floor;
+      while (firstFreeX(obstacles, 0, w, top, top + h) !== 0) {
+        const next = nextTop(obstacles, top, top + h);
+        if (!Number.isFinite(next)) break;
+        top = next;
+      }
+      rect.position.set(ox, top + oy);
+      rect.wasPacked = true;
+      shelves.push({ top, height: h, cursor: Infinity, strips: [] });
+      contentBottom = Math.max(contentBottom, top + h);
+      continue;
+    }
+
+    // Step 1: a shelf where the rectangle fits without growth
+    let spot: Spot | undefined;
+    let firstShelf: Shelf | undefined;
+    if (fit === "best") {
+      for (const s of shelves.flatMap((shelf) => spotsOn(shelf, w, h, false)).toSorted((a, b) => a.left - b.left)) {
+        spot = verify(s, w, h);
+        if (spot !== undefined) break;
+      }
+      if (spot !== undefined) firstShelf = shelves.find((shelf) => shelf === spot!.shelf || firstOn(shelf, w, h) !== undefined);
+    } else {
+      for (const shelf of fit === "next" ? shelves.slice(-1) : shelves) {
+        spot = firstOn(shelf, w, h);
+        if (spot !== undefined) break;
+      }
+    }
+    // Step 2: the last shelf grows. Step 3: a new shelf opens under the last shelf.
+    if (spot === undefined && open !== undefined) {
+      const grown = spotsOn(open, w, h, true)[0];
+      if (grown !== undefined) spot = verify(grown, w, h);
+    }
+    if (spot === undefined) {
+      let top = floor;
+      let x = place(0, w, top, h);
+      while (!(x + w <= width) && top + h <= limit) {
+        const next = stepDown(top, w, h);
+        if (!Number.isFinite(next)) break;
+        top = next;
+        x = place(0, w, top, h);
+      }
+      if (!(x + w <= width) || top + h > limit) continue;
+      const shelf: Shelf = { top, height: h, cursor: x, strips: [] };
+      shelves.push(shelf);
+      spot = { shelf, x, y: top, left: 0 };
+    } else {
+      if (spot.shelf !== open) countMove(MOVES.firstFit);
+      if (firstShelf !== undefined && spot.shelf !== firstShelf) countMove(MOVES.bestFit);
+    }
+
+    const { shelf } = spot;
+    rect.position.set(spot.x + ox, spot.y + oy);
+    rect.wasPacked = true;
+    if (spot.strip !== undefined) {
+      countMove(MOVES.shelf);
+      spot.strip.bottom = spot.y + h;
+    } else {
+      shelf.cursor = spot.x + w;
+      shelf.strips.push({ x: spot.x, w, bottom: spot.y + h });
+      if (spot.grow === true) shelf.height = h;
+    }
+    contentBottom = Math.max(contentBottom, spot.y + h);
+  }
+
+  if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, contentBottom);
+  return outer;
+}