@mark1russell7/packing 0.1.2 → 0.1.4

package/src/index.ts

@@ -7,3 +7,78 @@ export { packFree, aspectError, type FreeWidthOptions, type FreeWidthResult, typ
 export { compareRects, SORT_ORDERS, type SortOrder } from "./order.ts";
 export { pushCascade, type PushOptions } from "./push.ts";
 export { packingMetrics, type MetricsOptions, type PackingMetrics } from "./metrics.ts";
+export {
+  DEFAULT_TOLERANCE,
+  EPS,
+  RECORD_EPS,
+  marginOf,
+  turnItem,
+  turnPoint,
+  turnPort,
+  turnRegion,
+  type Container,
+  type Item,
+  type Margin,
+  type Obstacle,
+  type PackInput,
+  type PackOutput,
+  type Placement,
+  type Port,
+  type Region,
+  type StageTrace,
+  type Tolerance,
+} from "./contract.ts";
+export {
+  UnsupportedCell,
+  assertSupported,
+  cellOf,
+  createContext,
+  mulberry32,
+  supportsCell,
+  unsupportedOf,
+  type Cell,
+  type Dimension,
+  type DimensionValue,
+  type PackContext,
+  type SizeSearch,
+  type Strategy,
+  type Supports,
+} from "./strategy.ts";
+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 {
+  canonicalJson,
+  countCell,
+  fnv1a32,
+  hashInput,
+  round3,
+  toPackInput,
+  type CorpusCell,
+  type CountScale,
+  type Edge,
+  type GeneratorParams,
+  type GeneratorStamp,
+  type LayoutInput,
+  type ObstacleLayout,
+  type SizeDistribution,
+} from "./layout-input.ts";
+export {
+  cards,
+  dashboard,
+  edgeCases,
+  gallery,
+  generator,
+  generators,
+  rectGrid,
+  rectScattered,
+  wordCloud,
+  type CorpusGenerator,
+  type EdgeCase,
+  type EdgeCaseParams,
+  type RectGridParams,
+  type RectScatteredParams,
+  type UiParams,
+} from "./generators.ts";
+export { corpus, type Corpus, type CorpusEntry, type CorpusManifest, type CorpusSpec } from "./corpus.ts";

package/src/layout-input.ts

@@ -0,0 +1,120 @@
+// 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 { 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 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;
+}
+
+/** 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;
+  /** The origin: `made-up`, `published:<set>` or `known-best:<construction>`. */
+  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;
+  /** The first 16 hex characters of the SHA-256 of the canonical form of the other fields. */
+  hash: string;
+}
+
+/** The layout of the obstacles (`docs/research/TAXONOMY.md`, dimension 3). */
+export type ObstacleLayout = "none" | "center" | "scattered" | "wall" | "corridors" | "touching" | "edge";
+
+/** The distribution of the sizes of the items (`docs/research/TAXONOMY.md`, dimension 6). */
+export type SizeDistribution = "identical" | "nearIdentical" | "uniform" | "heavyTail" | "bimodal" | "extremeAspect";
+
+/** The scale of the count of the items (`docs/research/TAXONOMY.md`, dimension 7). */
+export type CountScale = "1" | "10" | "100" | "1k" | "10k";
+
+/**
+ * The cell of a generated input: one value for each dimension of the packer. The cell of `cellOf` has the dimensions
+ * that the input tells. The generator adds the layout of the obstacles, the sizes, the count and the mode.
+ */
+export interface CorpusCell extends Cell {
+  obstacles: ObstacleLayout;
+  sizes: SizeDistribution;
+  count: CountScale;
+  mode: "offline" | "online" | "incremental";
+}
+
+/** This function gives the `fnv1a32` hash of the UTF-8 bytes of a string, as `docs/FORMAT.md` gives it. */
+export function fnv1a32(text: string): number {
+  let h = 0x811c9dc5;
+  for (const b of utf8(text)) h = Math.imul(h ^ b, 0x01000193) >>> 0;
+  return h;
+}
+
+/** This function rounds the numbers of a file to 3 decimals. A half goes up, and the value `-0` becomes 0. */
+export function round3(x: number): number {
+  const v = Math.round(x * 1000) / 1000;
+  return Object.is(v, -0) ? 0 : v;
+}
+
+/**
+ * This function gives the canonical form of a value: sorted keys, no whitespace and the numbers of `JSON.stringify`
+ * after `round3`. A key with the value `undefined` is not in the form.
+ */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(typeof value === "number" ? round3(value) : value);
+}
+
+/** 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;
+  return sha256Hex(canonicalJson(rest)).slice(0, 16);
+}
+
+/** This function gives the scale of a count: the nearest of 1, 10, 100, 1000 and 10000 on a log scale. The count 0 gives `1`. */
+export function countCell(count: number): CountScale {
+  if (count <= 3) return "1";
+  if (count <= 31) return "10";
+  if (count <= 316) return "100";
+  if (count <= 3162) return "1k";
+  return "10k";
+}
+
+/** This function gives the packing input of a file. The boxes become the items, and the edges go. */
+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;
+}

