@mark1russell7/packing 0.1.3 → 0.1.5

package/src/index.ts

@@ -7,6 +7,24 @@ 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 {
+  MEASURE_SPECS,
+  isDeterministic,
+  measure,
+  measureChange,
+  medianRatio,
+  pairedRatio,
+  quantile,
+  roundMeasures,
+  tailShare,
+  type ChangeMeasures,
+  type Direction,
+  type LayoutMeasures,
+  type MeasureFamily,
+  type MeasureId,
+  type MeasureOptions,
+  type MeasureSpec,
+} from "./measures.ts";
 export {
   DEFAULT_TOLERANCE,
   EPS,
@@ -48,3 +66,37 @@ export { logSweep, push, rows, shelf, skyline, type LayoutStrategyOptions, type
 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/measures.ts

@@ -0,0 +1,363 @@
+// The algebra of measures (roadmap item k8). `docs/MEASURES.md` defines each measure. This file computes them.
+
+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 family of a measure. Each family has a section in `docs/MEASURES.md`. */
+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.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 measures of one layout, by id. `measure` gives them. The values are not rounded. */
+export interface LayoutMeasures {
+  "pack.area": number;
+  "pack.fill": number;
+  "pack.whitespace": number;
+  "pack.aspect": number;
+  "pack.aspectError": number;
+  "pack.order.inversions": number;
+  "pack.order.breaks": number;
+  "pack.raggedness": number;
+  "pack.overflow": number;
+  "pack.search.widths": number;
+  "pack.search.ms": number;
+}
+
+/** The stability measures of a change pair, by id. `measureChange` gives them. The values are not rounded. */
+export interface ChangeMeasures {
+  "pack.stability.moved": number;
+  "pack.stability.mean": number;
+  "pack.stability.q95": number;
+}
+
+/** The options of `measure`. */
+export interface MeasureOptions {
+  /**
+   * A box joins a row when its top is this close to the top of the first box of the row. The rows give
+   * `pack.raggedness`. The default is half the median height of the boxes.
+   */
+  rowTolerance?: number;
+}
+
+const spec = (id: MeasureId, family: MeasureFamily, unit: string, direction: Direction, min: number, max: number): MeasureSpec => ({
+  id,
+  family,
+  unit,
+  direction,
+  min,
+  max,
+});
+
+/** The facts of each measure, by id. `docs/MEASURES.md` gives the full definitions. */
+export const MEASURE_SPECS: Readonly<Record<MeasureId, MeasureSpec>> = Object.freeze({
+  "pack.area": spec("pack.area", "density", "square units", "lower", 0, Infinity),
+  "pack.fill": spec("pack.fill", "density", "share", "higher", 0, 1),
+  "pack.whitespace": spec("pack.whitespace", "density", "share", "lower", 0, 1),
+  "pack.aspect": spec("pack.aspect", "aspect", "ratio", "lower", 1, Infinity),
+  "pack.aspectError": spec("pack.aspectError", "aspect", "natural log", "lower", 0, Infinity),
+  "pack.order.inversions": spec("pack.order.inversions", "order", "share", "lower", 0, 1),
+  "pack.order.breaks": spec("pack.order.breaks", "order", "count", "lower", 0, Infinity),
+  "pack.raggedness": spec("pack.raggedness", "raggedness", "share", "lower", 0, 1),
+  "pack.overflow": spec("pack.overflow", "overflow", "count", "lower", 0, Infinity),
+  "pack.stability.moved": spec("pack.stability.moved", "stability", "share", "lower", 0, 1),
+  "pack.stability.mean": spec("pack.stability.mean", "stability", "container widths", "lower", 0, Infinity),
+  "pack.stability.q95": spec("pack.stability.q95", "stability", "container widths", "lower", 0, Infinity),
+  "pack.deterministic": spec("pack.deterministic", "determinism", "boolean", "higher", 0, 1),
+  "pack.search.widths": spec("pack.search.widths", "speed", "count", "lower", 0, Infinity),
+  "pack.search.ms": spec("pack.search.ms", "speed", "milliseconds", "lower", 0, Infinity),
+});
+
+/** A placed box: the rectangle of an item at its position, with its rank. */
+export interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  rank: number;
+}
+
+/** This function gives the smallest rectangle around the boxes. No box gives a rectangle of size 0 at 0, 0. */
+export function hullOf(boxes: readonly Pick<Box, "x" | "y" | "w" | "h">[]): { x: number; y: number; w: number; h: number } {
+  if (boxes.length === 0) return { x: 0, y: 0, w: 0, h: 0 };
+  let left = Infinity;
+  let top = Infinity;
+  let right = -Infinity;
+  let bottom = -Infinity;
+  for (const b of boxes) {
+    left = Math.min(left, b.x);
+    top = Math.min(top, b.y);
+    right = Math.max(right, b.x + b.w);
+    bottom = Math.max(bottom, b.y + b.h);
+  }
+  return { x: left, y: top, w: right - left, h: bottom - top };
+}
+
+/**
+ * This function puts the boxes in rows. It sorts the boxes by their top, and keeps the order of the list for equal tops.
+ * A box joins the last row when its top is within `tolerance` of the top of the first box of that row.
+ */
+export function rowsOf(boxes: readonly Pick<Box, "x" | "y" | "w">[], tolerance: number): { top: number; right: number; count: number }[] {
+  const rows: { top: number; right: number; count: number }[] = [];
+  for (const b of boxes.toSorted((p, q) => p.y - q.y)) {
+    const row = rows.at(-1);
+    if (row && Math.abs(b.y - row.top) <= tolerance) {
+      row.right = Math.max(row.right, b.x + b.w);
+      row.count += 1;
+    } else {
+      rows.push({ top: b.y, right: b.x + b.w, count: 1 });
+    }
+  }
+  return rows;
+}
+
+/**
+ * This function gives the placed boxes of an output, in the order of the items of the input. A box has the size of its
+ * item after the turn. The list has no item without a placement, and no item with a width or a height of 0.
+ */
+export function boxesOf(input: PackInput, output: PackOutput): Box[] {
+  const placements = new Map<string, PackOutput["placements"][number]>();
+  for (const p of output.placements) if (!placements.has(p.id)) placements.set(p.id, p);
+  const boxes: Box[] = [];
+  for (const [index, item] of input.items.entries()) {
+    const p = placements.get(item.id);
+    if (p === undefined || !(item.w > 0 && item.h > 0)) continue;
+    const turned = p.turn === 90;
+    boxes.push({ x: p.x, y: p.y, w: turned ? item.h : item.w, h: turned ? item.w : item.h, rank: item.rank ?? index });
+  }
+  return boxes;
+}
+
+/**
+ * This function tells if box `a` comes before box `b` in the reading order. Two boxes whose heights overlap by more than
+ * `RECORD_EPS` are on one line, and the left box comes first. Otherwise the upper box comes first.
+ */
+export function readsBefore(a: Pick<Box, "x" | "y" | "h">, b: Pick<Box, "x" | "y" | "h">): boolean {
+  const shared = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+  if (shared > RECORD_EPS) return a.x + RECORD_EPS < b.x;
+  return a.y < b.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;
+  return sum;
+}
+
+/**
+ * This function gives the measures of one layout, by the ids of `docs/MEASURES.md`. The values are not rounded. A
+ * record rounds them with `roundMeasures`.
+ *
+ * - The boxes are the placed items with a width and a height above 0. The hull is the smallest rectangle around them.
+ * - An empty layout gives the area 0, the aspect 1 and the aspect error 0. Its fill is 0 and its whitespace is 1.
+ * - The time `pack.search.ms` comes from the trace. It is not part of the determinism rule.
+ *
+ * @example
+ * ```ts
+ * const m = measure(input, packWith("shelf", input));
+ * m["pack.fill"]; // the area of the boxes divided by the area of the hull
+ * ```
+ */
+export function measure(input: PackInput, output: PackOutput, options: MeasureOptions = {}): LayoutMeasures {
+  const boxes = boxesOf(input, output);
+  const hull = hullOf(boxes);
+  const hullArea = hull.w * hull.h;
+  const boxArea = boxes.reduce((sum, b) => sum + b.w * b.h, 0);
+  const fill = hullArea > 0 ? boxArea / hullArea : 0;
+  const empty = boxes.length === 0;
+  const target = input.container.aspect ?? 1;
+
+  // The reading order: each pair of boxes with different ranks, and each step of the rank order
+  let pairs = 0;
+  let inversions = 0;
+  for (let i = 0; i < boxes.length; i++) {
+    for (let j = i + 1; j < boxes.length; j++) {
+      const a = boxes[i]!;
+      const b = boxes[j]!;
+      if (a.rank === b.rank) continue;
+      pairs += 1;
+      const first = a.rank < b.rank ? a : b;
+      const second = first === a ? b : a;
+      if (readsBefore(second, first)) inversions += 1;
+    }
+  }
+  const byRank = boxes.toSorted((a, b) => a.rank - b.rank);
+  let breaks = 0;
+  for (let k = 1; k < byRank.length; k++) {
+    const prev = byRank[k - 1]!;
+    const next = byRank[k]!;
+    if (prev.rank !== next.rank && readsBefore(next, prev)) breaks += 1;
+  }
+
+  const tolerance = options.rowTolerance ?? quantileOrZero(boxes.map((b) => b.h), 0.5) / 2;
+  const rights = rowsOf(boxes, tolerance).map((r) => r.right);
+  const spread = rights.length > 0 ? Math.max(...rights) - Math.min(...rights) : 0;
+
+  return {
+    "pack.area": hullArea,
+    "pack.fill": fill,
+    "pack.whitespace": 1 - fill,
+    "pack.aspect": empty ? 1 : Math.max(hull.w / hull.h, hull.h / hull.w),
+    "pack.aspectError": empty ? 0 : aspectError(hull.w, hull.h, target),
+    "pack.order.inversions": pairs > 0 ? inversions / pairs : 0,
+    "pack.order.breaks": breaks,
+    "pack.raggedness": hull.w > 0 ? spread / hull.w : 0,
+    "pack.overflow": new Set(output.overflow).size,
+    "pack.search.widths": traceSum(output, "pack.search.widths"),
+    "pack.search.ms": traceSum(output, "pack.search.ms"),
+  };
+}
+
+/**
+ * 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.
+ *
+ * - An item stays when both inputs have it and both outputs place it. The added and the removed items do not count.
+ * - A staying item moved when its `x` or its `y` changed by more than `RECORD_EPS`, or when its turn changed.
+ * - The distance of an item is the length of the move of its top-left corner. The unit is the width `W`.
+ * - `W` is the larger width of the 2 output sizes. A `W` of 0 becomes 1, so the unit is then the unit of the input.
+ * - No staying item gives 0 for each measure.
+ */
+export function measureChange(baseInput: PackInput, baseOutput: PackOutput, changeInput: PackInput, changeOutput: PackOutput): ChangeMeasures {
+  const placed = (input: PackInput, output: PackOutput): Map<string, PackOutput["placements"][number]> => {
+    const ids = new Set(input.items.map((i) => i.id));
+    const map = new Map<string, PackOutput["placements"][number]>();
+    for (const p of output.placements) if (ids.has(p.id) && !map.has(p.id)) map.set(p.id, p);
+    return map;
+  };
+  const before = placed(baseInput, baseOutput);
+  const after = placed(changeInput, changeOutput);
+  const width = Math.max(baseOutput.size.w, changeOutput.size.w);
+  const unit = width > 0 ? width : 1;
+
+  const distances: number[] = [];
+  let moved = 0;
+  for (const [id, p] of before) {
+    const q = after.get(id);
+    if (q === undefined) continue;
+    const dx = q.x - p.x;
+    const dy = q.y - p.y;
+    if (Math.abs(dx) > RECORD_EPS || Math.abs(dy) > RECORD_EPS || (p.turn ?? 0) !== (q.turn ?? 0)) moved += 1;
+    distances.push(Math.hypot(dx, dy) / unit);
+  }
+  if (distances.length === 0) return { "pack.stability.moved": 0, "pack.stability.mean": 0, "pack.stability.q95": 0 };
+  return {
+    "pack.stability.moved": moved / distances.length,
+    "pack.stability.mean": distances.reduce((sum, d) => sum + d, 0) / distances.length,
+    "pack.stability.q95": quantile(distances, 0.95),
+  };
+}
+
+/**
+ * This function gives the measure `pack.deterministic` of two runs with the same input, options and seed. It gives
+ * `true` when the runs have the same placements, overflow, size and moved obstacles.
+ *
+ * - The placements match by id, so their order in the list does not count. The numbers must be equal.
+ * - The trace is not part of the rule, because its times change each time.
+ */
+export function isDeterministic(first: PackOutput, second: PackOutput): boolean {
+  const key = <T extends { id: string }>(list: readonly T[]): Map<string, T> => new Map(list.map((e) => [e.id, e]));
+  const samePlacements = (a: PackOutput["placements"], b: PackOutput["placements"]): boolean => {
+    if (a.length !== b.length) return false;
+    const other = key(b);
+    return a.every((p) => {
+      const q = other.get(p.id);
+      return q !== undefined && q.x === p.x && q.y === p.y && (q.turn ?? 0) === (p.turn ?? 0);
+    });
+  };
+  const sameMoved = (a: PackOutput["moved"], b: PackOutput["moved"]): boolean => {
+    if (a.length !== b.length) return false;
+    const other = key(b);
+    return a.every((m) => {
+      const n = other.get(m.id);
+      return n !== undefined && n.x === m.x && n.y === m.y;
+    });
+  };
+  const overflowA = new Set(first.overflow);
+  const overflowB = new Set(second.overflow);
+  return (
+    first.size.w === second.size.w &&
+    first.size.h === second.size.h &&
+    overflowA.size === overflowB.size &&
+    [...overflowA].every((id) => overflowB.has(id)) &&
+    samePlacements(first.placements, second.placements) &&
+    sameMoved(first.moved, second.moved)
+  );
+}
+
+/**
+ * This function rounds each number of a record of measures with `round3`, as `docs/FORMAT.md` tells. A half goes up,
+ * and `-0` becomes 0. The function keeps the other values, and it does not change its argument.
+ */
+export function roundMeasures<T extends object>(measures: T): T {
+  const out: Record<string, unknown> = {};
+  for (const [id, value] of Object.entries(measures)) out[id] = typeof value === "number" ? round3(value) : value;
+  return out as T;
+}
+
+/**
+ * This function gives the paired ratio of a measure on one input: the value of the candidate against the value of the
+ * current default. A ratio above 1 is worse, in the direction of the measure.
+ *
+ * - For `lower`, the ratio is `candidate / current`. For `higher`, it is `current / candidate`.
+ * - When both values are 0, the ratio is 1. When only the divisor is 0, the ratio is `Infinity`.
+ * - The values are 0 or more. A negative value or `NaN` throws a `RangeError`.
+ */
+export function pairedRatio(candidate: number, current: number, direction: Direction): number {
+  if (!(candidate >= 0 && current >= 0)) throw new RangeError("A paired ratio needs two values of 0 or more.");
+  const top = direction === "lower" ? candidate : current;
+  const bottom = direction === "lower" ? current : candidate;
+  if (bottom === 0) return top === 0 ? 1 : Infinity;
+  return top / bottom;
+}
+
+/**
+ * This function gives the quantile `q` of a list of numbers, with linear interpolation between the sorted values. The
+ * position in the sorted list is `(n - 1) * q`. An empty list or a `q` outside 0 to 1 throws a `RangeError`.
+ */
+export function quantile(values: readonly number[], q: number): number {
+  if (values.length === 0) throw new RangeError("A quantile needs one value or more.");
+  if (!(q >= 0 && q <= 1)) throw new RangeError("A quantile needs a q from 0 to 1.");
+  const sorted = values.toSorted((a, b) => a - b);
+  const at = (sorted.length - 1) * q;
+  const low = Math.floor(at);
+  const part = at - low;
+  const a = sorted[low]!;
+  if (part === 0) return a;
+  const b = sorted[low + 1]!;
+  if (a === b) return a;
+  return a + part * (b - a);
+}
+
+/** This function gives the quantile `q` of a list, and 0 for an empty list. */
+function quantileOrZero(values: readonly number[], q: number): number {
+  return values.length === 0 ? 0 : quantile(values, q);
+}
+
+/** This function gives the median of the paired ratios of a corpus: the quantile 0.5. It is not a ratio of two medians. */
+export function medianRatio(ratios: readonly number[]): number {
+  return quantile(ratios, 0.5);
+}
+
+/** This function gives the share of the paired ratios above a limit. An empty list throws a `RangeError`. */
+export function tailShare(ratios: readonly number[], limit: number): number {
+  if (ratios.length === 0) throw new RangeError("A tail share needs one ratio or more.");
+  return ratios.filter((r) => r > limit).length / ratios.length;
+}

package/src/metrics.ts

@@ -1,3 +1,4 @@
+import { hullOf, rowsOf } from "./measures.ts";
 import type { Rect } from "./rect.ts";
 
 /** The measurements of a packing. */
@@ -35,31 +36,18 @@ export interface MetricsOptions {
  */
 export function packingMetrics(rects: readonly Rect[], options: MetricsOptions = {}): PackingMetrics {
   const tolerance = options.rowTolerance ?? 40;
-  const boxes = rects.filter((r) => r.size.x > 0 && r.size.y > 0);
+  const boxes = rects.filter((r) => r.size.x > 0 && r.size.y > 0).map((r) => ({ x: r.position.x, y: r.position.y, w: r.size.x, h: r.size.y }));
   if (boxes.length === 0) return { count: 0, hull: { width: 0, height: 0 }, hullAspect: 0, rows: [], raggedness: 0, utilization: 0, widestOverMedian: 0 };
 
-  const left = Math.min(...boxes.map((r) => r.position.x));
-  const top = Math.min(...boxes.map((r) => r.position.y));
-  const right = Math.max(...boxes.map((r) => r.right()));
-  const bottom = Math.max(...boxes.map((r) => r.bottom()));
-  const hull = { width: right - left, height: bottom - top };
-
-  // The rows: the rectangles by their top, and a row takes each rectangle near the top of its first rectangle
-  const rows: { top: number; right: number; count: number }[] = [];
-  for (const r of boxes.toSorted((a, b) => a.position.y - b.position.y)) {
-    const row = rows.at(-1);
-    if (row && Math.abs(r.position.y - row.top) <= tolerance) {
-      row.right = Math.max(row.right, r.right());
-      row.count += 1;
-    } else {
-      rows.push({ top: r.position.y, right: r.right(), count: 1 });
-    }
-  }
+  // The hull and the rows come from the helpers of `measure`, so the two functions agree
+  const box = hullOf(boxes);
+  const hull = { width: box.w, height: box.h };
+  const rows = rowsOf(boxes, tolerance);
   const rights = rows.map((row) => row.right);
-  const widths = boxes.map((r) => r.size.x).toSorted((a, b) => a - b);
+  const widths = boxes.map((r) => r.w).toSorted((a, b) => a - b);
   const median = widths[Math.floor(widths.length / 2)] ?? 0;
   const widest = widths.at(-1) ?? 0;
-  const area = boxes.reduce((sum, r) => sum + r.area(), 0);
+  const area = boxes.reduce((sum, r) => sum + r.w * r.h, 0);
   return {
     count: boxes.length,
     hull,

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("");
+}