@mark1russell7/packing 0.1.7 → 0.2.1

package/src/frame.ts

@@ -2,6 +2,7 @@
 // Each item grows by its margin and by half the gap on each side. Each obstacle grows by half the gap. Thus two items
 // are `mA + gap + mB` apart. The area of the frame is the container less the inset, grown by half the gap on each side.
 
+import { boundsOf } from "@mark1russell7/layout-contract";
 import { EPS, marginOf, type Item, type Obstacle, type PackInput, type PackOutput, type Placement, type Region, type StageTrace } from "./contract.ts";
 import { Rect } from "./rect.ts";
 
@@ -12,24 +13,8 @@ export function now(): number {
   return clock ? clock.now() : Date.now();
 }
 
-/** This function gives the bounding box of a region. */
-export function boundsOf(region: Region): { x: number; y: number; w: number; h: number } {
-  switch (region.kind) {
-    case "rect":
-      return { x: region.x, y: region.y, w: region.w, h: region.h };
-    case "circle":
-      return { x: region.cx - region.r, y: region.cy - region.r, w: 2 * region.r, h: 2 * region.r };
-    case "ellipse":
-      return { x: region.cx - region.rx, y: region.cy - region.ry, w: 2 * region.rx, h: 2 * region.ry };
-    case "polygon": {
-      const xs = region.points.map((p) => p[0]);
-      const ys = region.points.map((p) => p[1]);
-      const x = Math.min(...xs);
-      const y = Math.min(...ys);
-      return { x, y, w: Math.max(...xs) - x, h: Math.max(...ys) - y };
-    }
-  }
-}
+/** The bounding box of a region comes from the contract. */
+export { boundsOf } from "@mark1russell7/layout-contract";
 
 /** The rectangle of a container: its origin and its size. A free side has the size `Infinity`. */
 export interface Bounds {
@@ -147,7 +132,7 @@ export function rectsOf(frame: Frame): Rect<number>[] {
  * This function reads the output from the rectangles of a frame after a packing of 0.1. A locked item keeps its
  * position exactly. Each other item that the packer did not place goes to the overflow.
  */
-export function readFrame(input: PackInput, frame: Frame, trace: StageTrace[], moved: PackOutput["moved"] = []): PackOutput {
+export function readFrame(input: PackInput, frame: Frame, trace: readonly StageTrace[], moved: PackOutput["moved"] = []): PackOutput {
   const placements: Placement[] = [];
   const overflow: string[] = [...frame.tooLarge];
   for (const e of frame.entries) {
@@ -197,44 +182,48 @@ export function transposeRegion(region: Region): Region {
     case "ellipse":
       return { kind: "ellipse", cx: region.cy, cy: region.cx, rx: region.ry, ry: region.rx };
     case "polygon": {
-      const swap = (ring: [number, number][]): [number, number][] => ring.map(([x, y]) => [y, x]);
-      const turned: Region = { kind: "polygon", points: swap(region.points) };
-      if (region.holes) turned.holes = region.holes.map(swap);
-      return turned;
+      const swap = (ring: readonly (readonly [number, number])[]): [number, number][] => ring.map(([x, y]) => [y, x]);
+      return region.holes === undefined
+        ? { kind: "polygon", points: swap(region.points) }
+        : { kind: "polygon", points: swap(region.points), holes: region.holes.map(swap) };
     }
   }
 }
 
 /** This function gives an item with the axes changed. The ports go, because the adapters of 0.1 do not read them. */
 function transposeItem(item: Item): Item {
-  const { ports: _ports, ...rest } = item;
-  const turned: Item = { ...rest, w: item.h, h: item.w };
-  delete turned.x;
-  delete turned.y;
-  if (item.y !== undefined) turned.x = item.y;
-  if (item.x !== undefined) turned.y = item.x;
-  if (item.shape) turned.shape = transposeRegion(item.shape);
-  if (item.margin !== undefined && typeof item.margin !== "number") {
-    const m = item.margin;
-    turned.margin = { top: m.left, right: m.bottom, bottom: m.right, left: m.top };
-  }
-  return turned;
+  const { ports: _ports, x, y, shape, margin, ...rest } = item;
+  return {
+    ...rest,
+    w: item.h,
+    h: item.w,
+    ...(y === undefined ? {} : { x: y }),
+    ...(x === undefined ? {} : { y: x }),
+    ...(shape === undefined ? {} : { shape: transposeRegion(shape) }),
+    ...(margin === undefined
+      ? {}
+      : { margin: typeof margin === "number" ? margin : { top: margin.left, right: margin.bottom, bottom: margin.right, left: margin.top } }),
+  };
 }
 
 /** This function gives an input with the axes changed. A fixed height becomes a fixed width. */
 export function transposeInput(input: PackInput): PackInput {
   const c = input.container;
-  const container: PackInput["container"] = { fixed: c.fixed === "height" ? "width" : c.fixed === "width" ? "height" : c.fixed };
-  if (c.h !== undefined) container.w = c.h;
-  if (c.w !== undefined) container.h = c.w;
-  if (c.aspect !== undefined) container.aspect = 1 / c.aspect;
-  if (c.aspectWeight !== undefined) container.aspectWeight = c.aspectWeight;
-  if (c.shape !== undefined) container.shape = transposeRegion(c.shape);
-  if (c.inset !== undefined) container.inset = c.inset;
-  const turned: PackInput = { container, items: input.items.map(transposeItem) };
-  if (input.obstacles) turned.obstacles = input.obstacles.map((o) => ({ ...o, region: transposeRegion(o.region) }));
-  if (input.gap !== undefined) turned.gap = input.gap;
-  return turned;
+  const container: PackInput["container"] = {
+    fixed: c.fixed === "height" ? "width" : c.fixed === "width" ? "height" : c.fixed,
+    ...(c.h === undefined ? {} : { w: c.h }),
+    ...(c.w === undefined ? {} : { h: c.w }),
+    ...(c.aspect === undefined ? {} : { aspect: 1 / c.aspect }),
+    ...(c.aspectWeight === undefined ? {} : { aspectWeight: c.aspectWeight }),
+    ...(c.shape === undefined ? {} : { shape: transposeRegion(c.shape) }),
+    ...(c.inset === undefined ? {} : { inset: c.inset }),
+  };
+  return {
+    container,
+    items: input.items.map(transposeItem),
+    ...(input.obstacles === undefined ? {} : { obstacles: input.obstacles.map((o) => ({ ...o, region: transposeRegion(o.region) })) }),
+    ...(input.gap === undefined ? {} : { gap: input.gap }),
+  };
 }
 
 /** This function gives an output with the axes changed. */
@@ -244,7 +233,7 @@ export function transposeOutput(output: PackOutput): PackOutput {
     overflow: [...output.overflow],
     size: { w: output.size.h, h: output.size.w },
     moved: output.moved.map((m) => ({ id: m.id, x: m.y, y: m.x })),
-    trace: output.trace,
+    ...(output.trace === undefined ? {} : { trace: output.trace }),
   };
 }
 
@@ -256,7 +245,5 @@ export function viaAxes(input: PackInput, previous: PackOutput | undefined, run:
   const start = now();
   const turned = transposeInput(input);
   const inner = run(turned, previous === undefined ? undefined : transposeOutput(previous));
-  const output = transposeOutput(inner);
-  output.trace = [{ id: "axes", ms: now() - start, measures: {} }, ...inner.trace];
-  return output;
+  return { ...transposeOutput(inner), trace: [{ id: "axes", ms: now() - start, measures: {} }, ...(inner.trace ?? [])] };
 }

package/src/generators.ts

@@ -2,7 +2,7 @@
 // container, then the obstacles, then the boxes. Each step has its own random numbers: `mulberry32` of
 // `fnv1a32("<seed>:<step>")`. Thus a packing input and a routing input with the same seed get the same obstacles.
 
-import type { Container, Item, Obstacle, Region } from "./contract.ts";
+import type { Item, LayoutContainer, Obstacle, Region } from "./contract.ts";
 import {
   countCell,
   fnv1a32,
@@ -10,7 +10,7 @@ import {
   round3,
   type CorpusCell,
   type GeneratorParams,
-  type LayoutInput,
+  type GeneratedInput,
   type ObstacleLayout,
   type SizeDistribution,
 } from "./layout-input.ts";
@@ -36,11 +36,11 @@ export interface CorpusGenerator<P extends GeneratorParams = GeneratorParams> {
   /** This method gives the cell of each input of the parameters. The cell does not depend on the seed. */
   cell(params?: Partial<P>): CorpusCell;
   /** This method gives the input file of a seed. The `id` is `<set>/<family>/s<seed>`. */
-  generate(seed: number, params?: Partial<P>, set?: string): LayoutInput;
+  generate(seed: number, params?: Partial<P>, set?: string): GeneratedInput;
 }
 
 /** The parts of a file that a generator makes. */
-type Parts = Pick<LayoutInput, "container" | "boxes"> & { obstacles: Obstacle[] };
+type Parts = Pick<GeneratedInput, "container" | "boxes"> & { obstacles: Obstacle[] };
 
 /** The data of a generator, before `defineGenerator` adds the common steps. */
 interface GeneratorSpec<P extends GeneratorParams> {
@@ -153,12 +153,12 @@ function defineGenerator<P extends GeneratorParams>(spec: GeneratorSpec<P>): Cor
     values: spec.values,
     withDefaults,
     cell: (params?: Partial<P>): CorpusCell => spec.cell(withDefaults(params)),
-    generate(seed: number, params?: Partial<P>, set: string = spec.set): LayoutInput {
+    generate(seed: number, params?: Partial<P>, set: string = spec.set): GeneratedInput {
       if (!Number.isInteger(seed) || seed < 0) throw new RangeError(`The seed is a whole number from 0. It is ${seed}.`);
       const full = withDefaults(params);
       const family = spec.family(full);
       const { container, obstacles, boxes } = spec.build(seed, full);
-      const file: Omit<LayoutInput, "hash"> = roundNumbers({
+      const file: Omit<GeneratedInput, "hash"> = roundNumbers({
         schema: "layout-input/1" as const,
         id: `${set}/${family}/s${seed}`,
         set,
@@ -195,7 +195,7 @@ export const rectScattered: CorpusGenerator<RectScatteredParams> = defineGenerat
     let r = stepRandom(seed, "container");
     const w = int(r, 600, 1000);
     const h = int(r, 400, 800);
-    const container: Container = { w, h, fixed: "size" };
+    const container: LayoutContainer = { w, h, fixed: "size" };
 
     r = stepRandom(seed, "obstacles");
     const n = int(r, 3, 8);
@@ -232,8 +232,8 @@ const OBSTACLE_LAYOUTS = ["none", "center", "scattered", "wall", "corridors", "t
 const SIZE_DISTRIBUTIONS = ["identical", "nearIdentical", "uniform", "heavyTail", "bimodal", "extremeAspect"] as const;
 
 /** This function gives the container of a size value for the nominal rectangle `w` by `h`, with an optional shape. */
-function containerOf(size: DimensionValue<"containerSize">, w: number, h: number, shape?: Region): Container {
-  const containers: Record<DimensionValue<"containerSize">, Container> = {
+function containerOf(size: DimensionValue<"containerSize">, w: number, h: number, shape?: Region): LayoutContainer {
+  const containers: Record<DimensionValue<"containerSize">, LayoutContainer> = {
     fixed: { w, h, fixed: "size" },
     freeHeight: { w, fixed: "width" },
     freeWidth: { h, fixed: "height" },
@@ -241,8 +241,7 @@ function containerOf(size: DimensionValue<"containerSize">, w: number, h: number
     freeArea: { fixed: "none", aspectWeight: 0 },
   };
   const container = containers[size];
-  if (shape !== undefined) container.shape = shape;
-  return container;
+  return shape === undefined ? container : { ...container, shape };
 }
 
 /** This function gives the 4 corners of a rectangle, clockwise from the top left. */
@@ -625,7 +624,7 @@ export const edgeCases: CorpusGenerator<EdgeCaseParams> = defineGenerator<EdgeCa
       w = int(r, 600, 1000);
       h = int(r, 400, 800);
     }
-    const container: Container = { w, h, fixed: "size" };
+    const container: LayoutContainer = { w, h, fixed: "size" };
 
     r = stepRandom(seed, "obstacles");
     const obstacles: Obstacle[] = [];

package/src/index.ts

@@ -1,7 +1,8 @@
 export { Vector } from "./vector.ts";
 export { Rect } from "./rect.ts";
 export { pack, packRows, type PackOptions, type PackLayoutOptions } from "./pack.ts";
-export { packSkyline, lowestWindow } from "./skyline.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 { packFree, aspectError, type FreeWidthOptions, type FreeWidthResult, type FreeWidthTry } from "./free.ts";
 export { compareRects, SORT_ORDERS, type SortOrder } from "./order.ts";
@@ -29,13 +30,14 @@ export {
   DEFAULT_TOLERANCE,
   EPS,
   RECORD_EPS,
+  checkInput,
   marginOf,
   turnItem,
   turnPoint,
   turnPort,
   turnRegion,
-  type Container,
   type Item,
+  type LayoutContainer,
   type Margin,
   type Obstacle,
   type PackInput,
@@ -43,6 +45,8 @@ export {
   type Placement,
   type Port,
   type Region,
+  type Side,
+  type Sides,
   type StageTrace,
   type Tolerance,
 } from "./contract.ts";
@@ -65,7 +69,7 @@ export {
 export { logSweep, push, rows, shelf, skyline, type LayoutStrategyOptions, type PushStrategyOptions } from "./adapters.ts";
 export { fromRects, toRects } from "./convert.ts";
 export { packWith, strategies, strategy } from "./registry.ts";
-export { checkHard, type HardBreaks } from "./check.ts";
+export { checkHard, type PackHard } from "./check.ts";
 export {
   canonicalJson,
   countCell,
@@ -75,9 +79,10 @@ export {
   toPackInput,
   type CorpusCell,
   type CountScale,
-  type Edge,
+  type GeneratedInput,
   type GeneratorParams,
   type GeneratorStamp,
+  type LayoutEdge,
   type LayoutInput,
   type ObstacleLayout,
   type SizeDistribution,

package/src/layout-input.ts

@@ -1,52 +1,39 @@
 // The input file `layout-input/1` of `docs/FORMAT.md`: its types, its numbers, its canonical form and its hash.
 
-import type { Container, Item, Obstacle, PackInput } from "./contract.ts";
+import type { LayoutContainer, LayoutEdge, LayoutGenerator, LayoutInput } from "@mark1russell7/layout-contract";
+import type { PackInput } from "./contract.ts";
 import { sha256Hex, utf8 } from "./sha256.ts";
 import type { Cell } from "./strategy.ts";
 
-/** An edge between two boxes. The router reads it, and the packer ignores it. */
-export interface Edge {
-  id: string;
-  source: string;
-  target: string;
-  sourcePort?: string;
-  targetPort?: string;
-  /** The free data of the edge. The packer does not read it. */
-  data?: Readonly<Record<string, unknown>>;
-}
+export type { LayoutEdge, LayoutInput } from "@mark1russell7/layout-contract";
 
 /** The parameters of a generator: a name and a string or a number for each parameter. */
 export type GeneratorParams = Record<string, string | number>;
 
-/** The stamp of a generated input: the generator, its version, the full parameters and the seed. */
-export interface GeneratorStamp {
-  name: string;
-  version: number;
-  params: GeneratorParams;
-  seed: number;
+/**
+ * The stamp of a generated input: the generator, its version, the full parameters and the seed.
+ * It is `LayoutGenerator` of the contract with a string or a number for each parameter.
+ */
+export interface GeneratorStamp extends LayoutGenerator {
+  readonly params: Readonly<GeneratorParams>;
 }
 
-/** One input file `layout-input/1`. `docs/FORMAT.md` gives each field. */
-export interface LayoutInput {
-  schema: "layout-input/1";
-  id: string;
-  set: string;
-  family: string;
-  seed: number;
+/**
+ * A generated input file `layout-input/1`. It is a `LayoutInput` with each field that a generator writes.
+ * `docs/FORMAT.md` gives each field.
+ */
+export interface GeneratedInput extends LayoutInput {
+  readonly set: string;
+  readonly family: string;
+  readonly seed: number;
   /** The origin: `made-up`, `published:<set>` or `known-best:<construction>`. */
-  source: string;
+  readonly source: string;
   /** The generator of a generated input. A hand-made or published input has `null`. */
-  generator: GeneratorStamp | null;
-  container: Container;
-  obstacles?: Obstacle[];
-  gap?: number;
-  boxes: Item[];
-  edges: Edge[];
-  base?: string;
-  change?: string;
-  step?: number;
+  readonly generator: GeneratorStamp | null;
+  readonly container: LayoutContainer;
+  readonly edges: readonly LayoutEdge[];
   /** The first 16 hex characters of the SHA-256 of the canonical form of the other fields. */
-  hash: string;
+  readonly hash: string;
 }
 
 /** The layout of the obstacles (`docs/research/TAXONOMY.md`, dimension 3). */
@@ -98,9 +85,8 @@ export function canonicalJson(value: unknown): string {
 }
 
 /** This function gives the hash of an input file: the first 16 hex characters of the SHA-256 of its canonical form without `hash`. */
-export function hashInput(file: Omit<LayoutInput, "hash"> | LayoutInput): string {
-  const rest: Partial<LayoutInput> = { ...file };
-  delete rest.hash;
+export function hashInput(file: LayoutInput): string {
+  const { hash: _hash, ...rest } = file;
   return sha256Hex(canonicalJson(rest)).slice(0, 16);
 }
 
@@ -113,10 +99,15 @@ export function countCell(count: number): CountScale {
   return "10k";
 }
 
-/** This function gives the packing input of a file. The boxes become the items, and the edges go. */
+/**
+ * This function gives the packing input of a file. The boxes become the items, and the edges go.
+ * A file without a container gets `{ fixed: "none" }`, so the packer picks the size. It is `toPackInput` of the contract.
+ */
 export function toPackInput(file: Pick<LayoutInput, "container" | "boxes" | "obstacles" | "gap">): PackInput {
-  const input: PackInput = { container: file.container, items: file.boxes };
-  if (file.obstacles !== undefined) input.obstacles = file.obstacles;
-  if (file.gap !== undefined) input.gap = file.gap;
-  return input;
+  return {
+    container: file.container ?? { fixed: "none" },
+    items: file.boxes,
+    ...(file.obstacles === undefined ? {} : { obstacles: file.obstacles }),
+    ...(file.gap === undefined ? {} : { gap: file.gap }),
+  };
 }

package/src/measures.ts

@@ -1,11 +1,12 @@
 // The algebra of measures (roadmap item k8). `docs/MEASURES.md` defines each measure. This file computes them.
 
+import type { MeasureSpec as ContractMeasureSpec, Direction } from "@mark1russell7/layout-contract";
 import { RECORD_EPS, type PackInput, type PackOutput } from "./contract.ts";
 import { aspectError } from "./free.ts";
 import { round3 } from "./layout-input.ts";
 
-/** The direction of a measure: `lower` when a lower value is better, `higher` when a higher value is better. */
-export type Direction = "lower" | "higher";
+/** The direction of a measure comes from the contract: `lower` when a lower value is better, `higher` when a higher value is better. */
+export type { Direction } from "@mark1russell7/layout-contract";
 
 /** The family of a measure. Each family has a section in `docs/MEASURES.md`. */
 export type MeasureFamily = "density" | "aspect" | "order" | "raggedness" | "overflow" | "stability" | "determinism" | "speed";
@@ -13,21 +14,17 @@ export type MeasureFamily = "density" | "aspect" | "order" | "raggedness" | "ove
 /** 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.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. */
-export interface MeasureSpec {
-  id: MeasureId;
-  family: MeasureFamily;
-  unit: string;
-  direction: Direction;
-  /** The lowest value. */
-  min: number;
-  /** The highest value. The value `Infinity` tells that the measure has no upper limit. */
-  max: number;
+/**
+ * The facts of one measure: its family, its unit, its direction and its range.
+ * It is `MeasureSpec` of the contract for a packer measure id, with a family.
+ */
+export interface MeasureSpec extends ContractMeasureSpec<MeasureId> {
+  readonly family: MeasureFamily;
   /**
    * The floor is the best value of a guard measure. The floor rule of `docs/PROMOTION.md` of `highways` reads it. Each
    * guard of the packer has the floor 0. A measure without a floor has no floor rule.
    */
-  floor?: number;
+  readonly floor?: number;
   /**
    * The tolerance is the absolute tolerance at the floor. A candidate within the tolerance ties with a default at the floor.
    *
@@ -36,7 +33,7 @@ export interface MeasureSpec {
    * - `pack.stability.mean` has 0.005 container widths, and `pack.stability.q95` has 0.01. The default often moves no item.
    * - `pack.stability.moved` has 0.02: 2% of the items that stay. On a small change, the default often moves no item.
    */
-  tol?: number;
+  readonly tol?: number;
 }
 
 /** The measures of one layout, by id. `measure` gives them. The values are not rounded. */
@@ -175,7 +172,7 @@ export function readsBefore(a: Pick<Box, "x" | "y" | "h">, b: Pick<Box, "x" | "y
 /** This function sums one measure over the stages of a trace. A trace without the measure gives 0. */
 function traceSum(output: PackOutput, id: string): number {
   let sum = 0;
-  for (const stage of output.trace) sum += stage.measures[id] ?? 0;
+  for (const stage of output.trace ?? []) sum += stage.measures?.[id] ?? 0;
   return sum;
 }
 

package/src/pack.ts

@@ -1,13 +1,19 @@
 import { compareRects, type SortOrder } from "./order.ts";
 import { Rect } from "./rect.ts";
-import { packShelf } from "./shelf.ts";
+import { packRowsInSpace, packShelf } from "./shelf.ts";
 import { packSkyline } from "./skyline.ts";
+import type { FreeSpace } from "./space.ts";
 import { Vector } from "./vector.ts";
 
 /** The options of `pack` and `packRows` */
 export interface PackOptions {
   /** The order of the rectangles before the packing. The default is `height-desc`. */
   sortOrder?: SortOrder;
+  /**
+   * The free space of the container: `freeSpace` of the input. With a space that is not plain, each strategy packs into
+   * the outline of the container and around its holes. The rows of `packRows` also go around the locked rectangles.
+   */
+  space?: FreeSpace;
 }
 
 /** The options of `pack` */
@@ -85,9 +91,14 @@ function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean
  * This function packs rectangles into an outer rectangle of a given width with a guillotine row packing. It does
  * not change the width. Without `fixedSize`, the height grows until all rectangles fit. A `locked` rectangle keeps
  * its position, but the rows do not go around it. `pack` sets the width first and then uses this function.
+ *
+ * With `options.space`, the rows go around the locked rectangles and the holes of the space, inside its outline. A space
+ * that is plain, with no locked rectangle, gives the rows of 0.1.
  */
 export function packRows<T>(rects: Rect<T>[], outer: Rect<T>, options: PackOptions = {}): Rect<T> {
   const order = options.sortOrder ?? "height-desc";
+  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));
   return outer;

package/src/shelf.ts

@@ -1,10 +1,16 @@
 import { compareRects, type SortOrder } from "./order.ts";
 import type { Rect } from "./rect.ts";
+import { firstFit, type FreeSpace, type FreeSpan } from "./space.ts";
 
 /** The options of `packShelf` */
 export interface ShelfOptions {
   /** The order of the rectangles before the packing. The default is `height-desc`. */
   sortOrder?: SortOrder;
+  /**
+   * The free space of the container: `freeSpace` of the input. Without it, or when it is plain, the packer uses only the
+   * outer rectangle and the locked rectangles.
+   */
+  space?: FreeSpace;
 }
 
 /** An obstacle in the coordinates of the outer rectangle */
@@ -52,8 +58,10 @@ function nextTop(obstacles: readonly Box[], top: number, bottom: number): number
  * - A rectangle wider than the outer rectangle goes on its own row, at the left edge, and overflows.
  * - 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.
  */
 export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOptions = {}): Rect<T> {
+  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[] = [];
   let contentBottom = 0;
@@ -119,3 +127,102 @@ export function packShelf<T>(rects: Rect<T>[], outer: Rect<T>, options: ShelfOpt
   if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, contentBottom);
   return outer;
 }
+
+/**
+ * This function gives the first x from `start` where a rectangle of width `w` fits. There, it crosses no locked rectangle,
+ * and it is in a free span of its band. It takes `firstFreeX` and `firstFit` in turn until they agree. It gives `Infinity` when no x fits.
+ */
+function placeInBand(obstacles: readonly Box[], spans: readonly FreeSpan[], start: number, w: number, top: number, bottom: number): number {
+  let x = start;
+  for (;;) {
+    const free = firstFreeX(obstacles, x, w, top, bottom);
+    const fit = firstFit(spans, free, w);
+    if (fit === free || !Number.isFinite(fit)) return fit;
+    x = fit;
+  }
+}
+
+/**
+ * This function packs rectangles into rows inside a free space. `packShelf` and `packRows` use it when the space is not
+ * plain. It sets the position of each rectangle and gives the outer rectangle.
+ *
+ * - A rectangle goes to the first x from the row cursor where it fits in the space and crosses no locked rectangle.
+ * - When it does not fit, a new row starts under the current row. An empty row steps down to `nextY` of the space.
+ * - When the steps of an empty row find no place, the row goes back to its last top edge. Later rectangles can use it.
+ * - A rectangle wider than the outer rectangle overflows. Without `fixedSize`, it goes on its own row at the left edge.
+ */
+export function packRowsInSpace<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder, space: FreeSpace): Rect<T> {
+  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);
+  }
+  // The x in the row, in the coordinates of the outer rectangle, or Infinity
+  const place = (start: number, w: number, top: number, h: number): number => {
+    const spans = 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);
+  };
+
+  let rowTop = 0;
+  let rowBottom = 0;
+  let cursor = 0;
+  let rowEmpty = true;
+  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;
+    if (w > width) {
+      if (outer.fixedSize) continue;
+      const top = rowEmpty ? rowTop : rowBottom;
+      rect.position.set(ox, top + oy);
+      rect.wasPacked = true;
+      rowTop = top + h;
+      rowBottom = rowTop;
+      cursor = 0;
+      rowEmpty = true;
+      contentBottom = Math.max(contentBottom, top + h);
+      continue;
+    }
+
+    let x = place(cursor, w, rowTop, h);
+    if (!(x + w <= width) && !rowEmpty) {
+      rowTop = rowBottom;
+      cursor = 0;
+      rowEmpty = true;
+      x = place(0, w, rowTop, h);
+    }
+    // The steps of an empty row. They stay only when the rectangle finds a place.
+    let top = rowTop;
+    while (!(x + w <= width) && top + h <= limit) {
+      const next = Math.min(space.nextY(top + oy, top + h + oy, w) - oy, nextTop(obstacles, top, top + h));
+      if (!Number.isFinite(next)) break;
+      top = next;
+      x = place(0, w, top, h);
+    }
+    if (!(x + w <= width) || top + h > limit) continue;
+    if (top !== rowTop) {
+      rowTop = top;
+      rowBottom = top;
+    }
+
+    rect.position.set(x + ox, rowTop + oy);
+    rect.wasPacked = true;
+    rowEmpty = false;
+    cursor = x + w;
+    rowBottom = Math.max(rowBottom, rowTop + h);
+    contentBottom = Math.max(contentBottom, rowTop + h);
+  }
+
+  if (!outer.fixedSize) outer.size.y = Math.max(outer.size.y, contentBottom);
+  return outer;
+}