package/src/pack.ts

@@ -70,7 +70,8 @@ function packRow<T>(rects: Rect<T>[], outer: Rect<T>, order: SortOrder): boolean
     if (fillGaps && row.length > 1) {
       const rectInRow = row[row.length - 1]!;
       const outerLeft = new Rect<T>();
-      outerLeft.position.set(rectInRow.position.x, rectInRow.bottom());
+      // The position of the region is relative to the outer rectangle, as packInto adds the position of the outer rectangle
+      outerLeft.position.set(rectInRow.position.x - outer.position.x, rectInRow.bottom() - outer.position.y);
       outerLeft.size.set(rectInRow.size.x, rowRect.size.y - rectInRow.size.y);
       outerLeft.fixedWidth = true;
       outerLeft.fixedSize = true;

package/src/registry.ts

@@ -0,0 +1,23 @@
+import { push, rows, shelf, skyline } from "./adapters.ts";
+import type { PackInput, PackOutput } from "./contract.ts";
+import { createContext, type Strategy } from "./strategy.ts";
+
+/** Each strategy of the package. The benchmark starts each one on each input of the corpus. */
+export const strategies: readonly Strategy[] = Object.freeze([rows, skyline, shelf, push] as Strategy[]);
+
+/** This function gives the strategy with an id. It throws a `RangeError` for an id that the registry does not have. */
+export function strategy(id: string): Strategy {
+  const found = strategies.find((s) => s.id === id);
+  if (found === undefined) throw new RangeError(`The registry has no strategy "${id}".`);
+  return found;
+}
+
+/**
+ * This function packs an input with the strategy of an id. The options go over the defaults of the strategy. The
+ * context gets `mulberry32` with the seed. The default seed is 0.
+ */
+export function packWith(id: string, input: PackInput, options?: unknown, seed = 0): PackOutput {
+  const s = strategy(id);
+  const merged: unknown = { ...(s.defaults as object), ...(options as object | undefined) };
+  return s.pack(input, merged, createContext(seed));
+}

package/src/sha256.ts

@@ -0,0 +1,93 @@
+// SHA-256 (FIPS 180-4) in plain TypeScript. The hash of a corpus file needs it, and a browser has no synchronous SHA-256.
+
+/** The round constants of SHA-256. */
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be,
+  0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa,
+  0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85,
+  0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f,
+  0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+/** The first hash value of SHA-256. */
+const H0 = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+
+/** This function turns a 32-bit word to the right by `n` bits. */
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+/**
+ * This function gives the UTF-8 bytes of a string. A lone surrogate becomes U+FFFD, as with `TextEncoder`. The
+ * package has no `TextEncoder` type, because its code operates on each runtime with no global types.
+ */
+export function utf8(text: string): Uint8Array {
+  const out: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    let c = text.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        c = 0x10000 + ((c - 0xd800) << 10) + (next - 0xdc00);
+        i++;
+      }
+    }
+    if (c >= 0xd800 && c <= 0xdfff) c = 0xfffd;
+    if (c < 0x80) out.push(c);
+    else if (c < 0x800) out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+    else if (c < 0x10000) out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    else out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+  }
+  return Uint8Array.from(out);
+}
+
+/** This function gives the SHA-256 of the UTF-8 bytes of a string, as 64 lowercase hex characters. */
+export function sha256Hex(text: string): string {
+  const bytes = utf8(text);
+  const length = bytes.length;
+  const padded = new Uint8Array((((length + 9 + 63) / 64) | 0) * 64);
+  padded.set(bytes);
+  padded[length] = 0x80;
+  const view = new DataView(padded.buffer);
+  const bits = length * 8;
+  view.setUint32(padded.length - 8, Math.floor(bits / 0x100000000));
+  view.setUint32(padded.length - 4, bits >>> 0);
+
+  const hash = [...H0];
+  const w = new Uint32Array(64);
+  for (let block = 0; block < padded.length; block += 64) {
+    for (let t = 0; t < 16; t++) w[t] = view.getUint32(block + t * 4);
+    for (let t = 16; t < 64; t++) {
+      const a = w[t - 15]!;
+      const b = w[t - 2]!;
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[t] = (w[t - 16]! + s0 + w[t - 7]! + s1) | 0;
+    }
+    let [a, b, c, d, e, f, g, h] = hash as [number, number, number, number, number, number, number, number];
+    for (let t = 0; t < 64; t++) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (h + s1 + ch + K[t]! + w[t]!) | 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (s0 + maj) | 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + t1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) | 0;
+    }
+    hash[0] = (hash[0]! + a) | 0;
+    hash[1] = (hash[1]! + b) | 0;
+    hash[2] = (hash[2]! + c) | 0;
+    hash[3] = (hash[3]! + d) | 0;
+    hash[4] = (hash[4]! + e) | 0;
+    hash[5] = (hash[5]! + f) | 0;
+    hash[6] = (hash[6]! + g) | 0;
+    hash[7] = (hash[7]! + h) | 0;
+  }
+  return hash.map((x) => (x >>> 0).toString(16).padStart(8, "0")).join("");
+}

