@mark1russell7/layout-contract 0.2.12 → 0.2.14

package/src/input.ts

@@ -1,4 +1,5 @@
 import type { Margin, Region, Side } from "./geometry.ts";
+import type { ShapeKind } from "./shapes.ts";
 
 /**
  * A port of a box: a place where edges go into the box.
@@ -28,6 +29,11 @@ export interface LayoutBox {
   readonly group?: string;
   /** A region relative to the origin of the box. Without it, the box is the rectangle `w` by `h`. */
   readonly shape?: Region;
+  /**
+   * The shape kind of the box (`docs/SHAPES.md`). Without it, `shapeKindOf` gives the kind of `shape`, or `rect` without a shape.
+   * The kind `free` tells that the contract knows only the bounding box `w` by `h`.
+   */
+  readonly shapeKind?: ShapeKind;
   readonly ports?: readonly Port[];
   /** A ring around the box. No other box enters it. Only a route from a port of the box enters it, at a right angle. */
   readonly margin?: Margin;
@@ -80,6 +86,19 @@ export interface LayoutGenerator {
   readonly seed: number;
 }
 
+/**
+ * One minimum distance between two boxes (`a` and `b`). It replaces the two margins of the boxes for this pair, and the global `gap`.
+ * The order of `a` and `b` has no meaning. A pair without an entry keeps the margins and the `gap`.
+ */
+export interface PairGap {
+  readonly a: string;
+  readonly b: string;
+  /** The minimum distance between the two boxes, in units: a finite number of 0 or more. */
+  readonly gap: number;
+  /** The count of the channels that the gap has space for. It is information only: a whole number of 0 or more. */
+  readonly lanes?: number;
+}
+
 /** The cell of an input in the taxonomy: one value for each dimension. The dimensions are in `docs/FORMAT.md` of `packing`. */
 export interface LayoutCell {
   readonly containerSize?: "fixed" | "freeHeight" | "freeWidth" | "freeAspect" | "freeArea";
@@ -92,6 +111,8 @@ export interface LayoutCell {
   readonly edgeShape?: "random" | "clustered" | "hubChain" | "longRange" | "tree" | "bundled";
   readonly groups?: "none" | "flat" | "nested";
   readonly ports?: "free" | "sides" | "fixed";
+  /** The shape kinds of the boxes: one kind, or `mixed` for more kinds. Without it, each box is a `rect`. `itemShapeOf` gives the value. */
+  readonly itemShape?: ShapeKind | "mixed";
 }
 
 /** An input of the corpus: the format `layout-input/1`. */
@@ -116,6 +137,8 @@ export interface LayoutInput {
   readonly container?: LayoutContainer;
   /** The free space between two boxes with their margins. Routes use it. */
   readonly gap?: number;
+  /** The distances of some pairs of boxes. An entry replaces the margins and the `gap` for its pair. `canonicalInput` sorts the list. */
+  readonly pairGaps?: readonly PairGap[];
   readonly boxes: readonly LayoutBox[];
   readonly edges?: readonly LayoutEdge[];
   readonly obstacles?: readonly Obstacle[];
@@ -133,6 +156,7 @@ export interface PackInput {
   readonly items: readonly Item[];
   readonly obstacles?: readonly Obstacle[];
   readonly gap?: number;
+  readonly pairGaps?: readonly PairGap[];
 }
 
 /** This function gives the packer input of a file. An input without a container gets `{ fixed: "none" }`, so the packer picks the size. */
@@ -142,5 +166,22 @@ export function toPackInput(input: LayoutInput): PackInput {
     items: input.boxes,
     ...(input.obstacles === undefined ? {} : { obstacles: input.obstacles }),
     ...(input.gap === undefined ? {} : { gap: input.gap }),
+    ...(input.pairGaps === undefined ? {} : { pairGaps: input.pairGaps }),
   };
 }
+
+/** This function compares two strings by their UTF-16 code units, as `Array.prototype.sort` does without a compare function. */
+const byCode = (x: string, y: string): number => (x < y ? -1 : x > y ? 1 : 0);
+
+/**
+ * This function gives the canonical form of an input. `documentHash` uses it for each `layout-input/1` document.
+ * Each pair of `pairGaps` gets `a` before `b`, and the list is sorted by `a` and then by `b`.
+ * An input without `pairGaps` is the same object, so its hash does not change.
+ */
+export function canonicalInput<T extends LayoutInput>(input: T): T {
+  if (!Array.isArray(input.pairGaps)) return input;
+  const pairGaps = input.pairGaps
+    .map((p): PairGap => (byCode(p.a, p.b) > 0 ? { ...p, a: p.b, b: p.a } : p))
+    .sort((x, y) => byCode(x.a, y.a) || byCode(x.b, y.b));
+  return { ...input, pairGaps };
+}

package/src/measures.ts

@@ -1,3 +1,4 @@
+import { SHAPE_KIND_IDS, type ShapeKind } from "./shapes.ts";
 import { RECORD_EPS, RECORD_SCALE } from "./tolerance.ts";
 
 /** The direction of a measure: the side of the better values. */
@@ -29,6 +30,8 @@ export interface MeasureSpec<Id extends string = string> {
   readonly minEffect?: number | { readonly rel: number };
   /** The role of the measure in the joint selector. */
   readonly role?: "guard" | "change-guard" | "diagnostic" | "time";
+  /** The shape kinds of the boxes that the measure supports. Without it, the measure supports only `rect`. `checkShapes` refuses the other kinds. */
+  readonly shapes?: readonly ShapeKind[];
 }
 
 /** The id of a joint measure. `docs/JOINT-MEASURES.md` gives the definitions. */
@@ -43,17 +46,25 @@ export type JointMeasureId =
   | "joint.proxy.rank"
   | "joint.ms";
 
-/** The specs of the joint measures, in the order of `docs/JOINT-MEASURES.md`. */
+/** The shape kinds of a joint measure that reads only the bounding boxes, the centers and the positions of the boxes. */
+const BOUNDS_ONLY = SHAPE_KIND_IDS;
+/** The shape kinds of a joint measure that reads the area `w` by `h` of each box. */
+const AREA: readonly ShapeKind[] = ["rect"];
+
+/**
+ * The specs of the joint measures, in the order of `docs/JOINT-MEASURES.md`.
+ * `joint.fill` and `joint.straight.length` read the area of each box, so they support only `rect`. `docs/SHAPES.md` tells the reasons.
+ */
 export const JOINT_MEASURES: readonly MeasureSpec<JointMeasureId>[] = Object.freeze([
-  { id: "joint.fill", minEffect: 0.001, unit: "0 to 1", direction: "higher", min: 0, max: 1, floor: 1, role: "guard" },
-  { id: "joint.aspectError", minEffect: 0.01, unit: "natural log", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0.01, role: "guard" },
-  { id: "joint.spill", minEffect: 0.001, unit: "0 to 1", direction: "lower", min: 0, max: 1, floor: 0, tol: 0.001, role: "guard" },
-  { id: "joint.straight.crossings", minEffect: 0, unit: "count", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0, role: "guard" },
-  { id: "joint.straight.length", minEffect: 0.01, unit: "S for each edge", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0.01, role: "guard" },
-  { id: "joint.stability.mean", minEffect: 0.005, unit: "W", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0.005, role: "change-guard" },
-  { id: "joint.stability.moved", minEffect: 0.02, unit: "0 to 1", direction: "lower", min: 0, max: 1, floor: 0, tol: 0.02, role: "change-guard" },
-  { id: "joint.proxy.rank", unit: "-1 to 1", direction: "higher", min: -1, max: 1, role: "diagnostic" },
-  { id: "joint.ms", unit: "milliseconds", direction: "lower", min: 0, max: Infinity, role: "time" },
+  { id: "joint.fill", minEffect: 0.001, unit: "0 to 1", direction: "higher", min: 0, max: 1, floor: 1, role: "guard", shapes: AREA },
+  { id: "joint.aspectError", minEffect: 0.01, unit: "natural log", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0.01, role: "guard", shapes: BOUNDS_ONLY },
+  { id: "joint.spill", minEffect: 0.001, unit: "0 to 1", direction: "lower", min: 0, max: 1, floor: 0, tol: 0.001, role: "guard", shapes: BOUNDS_ONLY },
+  { id: "joint.straight.crossings", minEffect: 0, unit: "count", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0, role: "guard", shapes: BOUNDS_ONLY },
+  { id: "joint.straight.length", minEffect: 0.01, unit: "S for each edge", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0.01, role: "guard", shapes: AREA },
+  { id: "joint.stability.mean", minEffect: 0.005, unit: "W", direction: "lower", min: 0, max: Infinity, floor: 0, tol: 0.005, role: "change-guard", shapes: BOUNDS_ONLY },
+  { id: "joint.stability.moved", minEffect: 0.02, unit: "0 to 1", direction: "lower", min: 0, max: 1, floor: 0, tol: 0.02, role: "change-guard", shapes: BOUNDS_ONLY },
+  { id: "joint.proxy.rank", unit: "-1 to 1", direction: "higher", min: -1, max: 1, role: "diagnostic", shapes: BOUNDS_ONLY },
+  { id: "joint.ms", unit: "milliseconds", direction: "lower", min: 0, max: Infinity, role: "time", shapes: BOUNDS_ONLY },
 ] as const);
 
 /** The threshold of `joint.stability.moved`, in widths `W` of the base. */

package/src/record.ts

@@ -1,5 +1,6 @@
 import type { Tolerance } from "./tolerance.ts";
 import type { LayoutInput } from "./input.ts";
+import { shapeKindsOf, type ShapeKind } from "./shapes.ts";
 
 /** The stage of a record: the packer, the router, or both together. */
 export type Stage = "pack" | "route" | "joint";
@@ -21,6 +22,8 @@ export interface LayoutRecord {
   readonly seed: number;
   readonly nodes: number;
   readonly edges: number;
+  /** The shape kinds of the boxes of the input, in the order of `SHAPE_KINDS`. Without it, each box is a `rect`. */
+  readonly shapes?: readonly ShapeKind[];
   /** The value of each measure, by its name: `pack.*`, `route.*` or `joint.*`. */
   readonly measures: Readonly<Record<string, number>>;
   /** The count of the breaks of each hard rule. A good run has 0 for each rule. */
@@ -67,10 +70,15 @@ export interface RunEnv {
 }
 
 /** The facts of a run that the input does not give. */
-export type RunFacts = Omit<LayoutRecord, "schema" | "input" | "inputHash" | "set" | "nodes" | "edges">;
+export type RunFacts = Omit<LayoutRecord, "schema" | "input" | "inputHash" | "set" | "nodes" | "edges" | "shapes">;
 
-/** This function gives the record of a run. The input gives its id, its hash, its set and the counts of the nodes and the edges. */
+/**
+ * This function gives the record of a run. The input gives its id, its hash, its set and the counts of the nodes and the edges.
+ * The input also gives `shapes`. An input with only `rect` boxes gets no `shapes`, so its record does not change.
+ */
 export function toLayoutRecord(input: LayoutInput, run: RunFacts): LayoutRecord {
+  const shapes = shapeKindsOf(input);
+  const onlyRect = shapes.length === 0 || (shapes.length === 1 && shapes[0] === "rect");
   return {
     schema: "layout-record/1",
     ...run,
@@ -79,5 +87,6 @@ export function toLayoutRecord(input: LayoutInput, run: RunFacts): LayoutRecord
     set: input.set ?? "",
     nodes: input.boxes.length,
     edges: input.edges?.length ?? 0,
+    ...(onlyRect ? {} : { shapes }),
   };
 }

package/src/rules.ts

@@ -1,6 +1,7 @@
 import { boundsOf, grow, overlapOf, type Rect, type Region } from "./geometry.ts";
-import type { LayoutBox, LayoutInput, Obstacle } from "./input.ts";
+import type { LayoutBox, LayoutInput, Obstacle, PairGap } from "./input.ts";
 import { applyPack, type PackOutput } from "./output.ts";
+import { SHAPE_KIND_IDS, shapeKindProblem, type ShapeSupport } from "./shapes.ts";
 import { DEFAULT_TOLERANCE, EPS, RECORD_EPS } from "./tolerance.ts";
 
 /** This function gives the area of a placed box: its shape or its rectangle, at its position. A box without a position gives `undefined`. */
@@ -14,20 +15,52 @@ export function placedRect(box: LayoutBox): Rect | undefined {
 /**
  * This function counts the pairs of placed boxes whose insides, with their margins, overlap by more than `tolerance` on each axis.
  * A box with a shape counts as its bounding box. That area is larger, thus the count is safe.
+ *
+ * A pair of `pairGaps`, in either order, uses its `gap` in place of the two margins. One box grows by the gap, and the other box does not grow.
+ * Thus the pair breaks the rule only when the boxes are nearer than the gap on each axis. The other pairs do not change.
  */
-export function countOverlaps(boxes: readonly LayoutBox[], tolerance: number = DEFAULT_TOLERANCE.overlap): number {
-  const rects: Rect[] = [];
+export function countOverlaps(boxes: readonly LayoutBox[], tolerance: number = DEFAULT_TOLERANCE.overlap, pairGaps?: readonly PairGap[]): number {
+  if (pairGaps === undefined || pairGaps.length === 0) return marginOverlaps(boxes, tolerance, undefined);
+  const gaps = new Map<string, number>();
+  for (const p of pairGaps) {
+    const key = pairKey(p.a, p.b);
+    if (p.a !== p.b && !gaps.has(key)) gaps.set(key, p.gap);
+  }
+  const raw = new Map<string, Rect>();
+  for (const box of boxes) {
+    const r = placedRect(box);
+    if (r !== undefined && !raw.has(box.id)) raw.set(box.id, r);
+  }
+  let count = marginOverlaps(boxes, tolerance, gaps);
+  for (const [key, gap] of gaps) {
+    const [a, b] = JSON.parse(key) as [string, string];
+    const ra = raw.get(a);
+    const rb = raw.get(b);
+    if (ra === undefined || rb === undefined) continue;
+    const o = overlapOf(grow(ra, gap), rb);
+    if (o.x > tolerance && o.y > tolerance) count++;
+  }
+  return count;
+}
+
+/** This function gives the key of a pair of box ids, with the same key for each order. */
+const pairKey = (a: string, b: string): string => JSON.stringify(a < b ? [a, b] : [b, a]);
+
+/** This function counts the overlaps of the boxes with their margins. It skips the pairs of `skip`. Without `skip`, it is the rule of 0.2.13. */
+function marginOverlaps(boxes: readonly LayoutBox[], tolerance: number, skip: ReadonlyMap<string, number> | undefined): number {
+  const rects: { readonly id: string; readonly r: Rect }[] = [];
   for (const box of boxes) {
     const r = placedRect(box);
-    if (r !== undefined) rects.push(grow(r, box.margin));
+    if (r !== undefined) rects.push({ id: box.id, r: grow(r, box.margin) });
   }
-  rects.sort((a, b) => a.x - b.x);
+  rects.sort((a, b) => a.r.x - b.r.x);
   let count = 0;
   for (let i = 0; i < rects.length; i++) {
-    const a = rects[i]!;
+    const a = rects[i]!.r;
     for (let j = i + 1; j < rects.length; j++) {
-      const b = rects[j]!;
+      const b = rects[j]!.r;
       if (b.x >= a.x + a.w - tolerance) break;
+      if (skip !== undefined && skip.has(pairKey(rects[i]!.id, rects[j]!.id))) continue;
       const o = overlapOf(a, b);
       if (o.x > tolerance && o.y > tolerance) count++;
     }
@@ -96,6 +129,18 @@ export interface PackHard {
   readonly complete: number;
 }
 
+/**
+ * The hard rules of a pack, with the shape kinds that each rule supports.
+ * `no-overlap` and `in-container` test the bounding box of a shape. That count is exact only for a `rect`.
+ * `locked-kept` and `complete` read only the positions and the ids, so they support each kind.
+ */
+export const PACK_HARD_RULES: readonly ShapeSupport<keyof PackHard>[] = Object.freeze([
+  { id: "no-overlap", shapes: ["rect"] },
+  { id: "in-container", shapes: ["rect"] },
+  { id: "locked-kept", shapes: SHAPE_KIND_IDS },
+  { id: "complete", shapes: SHAPE_KIND_IDS },
+] as const);
+
 /** This function tells if the inside of `region` and the inside of `rect` have a common point. */
 export function regionHitsRect(region: Region, rect: Rect): boolean {
   if (rect.w <= 0 || rect.h <= 0) return false;
@@ -266,7 +311,8 @@ export function countObstacleHits(
 /**
  * This function gives the count of each hard rule of the output of a packer.
  * It applies the output with `applyPack`. Only the placed boxes and the locked boxes count for the overlaps and the container.
- * `no-overlap` counts the pairs of boxes and the pairs of a box and an obstacle.
+ * `no-overlap` counts the pairs of boxes and the pairs of a box and an obstacle. A pair of `pairGaps` uses its gap in place of the margins.
+ *
  * A locked box without a placement, or with a move of more than `RECORD_EPS`, breaks `locked-kept`.
  * A locked box without a position in the input is a bad input, not a break. `checkInput` finds it.
  * Another box without a placement that is not in `overflow` breaks `complete`.
@@ -295,7 +341,7 @@ export function packHard(input: LayoutInput, output: PackOutput, tolerance: numb
     }
   }
   return {
-    "no-overlap": countOverlaps(kept, tolerance) + countObstacleHits(kept, after.obstacles, tolerance),
+    "no-overlap": countOverlaps(kept, tolerance, input.pairGaps) + countObstacleHits(kept, after.obstacles, tolerance),
     "in-container": countOutside({ ...after, boxes: kept }, tolerance, options),
     "locked-kept": lockedMoved,
     complete: incomplete,
@@ -305,6 +351,7 @@ export function packHard(input: LayoutInput, output: PackOutput, tolerance: numb
 /**
  * This function gives the problems of an input file. An empty list tells that the file is good.
  * A problem is a bad input, not a break of a hard rule. Thus an engine refuses the input.
+ * In `pairGaps`, an unknown box, a pair of one box, a repeated pair in either order, a bad `gap` and bad `lanes` are problems.
  */
 export function checkInput(input: LayoutInput): readonly string[] {
   const problems: string[] = [];
@@ -314,10 +361,38 @@ export function checkInput(input: LayoutInput): readonly string[] {
     ids.add(box.id);
     if (!(box.w > 0 && box.h > 0 && Number.isFinite(box.w) && Number.isFinite(box.h))) problems.push(`box ${box.id}: the size is not positive and finite`);
     if (box.locked === true && (box.x === undefined || box.y === undefined)) problems.push(`box ${box.id}: a locked box has no position`);
+    const shape = shapeKindProblem(box);
+    if (shape !== undefined) problems.push(shape);
   }
   if (countPortsOffBorder(input.boxes) > 0) problems.push("a fixed port is not on the border of its box");
   for (const edge of input.edges ?? []) {
     if (!ids.has(edge.source) || !ids.has(edge.target)) problems.push(`edge ${edge.id}: a box of the edge is not in the input`);
   }
+  problems.push(...pairGapProblems(input.pairGaps, ids));
+  return problems;
+}
+
+/** This function gives the problems of the `pairGaps` of an input. `ids` has the ids of the boxes. */
+function pairGapProblems(pairGaps: LayoutInput["pairGaps"], ids: ReadonlySet<string>): string[] {
+  if (pairGaps === undefined) return [];
+  if (!Array.isArray(pairGaps)) return ["pairGaps: the value is not a list"];
+  const problems: string[] = [];
+  const seen = new Map<string, number>();
+  pairGaps.forEach((p: PairGap, i) => {
+    const at = `pair gap ${i} (${String(p?.a)}, ${String(p?.b)})`;
+    if (typeof p !== "object" || p === null || typeof p.a !== "string" || typeof p.b !== "string") {
+      problems.push(`pair gap ${i}: the entry has no string ids a and b`);
+      return;
+    }
+    for (const id of [p.a, p.b]) if (!ids.has(id)) problems.push(`${at}: the box ${id} is not in the input`);
+    if (p.a === p.b) problems.push(`${at}: the two ids are the same box`);
+    if (typeof p.gap !== "number" || !Number.isFinite(p.gap) || p.gap < 0) problems.push(`${at}: the gap ${String(p.gap)} is not a finite number of 0 or more`);
+    if (p.lanes !== undefined && (typeof p.lanes !== "number" || !Number.isInteger(p.lanes) || p.lanes < 0))
+      problems.push(`${at}: the lanes value ${String(p.lanes)} is not a whole number of 0 or more`);
+    const key = JSON.stringify(p.a < p.b ? [p.a, p.b] : [p.b, p.a]);
+    const first = seen.get(key);
+    if (first !== undefined) problems.push(`${at}: the pair is also pair gap ${first}`);
+    else seen.set(key, i);
+  });
   return problems;
 }

package/src/shapes.ts

@@ -0,0 +1,119 @@
+// The shape kinds of the items (`docs/SHAPES.md`): the declared set, the kind of a box and the check of the measures and rules on a run.
+import type { ClaimBreak } from "./corpus.ts";
+import type { Region } from "./geometry.ts";
+import type { LayoutBox, LayoutInput } from "./input.ts";
+
+/**
+ * The kind of the shape of an item. A box without `shape` and without `shapeKind` is a `rect`.
+ * The set is open: a later version can add a kind. A reader treats an unknown kind as a kind that it does not support.
+ */
+export type ShapeKind = "rect" | "polygon" | "circle" | "free";
+
+/** The geometry of a shape kind that this package gives. A `false` value tells that the kind declares the operation, but this package does not supply it. */
+export interface ShapeGeometry {
+  /** The bounding box: `boundsOf` and `placedRect`. */
+  readonly bounds: boolean;
+  /** The area of the shape. */
+  readonly area: boolean;
+  /** The test that the shape is inside a region: `rectInRegion` for a `rect`. */
+  readonly contains: boolean;
+  /** The test that two shapes overlap: `overlapOf` for two `rect` shapes. */
+  readonly overlap: boolean;
+}
+
+/** The facts of one shape kind: its fields, the kinds of `Region` that give it, and its geometry. */
+export interface ShapeKindSpec {
+  readonly id: ShapeKind;
+  /** The fields of the outline, relative to the top-left corner of the box. A name with `?` is optional. */
+  readonly fields: readonly string[];
+  /** The kinds of `LayoutBox.shape` that agree with this kind. */
+  readonly regions: readonly Region["kind"][];
+  readonly geometry: ShapeGeometry;
+}
+
+/** The declared shape kinds, in their order. Only `rect` has all of its geometry. The other kinds have their bounding box only. */
+export const SHAPE_KINDS: readonly ShapeKindSpec[] = Object.freeze([
+  { id: "rect", fields: ["w", "h"], regions: ["rect"], geometry: { bounds: true, area: true, contains: true, overlap: true } },
+  { id: "polygon", fields: ["points", "holes?"], regions: ["polygon"], geometry: { bounds: true, area: false, contains: false, overlap: false } },
+  { id: "circle", fields: ["cx", "cy", "r"], regions: ["circle"], geometry: { bounds: true, area: false, contains: false, overlap: false } },
+  { id: "free", fields: ["w", "h", "shape?"], regions: ["rect", "polygon", "circle", "ellipse"], geometry: { bounds: true, area: false, contains: false, overlap: false } },
+] as const);
+
+/** The ids of `SHAPE_KINDS`, in their order. */
+export const SHAPE_KIND_IDS: readonly ShapeKind[] = Object.freeze(SHAPE_KINDS.map((k) => k.id));
+
+/** The shape kinds of a measure or a rule without `shapes`. The contract measured only rectangles before L46. */
+export const DEFAULT_SHAPES: readonly ShapeKind[] = Object.freeze(["rect"] as const);
+
+/** A measure or a rule, with the shape kinds that it supports. Without `shapes`, it supports `DEFAULT_SHAPES`. */
+export interface ShapeSupport<Id extends string = string> {
+  readonly id: Id;
+  readonly shapes?: readonly ShapeKind[];
+}
+
+const REGION_KIND: Readonly<Record<Region["kind"], ShapeKind>> = { rect: "rect", polygon: "polygon", circle: "circle", ellipse: "free" };
+
+/** This function tells if a value is a declared shape kind. */
+export function isShapeKind(value: unknown): value is ShapeKind {
+  return typeof value === "string" && (SHAPE_KIND_IDS as readonly string[]).includes(value);
+}
+
+/**
+ * This function gives the shape kind of a box. A box with `shapeKind` has that kind.
+ * Without it, the kind comes from `shape`: no shape is a `rect`, and an ellipse is `free`.
+ */
+export function shapeKindOf(box: LayoutBox): ShapeKind {
+  if (box.shapeKind !== undefined) return box.shapeKind;
+  return box.shape === undefined ? "rect" : REGION_KIND[box.shape.kind];
+}
+
+/** This function gives the shape kinds of the boxes of an input, in the order of `SHAPE_KINDS`. An input without boxes gives an empty list. */
+export function shapeKindsOf(input: Pick<LayoutInput, "boxes">): ShapeKind[] {
+  const seen = new Set(input.boxes.map(shapeKindOf));
+  return SHAPE_KIND_IDS.filter((k) => seen.has(k));
+}
+
+/** This function gives the value of the cell dimension `itemShape` of an input: its one kind, `mixed` for more kinds, or `rect` without boxes. */
+export function itemShapeOf(input: Pick<LayoutInput, "boxes">): ShapeKind | "mixed" {
+  const kinds = shapeKindsOf(input);
+  return kinds.length === 0 ? "rect" : kinds.length === 1 ? kinds[0]! : "mixed";
+}
+
+/** This function gives the problem of the shape kind of a box, or `undefined` when `shapeKind` and `shape` agree. */
+export function shapeKindProblem(box: LayoutBox): string | undefined {
+  const k: unknown = box.shapeKind;
+  if (k === undefined) return undefined;
+  const spec = SHAPE_KINDS.find((s) => s.id === k);
+  if (spec === undefined) return `box ${box.id}: the shape kind ${String(k)} is not a declared kind`;
+  if (box.shape === undefined) return k === "rect" || k === "free" ? undefined : `box ${box.id}: the shape kind ${k} has no shape`;
+  if (!spec.regions.includes(box.shape.kind)) return `box ${box.id}: the shape kind ${k} does not agree with a shape of the kind ${box.shape.kind}`;
+  return undefined;
+}
+
+/** This function gives the shape kinds that a measure or a rule supports. */
+export function shapesOf(use: Pick<ShapeSupport, "shapes">): readonly ShapeKind[] {
+  return use.shapes ?? DEFAULT_SHAPES;
+}
+
+/**
+ * This function checks that each measure and each rule of a run supports each shape kind of the input. An empty list tells that the run is good.
+ * Each break has the claim `shape`, the id of the input, and the first 5 ids of the boxes of the kind.
+ */
+export function checkShapes(input: Pick<LayoutInput, "id" | "boxes">, uses: readonly ShapeSupport[]): ClaimBreak[] {
+  const kinds = shapeKindsOf(input);
+  const out: ClaimBreak[] = [];
+  for (const use of uses) {
+    const shapes = shapesOf(use);
+    for (const kind of kinds) {
+      if (shapes.includes(kind)) continue;
+      const ids = input.boxes.filter((b) => shapeKindOf(b) === kind).map((b) => b.id);
+      const shown = ids.slice(0, 5).join(", ") + (ids.length > 5 ? `, and ${ids.length - 5} more` : "");
+      out.push({
+        claim: "shape",
+        detail: `${use.id} supports only the shape kinds ${shapes.join(", ") || "(none)"}, but the input ${input.id} has ${kind} boxes: ${shown}`,
+        inputs: [input.id],
+      });
+    }
+  }
+  return out;
+}