package/src/strategy.ts

@@ -0,0 +1,214 @@
+import type { Container, PackInput, PackOutput, Region } from "./contract.ts";
+
+/** For each dimension of the taxonomy, the values that a strategy supports. `docs/research/TAXONOMY.md` gives the values. */
+export interface Supports {
+  containerSize: ("fixed" | "freeHeight" | "freeWidth" | "freeAspect" | "freeArea")[];
+  containerShape: ("rect" | "convex" | "polygon" | "circle" | "ellipse" | "holes")[];
+  /** The movement of the obstacles. An empty list supports only an input with no obstacle and no locked item. */
+  obstacleMove: ("fixed" | "costly" | "free")[];
+  itemShape: ("rect" | "circle" | "convex" | "polygon" | "mixed")[];
+  rotation: ("none" | "quarter" | "any")[];
+  order: ("free" | "soft" | "hard")[];
+  groups: ("none" | "flat" | "nested")[];
+  mode: ("offline" | "online" | "incremental")[];
+}
+
+/** A dimension of `Supports`. */
+export type Dimension = keyof Supports;
+
+/** A value of a dimension of `Supports`. */
+export type DimensionValue<D extends Dimension = Dimension> = Supports[D][number];
+
+/**
+ * The cell of an input: one value for each packer dimension that the input tells. The input does not tell the mode.
+ * Without obstacles and locked items, the cell has no `obstacleMove`.
+ */
+export interface Cell {
+  containerSize: DimensionValue<"containerSize">;
+  containerShape: DimensionValue<"containerShape">;
+  obstacleMove?: DimensionValue<"obstacleMove">;
+  itemShape: DimensionValue<"itemShape">;
+  rotation: DimensionValue<"rotation">;
+  order: DimensionValue<"order">;
+  groups: DimensionValue<"groups">;
+}
+
+/** The context of one packing. */
+export interface PackContext {
+  /** The seed. A strategy gets each random number from `rng`, not from `Math.random`. */
+  seed: number;
+  /** The random numbers in `[0, 1)`, from `mulberry32` with `seed`. */
+  rng: () => number;
+  /** A limit for the strategies that search. The strategy gives its best result at the limit. */
+  budget?: { ms?: number; steps?: number };
+  /** The previous output, for the mode `incremental`. */
+  previous?: PackOutput;
+}
+
+/** A packing strategy behind the Packer interface. */
+export interface Strategy<O = unknown> {
+  /** A stable name, for example `shelf`. The records use it. */
+  id: string;
+  /** The family of the catalog, for example `shelf` or `skyline`. */
+  family: string;
+  /** The ids of the catalog rows that this strategy builds. */
+  catalog: string[];
+  /** The cells that the strategy supports. */
+  supports: Supports;
+  /** The default options. A record writes the options in full. */
+  defaults: O;
+  /** The value `true` tells that the result depends only on the input, the options and the seed. */
+  deterministic: boolean;
+  /** This method packs an input. It throws `UnsupportedCell` for an input outside the cells of `supports`. */
+  pack(input: PackInput, options: O, context: PackContext): PackOutput;
+}
+
+/** A size search: it gives a strategy of a fixed width the cells `freeAspect` and `freeArea`. */
+export interface SizeSearch {
+  id: string;
+  /** This method searches the size of the container for an input with `fixed` set to `none`. `options` go to `inner`. */
+  search(input: PackInput, inner: Strategy, context: PackContext, options?: unknown): PackOutput;
+}
+
+/**
+ * The error of a strategy for an input outside its cells. The benchmark records this result. It is not a failure of the
+ * strategy.
+ */
+export class UnsupportedCell extends Error {
+  /** The dimension of the taxonomy. */
+  readonly dimension: Dimension;
+  /** The value of the input that the strategy does not support. */
+  readonly value: string;
+
+  constructor(dimension: Dimension, value: string) {
+    super(`The strategy does not support the value "${value}" of the dimension "${dimension}".`);
+    this.name = "UnsupportedCell";
+    this.dimension = dimension;
+    this.value = value;
+  }
+}
+
+/** This function gives a generator of random numbers in `[0, 1)`: `mulberry32` of `docs/FORMAT.md`. */
+export function mulberry32(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** This function makes the context of one packing from a seed. */
+export function createContext(seed = 0, more: Omit<PackContext, "seed" | "rng"> = {}): PackContext {
+  return { ...more, seed, rng: mulberry32(seed) };
+}
+
+/** This function tells if a polygon ring is convex. A ring with fewer than 3 points is convex. */
+function isConvex(points: readonly [number, number][]): boolean {
+  let sign = 0;
+  const n = points.length;
+  for (let i = 0; i < n; i++) {
+    const [ax, ay] = points[i]!;
+    const [bx, by] = points[(i + 1) % n]!;
+    const [cx, cy] = points[(i + 2) % n]!;
+    const cross = (bx - ax) * (cy - by) - (by - ay) * (cx - bx);
+    if (cross === 0) continue;
+    if (sign === 0) sign = Math.sign(cross);
+    else if (Math.sign(cross) !== sign) return false;
+  }
+  return true;
+}
+
+/** This function gives the value of `containerShape` of one region. */
+function shapeOf(region: Region): DimensionValue<"containerShape"> {
+  switch (region.kind) {
+    case "rect":
+    case "circle":
+    case "ellipse":
+      return region.kind;
+    case "polygon":
+      if (region.holes && region.holes.length > 0) return "holes";
+      return isConvex(region.points) ? "convex" : "polygon";
+  }
+}
+
+/** This function gives the value of `itemShape` of one item shape. An ellipse is convex. */
+function itemShapeOf(region: Region | undefined): DimensionValue<"itemShape"> {
+  if (region === undefined) return "rect";
+  switch (region.kind) {
+    case "rect":
+    case "circle":
+      return region.kind;
+    case "ellipse":
+      return "convex";
+    case "polygon":
+      return !region.holes?.length && isConvex(region.points) ? "convex" : "polygon";
+  }
+}
+
+/**
+ * This function gives the cell of an input: the values of the packer dimensions that the input tells.
+ *
+ * - `containerSize` comes from `fixed`. The value `none` gives `freeArea` when `aspectWeight` is 0, and `freeAspect` if not.
+ * - `containerShape` comes from the shape. A rectangle container with an obstacle of another region gives `holes`.
+ * - `obstacleMove` is the hardest value of the obstacles and the locked items: `costly`, then `free`, then `fixed`.
+ * - `order` is `soft` when an item has a rank, and `free` if not. The input does not tell a hard order.
+ * - `groups` is `nested` when an item has a parent, `flat` when an item has a group, and `none` if not.
+ */
+export function cellOf(input: PackInput): Cell {
+  const { container, items } = input;
+  const obstacles = input.obstacles ?? [];
+
+  const sizes: Record<Container["fixed"], DimensionValue<"containerSize">> = {
+    size: "fixed",
+    width: "freeHeight",
+    height: "freeWidth",
+    none: container.aspectWeight === 0 ? "freeArea" : "freeAspect",
+  };
+  const containerSize = sizes[container.fixed];
+
+  let containerShape = container.shape ? shapeOf(container.shape) : "rect";
+  if (containerShape === "rect" && obstacles.some((o) => o.region.kind !== "rect")) containerShape = "holes";
+
+  let obstacleMove: DimensionValue<"obstacleMove"> | undefined = items.some((i) => i.locked === true) ? "fixed" : undefined;
+  for (const o of obstacles) {
+    const move = o.move === undefined ? "fixed" : o.move.cost > 0 ? "costly" : "free";
+    if (move === "costly" || obstacleMove === undefined || (move === "free" && obstacleMove === "fixed")) obstacleMove = move;
+  }
+
+  const shapes = new Set(items.map((i) => itemShapeOf(i.shape)));
+  const itemShape = shapes.size > 1 ? "mixed" : ([...shapes][0] ?? "rect");
+
+  const cell: Cell = {
+    containerSize,
+    containerShape,
+    itemShape,
+    rotation: items.some((i) => i.turnable === true) ? "quarter" : "none",
+    order: items.some((i) => i.rank !== undefined) ? "soft" : "free",
+    groups: items.some((i) => i.parent !== undefined) ? "nested" : items.some((i) => i.group !== undefined) ? "flat" : "none",
+  };
+  if (obstacleMove !== undefined) cell.obstacleMove = obstacleMove;
+  return cell;
+}
+
+/** This function gives the first dimension of a cell that `supports` does not hold, or `undefined` when it holds each one. */
+export function unsupportedOf(supports: Supports, cell: Partial<Record<Dimension, string>>): { dimension: Dimension; value: string } | undefined {
+  for (const dimension of Object.keys(supports) as Dimension[]) {
+    const value = cell[dimension];
+    if (value === undefined) continue;
+    if (!(supports[dimension] as readonly string[]).includes(value)) return { dimension, value };
+  }
+  return undefined;
+}
+
+/** This function tells if `supports` holds each value of a cell. A dimension that the cell does not have is held. */
+export function supportsCell(supports: Supports, cell: Partial<Record<Dimension, string>>): boolean {
+  return unsupportedOf(supports, cell) === undefined;
+}
+
+/** This function throws `UnsupportedCell` for the first value of the cell of an input that `supports` does not hold. */
+export function assertSupported(supports: Supports, input: PackInput): void {
+  const miss = unsupportedOf(supports, cellOf(input));
+  if (miss) throw new UnsupportedCell(miss.dimension, miss.value);
+}