@mark1russell7/packing 0.2.11 → 0.2.12

package/package.json

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

package/src/aspect-fit.ts

@@ -0,0 +1,133 @@
+// The wrapper `aspectFit` of roadmap item k62 (`docs/PACKER.md`, "The aspect fit"). For a free-size container, it packs
+// with the wrapped strategy at some widths near the target aspect, and it keeps the best output by a key with the aspect
+// error in it. Nothing default uses it.
+
+import { pickMoves, portfolio, type Member, type SelectLevel } from "@mark1russell7/layout-contract";
+import { marginOf, turnItem, type PackInput, type PackOutput, type Region } from "./contract.ts";
+import { boundsOf, containerBounds, extentOf, viaAxes } from "./frame.ts";
+import { MEASURE_SPECS, measure } from "./measures.ts";
+import { measureKey } from "./select-key.ts";
+import { createContext, type PackContext, type Strategy } from "./strategy.ts";
+
+/** The options of `aspectFit` */
+export interface AspectFitOptions {
+  /** The target aspect: the width divided by the height. The default is `aspect` of the container, else 1. */
+  targetAspect?: number;
+}
+
+/** The id of the trace stage of `aspectFit`. Its measure `move.aspectPick` is 1 when the pick is not the output of the wrapped strategy. */
+export const ASPECT_FIT_STAGE = "aspect-fit";
+
+/**
+ * The factors of the widths of `aspectFit`. Each width is a factor times the square root of the area of the first output
+ * times the target aspect. The steps are approximately 5% of the width, thus approximately 0.1 of the aspect error.
+ */
+export const ASPECT_FIT_FACTORS: readonly number[] = Object.freeze([0.86, 0.9, 0.95, 1, 1.05, 1.1, 1.16]);
+
+/**
+ * The levels of the pick of `aspectFit`, in order. Level 0 is `hard`.
+ *
+ * - `hard`: the count of hard breaks of `checkHard` with `exactContainer`. Lower is better, with the minimum effect 0.
+ * - `pack.overflow.excessArea`: the overflow area above its bound. Lower is better.
+ * - `pack.aspectError`: the distance from the target aspect. Lower is better, with the minimum effect 0.01.
+ * - `pack.area`: the area of the hull. Lower is better, with the minimum effect of 1% of the area.
+ */
+export const ASPECT_FIT_LEVELS: readonly SelectLevel[] = Object.freeze([
+  { id: "hard", spec: { direction: "lower", minEffect: 0 } },
+  { id: "pack.overflow.excessArea", spec: MEASURE_SPECS["pack.overflow.excessArea"] },
+  { id: "pack.aspectError", spec: MEASURE_SPECS["pack.aspectError"] },
+  { id: "pack.area", spec: MEASURE_SPECS["pack.area"] },
+] as SelectLevel[]);
+
+/** This function gives a shape with the origin of `shape` and the width `w`. A shape that is not a rectangle keeps the holes of its polygon. */
+function stripOf(shape: Region, w: number): Region {
+  const b = boundsOf(shape);
+  if (shape.kind === "rect") return { kind: "rect", x: b.x, y: b.y, w, h: b.h };
+  const points: [number, number][] = [
+    [b.x, b.y],
+    [b.x + w, b.y],
+    [b.x + w, b.y + b.h],
+    [b.x, b.y + b.h],
+  ];
+  return shape.kind === "polygon" && shape.holes !== undefined ? { kind: "polygon", points, holes: shape.holes } : { kind: "polygon", points };
+}
+
+/** This function gives an input with the fixed width `w` and a free height. A shape becomes a strip of the width `w`. */
+function atWidth(input: PackInput, w: number): PackInput {
+  const c = input.container;
+  return { ...input, container: { ...c, fixed: "width", w, ...(c.shape === undefined ? {} : { shape: stripOf(c.shape, w) }) } };
+}
+
+/** This function gives the widths of `aspectFit` for an input and the first output. Each width is narrower than a fixed width. */
+function widthsOf(input: PackInput, first: PackOutput, target: number): number[] {
+  const area = measure(input, first)["pack.area"];
+  if (!(area > 0)) return [];
+  const inset = input.container.inset ?? 0;
+  const fixed = input.container.fixed === "width" ? containerBounds(input).w : Infinity;
+  let widest = 0;
+  for (const item of input.items) {
+    const m = marginOf(item);
+    widest = Math.max(widest, item.w + m.left + m.right);
+  }
+  const ideal = Math.sqrt(area * target);
+  const out: number[] = [];
+  for (const f of ASPECT_FIT_FACTORS) {
+    const w = Math.max(Math.round(f * ideal + 2 * inset), Math.ceil(widest + 2 * inset));
+    if (w < fixed && !out.includes(w)) out.push(w);
+  }
+  return out;
+}
+
+/** This function packs an input with a free height or a free size near the target aspect. */
+function fit<O>(input: PackInput, target: number, inner: Strategy<O>, options: O, context: PackContext): PackOutput {
+  const fresh = (): PackContext => createContext(context.seed, { ...(context.budget === undefined ? {} : { budget: context.budget }), ...(context.previous === undefined ? {} : { previous: context.previous }) });
+  const first = inner.pack(input, options, fresh());
+  const widths = widthsOf(input, first, target);
+  if (widths.length === 0) return first;
+  const origin = containerBounds(input);
+  const inset = input.container.inset ?? 0;
+  const free = input.container.fixed === "none";
+  // A free width goes to the far edge of the content. A fixed width keeps its size.
+  const sized = (out: PackOutput): PackOutput => {
+    const w = free ? extentOf(input, out.placements, out.moved, origin, inset, turnItem).right : origin.w;
+    return { ...out, size: { w, h: out.size.h } };
+  };
+  const members: Member<PackInput, PackOutput>[] = [
+    { id: inner.id, run: () => first },
+    ...widths.map((w) => ({ id: `${inner.id}@${w}`, run: (x: PackInput): PackOutput => sized(inner.pack(atWidth(x, w), options, fresh())) })),
+  ];
+  const view = (x: PackInput): PackInput => (x.container.aspect === target ? x : { ...x, container: { ...x.container, aspect: target } });
+  const got = portfolio(ASPECT_FIT_STAGE, members, measureKey(ASPECT_FIT_LEVELS.slice(1), view)).pick(input);
+  const stage = { id: ASPECT_FIT_STAGE, measures: { "move.aspectPick": pickMoves(got.trace).pick } };
+  return { ...got.output, trace: [...(got.output.trace ?? []), stage] };
+}
+
+/**
+ * This function wraps a strategy. For a free-size container, it packs at some widths near the target aspect and keeps the best output.
+ *
+ * - The target is `targetAspect`, else `aspect` of the container, else 1.
+ * - A container with the size `fixed` goes to the wrapped strategy without a change.
+ * - The first member is the output of the wrapped strategy. Each other member packs at one fixed width of `ASPECT_FIT_FACTORS`.
+ * - The key is `ASPECT_FIT_LEVELS`, then `outputHash`. The aspect error reads the target. `selectBest` of the contract picks the winner.
+ * - A fixed height goes through the turn of the axes, with the target `1 / target`.
+ * - The function throws a `RangeError` for a target that is not a number above 0.
+ */
+export function aspectFit<O>(inner: Strategy<O>, options: AspectFitOptions = {}): Strategy<O> {
+  const given = options.targetAspect;
+  if (given !== undefined && !(Number.isFinite(given) && given > 0)) throw new RangeError(`The target aspect of aspectFit is a number above 0, not ${String(given)}.`);
+  return {
+    id: `aspect-fit(${inner.id})`,
+    family: inner.family,
+    catalog: [],
+    supports: inner.supports,
+    defaults: inner.defaults,
+    deterministic: inner.deterministic,
+    pack(input: PackInput, o: O, context: PackContext): PackOutput {
+      const c = input.container;
+      if (c.fixed === "size") return inner.pack(input, o, context);
+      const target = given ?? c.aspect ?? 1;
+      if (c.fixed === "height") return viaAxes(input, context.previous, (turned, previous) => fit(turned, 1 / target, inner, o, { ...context, ...(previous === undefined ? {} : { previous }) }));
+      return fit(input, target, inner, o, context);
+    },
+  };
+}

package/src/corpus.ts

@@ -7,7 +7,7 @@ import type { CorpusCell, GeneratedInput, GeneratorParams } from "./layout-input
 export interface CorpusSpec {
   /** The name of the generator. */
   generator: string;
-  /** The version of the generator. Without it, the spec uses the version of the package. A different version is an error. */
+  /** The version of the generator. Without it, the spec uses the first version of the name. A version that the package does not have is an error. */
   version?: number;
   /** The parameters over the defaults of the generator. */
   params?: GeneratorParams;
@@ -46,10 +46,7 @@ export function corpus(name: string, specs: readonly CorpusSpec[]): Corpus {
   const inputs: GeneratedInput[] = [];
   const ids = new Set<string>();
   for (const spec of specs) {
-    const gen = generator(spec.generator);
-    if (spec.version !== undefined && spec.version !== gen.version) {
-      throw new RangeError(`The generator "${gen.name}" has the version ${gen.version}, not ${spec.version}.`);
-    }
+    const gen = generator(spec.generator, spec.version);
     const params = gen.withDefaults(spec.params);
     const cell = gen.cell(params);
     manifest.specs.push({ generator: gen.name, version: gen.version, params, seeds: [...spec.seeds] });

package/src/frame.ts

@@ -172,27 +172,43 @@ export function readFrame(input: PackInput, frame: Frame, trace: readonly StageT
 }
 
 /**
- * This function gives the size of the container after a packing. A fixed side keeps its size. A free side goes to the
- * far edge of the items with their margins and the inset, or of the obstacles.
+ * This function gives the far edges of a packing from the corner of the container. It reads the items with their margins,
+ * the inset and the obstacles. With `turn`, a placement with `turn: 90` reads the turned item.
  */
-function sizeOf(input: PackInput, frame: Frame, placements: Placement[], moved: PackOutput["moved"], turns?: FrameTurns): { w: number; h: number } {
+export function extentOf(
+  input: PackInput,
+  placements: readonly Placement[],
+  moved: PackOutput["moved"],
+  origin: { x: number; y: number } = containerBounds(input),
+  inset: number = input.container.inset ?? 0,
+  turn?: (item: Item) => Item,
+): { right: number; bottom: number } {
   const items = new Map(input.items.map((i) => [i.id, i]));
   let right = 0;
   let bottom = 0;
   for (const p of placements) {
     const given = items.get(p.id)!;
-    const item = p.turn === 90 && turns !== undefined ? turns.turn(given) : given;
+    const item = p.turn === 90 && turn !== undefined ? turn(given) : given;
     const m = marginOf(item);
-    right = Math.max(right, p.x + item.w + m.right + frame.inset - frame.bounds.x);
-    bottom = Math.max(bottom, p.y + item.h + m.bottom + frame.inset - frame.bounds.y);
+    right = Math.max(right, p.x + item.w + m.right + inset - origin.x);
+    bottom = Math.max(bottom, p.y + item.h + m.bottom + inset - origin.y);
   }
   const movedById = new Map(moved.map((m) => [m.id, m]));
   for (const o of input.obstacles ?? []) {
     const b = boundsOf(o.region);
     const at = movedById.get(o.id) ?? b;
-    right = Math.max(right, at.x + b.w - frame.bounds.x);
-    bottom = Math.max(bottom, at.y + b.h - frame.bounds.y);
+    right = Math.max(right, at.x + b.w - origin.x);
+    bottom = Math.max(bottom, at.y + b.h - origin.y);
   }
+  return { right, bottom };
+}
+
+/**
+ * This function gives the size of the container after a packing. A fixed side keeps its size. A free side goes to the
+ * far edge of the items with their margins and the inset, or of the obstacles.
+ */
+function sizeOf(input: PackInput, frame: Frame, placements: Placement[], moved: PackOutput["moved"], turns?: FrameTurns): { w: number; h: number } {
+  const { right, bottom } = extentOf(input, placements, moved, frame.bounds, frame.inset, turns?.turn);
   return {
     w: Number.isFinite(frame.bounds.w) ? frame.bounds.w : right,
     h: Number.isFinite(frame.bounds.h) ? frame.bounds.h : bottom,

package/src/generators.ts

@@ -473,18 +473,55 @@ export const rectGrid: CorpusGenerator<RectGridParams> = defineGenerator<RectGri
   values: { containerSize: CONTAINER_SIZES, containerShape: CONTAINER_SHAPES, obstacles: OBSTACLE_LAYOUTS, sizes: SIZE_DISTRIBUTIONS },
   family: (p) => `rect-grid.${p.containerSize}.${p.containerShape}.${p.obstacles}.${p.sizes}.n${p.count}`,
   cell: (p) => cellWith(p.containerSize, p.containerShape, p.obstacles, p.sizes, p.count),
-  build(seed, p) {
-    let r = stepRandom(seed, "container");
-    const w = int(r, 600, 1000);
-    const h = int(r, 400, 800);
-    const { region, frame } = shapeOf(r, p.containerShape, w, h);
-    const container = containerOf(p.containerSize, w, h, region);
+  build: gridOf,
+});
 
-    r = stepRandom(seed, "obstacles");
-    const obstacles = obstaclesOf(r, p.obstacles, frame);
+/** This function builds an input of `rect-grid`: the container, then the obstacles, then the boxes. */
+function gridOf(seed: number, p: RectGridParams): Parts {
+  let r = stepRandom(seed, "container");
+  const w = int(r, 600, 1000);
+  const h = int(r, 400, 800);
+  const { region, frame } = shapeOf(r, p.containerShape, w, h);
+  const container = containerOf(p.containerSize, w, h, region);
 
-    r = stepRandom(seed, "boxes");
-    return { container, obstacles, boxes: boxesOf(r, p.sizes, p.count, frame) };
+  r = stepRandom(seed, "obstacles");
+  const obstacles = obstaclesOf(r, p.obstacles, frame);
+
+  r = stepRandom(seed, "boxes");
+  return { container, obstacles, boxes: boxesOf(r, p.sizes, p.count, frame) };
+}
+
+/** The values of the parameter `order` of `rect-grid` version 2. The input format declares no hard order. */
+const GRID_ORDERS = ["free", "soft"] as const;
+
+/** The parameters of `rect-grid` version 2: the parameters of version 1 and the reading order of the boxes. */
+export type RectGridV2Params = RectGridParams & {
+  order: (typeof GRID_ORDERS)[number];
+};
+
+/**
+ * The generator `rect-grid`, version 2: the inputs of version 1 with the parameter `order`. With `soft`, each box gets a
+ * rank, a random permutation of the box indexes. With `free`, the boxes have no rank.
+ */
+export const rectGridV2: CorpusGenerator<RectGridV2Params> = defineGenerator<RectGridV2Params>({
+  name: "rect-grid",
+  version: 2,
+  set: "corpus-v1",
+  defaults: { containerSize: "fixed", containerShape: "rect", obstacles: "none", sizes: "uniform", order: "free", count: 100 },
+  values: { containerSize: CONTAINER_SIZES, containerShape: CONTAINER_SHAPES, obstacles: OBSTACLE_LAYOUTS, sizes: SIZE_DISTRIBUTIONS, order: GRID_ORDERS },
+  family: (p) => `rect-grid.${p.containerSize}.${p.containerShape}.${p.obstacles}.${p.sizes}.${p.order}.n${p.count}`,
+  cell: (p) => ({ ...cellWith(p.containerSize, p.containerShape, p.obstacles, p.sizes, p.count), order: p.order }),
+  build(seed, p) {
+    const built = gridOf(seed, p);
+    if (p.order === "free") return built;
+    // A shuffle of Fisher and Yates gives the ranks
+    const r = stepRandom(seed, "order");
+    const ranks = built.boxes.map((_, i) => i);
+    for (let i = ranks.length - 1; i > 0; i--) {
+      const j = Math.floor(r() * (i + 1));
+      [ranks[i], ranks[j]] = [ranks[j]!, ranks[i]!];
+    }
+    return { ...built, boxes: built.boxes.map((b, i) => ({ ...b, rank: ranks[i]! })) };
   },
 });
 
@@ -673,11 +710,17 @@ export const edgeCases: CorpusGenerator<EdgeCaseParams> = defineGenerator<EdgeCa
 // ---------------------------------------------------------------------------------------------------------------------
 
 /** Each generator of the package. */
-export const generators: readonly CorpusGenerator[] = Object.freeze([rectScattered, rectGrid, gallery, dashboard, cards, wordCloud, edgeCases] as CorpusGenerator[]);
+export const generators: readonly CorpusGenerator[] = Object.freeze([rectScattered, rectGrid, rectGridV2, gallery, dashboard, cards, wordCloud, edgeCases] as CorpusGenerator[]);
 
-/** This function gives the generator with a name. It throws a `RangeError` for a name that the package does not have. */
-export function generator(name: string): CorpusGenerator {
-  const found = generators.find((g) => g.name === name);
-  if (found === undefined) throw new RangeError(`The package has no generator "${name}".`);
+/**
+ * This function gives the generator with a name and a version. Without a version, it gives the first generator of the name
+ * in `generators`: version 1 of `rect-grid`. It throws a `RangeError` for a name or a version that the package does not have.
+ */
+export function generator(name: string, version?: number): CorpusGenerator {
+  const named = generators.filter((g) => g.name === name);
+  if (named.length === 0) throw new RangeError(`The package has no generator "${name}".`);
+  if (version === undefined) return named[0]!;
+  const found = named.find((g) => g.version === version);
+  if (found === undefined) throw new RangeError(`The generator "${name}" has the versions ${named.map((g) => g.version).join(", ")}, not ${version}.`);
   return found;
 }

package/src/index.ts

@@ -79,7 +79,8 @@ export {
   type PushStrategyOptions,
 } from "./adapters.ts";
 export { fromRects, toRects } from "./convert.ts";
-export { composites, packWith, strategies, strategy } from "./registry.ts";
+export { aspectFitStrategy, composites, packWith, strategies, strategy, type AspectFitStrategyOptions } from "./registry.ts";
+export { ASPECT_FIT_FACTORS, ASPECT_FIT_LEVELS, ASPECT_FIT_STAGE, aspectFit, type AspectFitOptions } from "./aspect-fit.ts";
 export { hardBreaks, packPortfolio, PORTFOLIO_LEVELS, PORTFOLIO_STAGE, type PackPortfolioOptions, type PortfolioEntry } from "./portfolio.ts";
 export {
   cellKey,
@@ -130,12 +131,14 @@ export {
   generator,
   generators,
   rectGrid,
+  rectGridV2,
   rectScattered,
   wordCloud,
   type CorpusGenerator,
   type EdgeCase,
   type EdgeCaseParams,
   type RectGridParams,
+  type RectGridV2Params,
   type RectScatteredParams,
   type UiParams,
 } from "./generators.ts";

package/src/portfolio-strategy.ts

@@ -5,7 +5,7 @@ import { maxrects, push, rows, shelf, skyline } from "./adapters.ts";
 import type { PackInput, PackOutput } from "./contract.ts";
 import { portfolioDefaultMembers, portfolioMembers } from "./portfolio-cell.ts";
 import { PORTFOLIO_SETS } from "./portfolio-sets.ts";
-import { packPortfolio } from "./portfolio.ts";
+import { packPortfolio, type PortfolioEntry } from "./portfolio.ts";
 import type { PackContext, Strategy, Supports } from "./strategy.ts";
 
 /** The options of the strategy `portfolio`. Without options, the output is a function of the input only. */
@@ -16,6 +16,10 @@ export interface PortfolioStrategyOptions {
   maxMembers?: number;
   /** The opt-in time limit of `portfolio` of the contract, in milliseconds. It has no default. A cut member makes the result not deterministic. */
   budgetMs?: number;
+  /** The members for each input, in place of the set of the cell. The function refuses `members` with the option `k`. */
+  members?: readonly (string | PortfolioEntry)[];
+  /** The measure ids of the key after the hard breaks, as the option `key` of `packPortfolio`. The default is the key of `PORTFOLIO_LEVELS`. */
+  key?: readonly string[];
 }
 
 /** The single strategies that the members of the table use */
@@ -42,7 +46,8 @@ function unionSupports(): Supports {
  *   The default output thus does not depend on the clock.
  * - A member that does not support the cell of an input throws, and it does not win. When each member throws, the strategy throws the first error.
  * - The option `budgetMs` goes to `portfolio` of the contract. The first member always runs.
- * - The strategy throws a `RangeError` for a `k` other than 2 or 3.
+ * - With `members`, each input gets these members, and `maxMembers` has no default. The id of the portfolio stays `portfolio`.
+ * - The strategy throws a `RangeError` for a `k` other than 2 or 3, and for `k` with `members`.
  */
 export const portfolioStrategy: Strategy<PortfolioStrategyOptions> = {
   id: "portfolio",
@@ -52,11 +57,13 @@ export const portfolioStrategy: Strategy<PortfolioStrategyOptions> = {
   defaults: {},
   deterministic: true,
   pack(input: PackInput, options: PortfolioStrategyOptions, context: PackContext): PackOutput {
-    const { k, maxMembers, budgetMs } = options;
+    const { k, maxMembers, budgetMs, members, key } = options;
     if (k !== undefined && k !== 2 && k !== 3) throw new RangeError(`The option k of the strategy portfolio is 2 or 3, not ${String(k)}.`);
+    if (k !== undefined && members !== undefined) throw new RangeError("The strategy portfolio takes the option k or the option members, not the two.");
     const size = k ?? 3;
-    const count = maxMembers ?? (k === undefined ? portfolioDefaultMembers(input) : undefined);
-    const limits = { ...(count === undefined ? {} : { maxMembers: count }), ...(budgetMs === undefined ? {} : { budgetMs }) };
-    return packPortfolio((x: PackInput) => portfolioMembers(x, size), { id: k === undefined ? "portfolio" : `portfolio-k${k}`, seed: context.seed, ...limits }).run(input);
+    const count = maxMembers ?? (k === undefined && members === undefined ? portfolioDefaultMembers(input) : undefined);
+    const limits = { ...(count === undefined ? {} : { maxMembers: count }), ...(budgetMs === undefined ? {} : { budgetMs }), ...(key === undefined ? {} : { key }) };
+    const list = members ?? ((x: PackInput) => portfolioMembers(x, size));
+    return packPortfolio(list, { id: k === undefined ? "portfolio" : `portfolio-k${k}`, seed: context.seed, ...limits }).run(input);
   },
 };

package/src/portfolio.ts

@@ -1,12 +1,13 @@
 // The portfolio of roadmap item k20, part 1 (`docs/PACKER.md`, "The portfolio"). A portfolio packs an input with each
 // member and keeps the best output by the one pick rule `selectBest` of the contract. Nothing default uses it.
 
-import { pickMoves, portfolio, type Member, type Portfolio, type PortfolioKey, type PortfolioPick, type SelectLevel } from "@mark1russell7/layout-contract";
-import { checkHard } from "./check.ts";
+import { pickMoves, portfolio, type Member, type Portfolio, type PortfolioPick, type SelectLevel } from "@mark1russell7/layout-contract";
 import type { PackInput, PackOutput } from "./contract.ts";
-import { outputHash } from "./layout-input.ts";
-import { MEASURE_SPECS, measure, roundMeasures, type LayoutMeasures } from "./measures.ts";
+import { MEASURE_SPECS } from "./measures.ts";
 import { packWith, strategy } from "./registry.ts";
+import { measureKey, measureLevel } from "./select-key.ts";
+
+export { hardBreaks } from "./select-key.ts";
 
 /** A member of `packPortfolio`: a strategy of the registry with some options. The id names the member in the trace. */
 export interface PortfolioEntry {
@@ -29,6 +30,11 @@ export interface PackPortfolioOptions {
   maxMembers?: number;
   /** The clock in milliseconds. The default is `performance.now`. */
   now?: () => number;
+  /**
+   * The measure ids of the key after the hard breaks, in order. Each id is a measure of `MEASURE_SPECS`. The default is
+   * `pack.overflow.excessArea`, then `pack.fill`, as in `PORTFOLIO_LEVELS`.
+   */
+  key?: readonly string[];
 }
 
 /** The id of the trace stage of `packPortfolio`. Its measure `move.pick` is 1 when the pick is not member 0. */
@@ -47,11 +53,6 @@ export const PORTFOLIO_LEVELS: readonly SelectLevel[] = Object.freeze([
   { id: "pack.fill", spec: MEASURE_SPECS["pack.fill"] },
 ] as SelectLevel[]);
 
-/** This function gives the count of the hard breaks of an output: the sum of `checkHard` with `exactContainer`. */
-export function hardBreaks(input: PackInput, output: PackOutput): number {
-  return Object.values(checkHard(input, output, undefined, { exactContainer: true })).reduce((sum, n) => sum + n, 0);
-}
-
 /**
  * This function makes an opt-in portfolio of strategies of the registry with `portfolio` of the contract.
  * Its `pick(input)` packs the input with each member and gives the output of the winner, its id and the trace.
@@ -59,10 +60,11 @@ export function hardBreaks(input: PackInput, output: PackOutput): number {
  * - A member is a strategy id, or a `PortfolioEntry` with options. The members run in the given order.
  * - `members` is a list, or a function of the input that gives the list. The strategy `portfolio` uses the function form.
  * - The key is the hard breaks, then `pack.overflow.excessArea`, then `pack.fill`. `PORTFOLIO_LEVELS` gives the specs.
+ *   The option `key` gives other measures after the hard breaks.
  * - The key reads the measures after `roundMeasures`, as a record keeps them. A replay of the records gives the same pick.
  * - The hash of the key is `outputHash`. `selectBest` of the contract picks the winner.
  * - The output of the winner gets the trace stage `portfolio` with `move.pick` of `pickMoves`.
- * - The function throws a `RangeError` for an unknown strategy, an empty list and two members with the same id.
+ * - The function throws a `RangeError` for an unknown strategy, an empty list, two members with the same id and an unknown measure of `key`.
  *   With the function form, `pick` throws this error for the list of an input.
  */
 export function packPortfolio(
@@ -77,26 +79,7 @@ export function packPortfolio(
       return { id: e.id, run: (input: PackInput): PackOutput => packWith(e.strategy, input, e.options, seed) };
     });
   const list = typeof members === "function" ? (input: PackInput): Member<PackInput, PackOutput>[] => toMembers(members(input)) : toMembers(members);
-  // Each level reads the measures of one output, so the measures of an output are computed one time
-  const cache = new WeakMap<PackOutput, LayoutMeasures>();
-  const measured = (input: PackInput, output: PackOutput): LayoutMeasures => {
-    let m = cache.get(output);
-    if (m === undefined) {
-      // The key reads the measures as a record keeps them, so a replay of the records gives the same pick
-      m = roundMeasures(measure(input, output));
-      cache.set(output, m);
-    }
-    return m;
-  };
-  const key: PortfolioKey<PackInput, PackOutput> = {
-    hard: hardBreaks,
-    levels: PORTFOLIO_LEVELS.slice(1).map((level) => ({
-      id: level.id,
-      spec: level.spec,
-      value: (input: PackInput, output: PackOutput): number => measured(input, output)[level.id as "pack.fill" | "pack.overflow.excessArea"],
-    })),
-    hash: outputHash,
-  };
+  const key = measureKey(options.key === undefined ? PORTFOLIO_LEVELS.slice(1) : options.key.map(measureLevel));
   const limits = {
     ...(options.budgetMs !== undefined ? { budgetMs: options.budgetMs } : {}),
     ...(options.maxMembers !== undefined ? { maxMembers: options.maxMembers } : {}),

package/src/registry.ts

@@ -1,16 +1,59 @@
 import { maxrects, push, rows, shelf, skyline } from "./adapters.ts";
+import { aspectFit } from "./aspect-fit.ts";
 import type { PackInput, PackOutput } from "./contract.ts";
 import { portfolioStrategy } from "./portfolio-strategy.ts";
-import { createContext, type Strategy } from "./strategy.ts";
+import { createContext, type PackContext, type Strategy, type Supports } from "./strategy.ts";
 
 /** Each single 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, maxrects] as Strategy[]);
 
+/** The options of the strategy `aspect-fit` */
+export interface AspectFitStrategyOptions {
+  /** The id of the wrapped strategy of the registry. The option is necessary. */
+  strategy?: string;
+  /** The options of the wrapped strategy over its defaults */
+  options?: unknown;
+  /** The target aspect of `aspectFit`. The default is `aspect` of the container, else 1. */
+  targetAspect?: number;
+}
+
+/** This function gives the union of the supports of some strategies. */
+function unionOf(list: readonly Strategy[]): Supports {
+  const out: Record<string, string[]> = {};
+  for (const s of list) {
+    for (const [dim, values] of Object.entries(s.supports) as [string, string[]][]) {
+      const own = (out[dim] ??= []);
+      for (const v of values) if (!own.includes(v)) own.push(v);
+    }
+  }
+  return out as unknown as Supports;
+}
+
+/**
+ * The strategy `aspect-fit`: `aspectFit` of roadmap item k62 around the strategy of the option `strategy`. Its supports are
+ * the union of the supports of the single strategies. A cell that the wrapped strategy does not support throws its error.
+ * The strategy throws a `RangeError` without the option `strategy`.
+ */
+export const aspectFitStrategy: Strategy<AspectFitStrategyOptions> = {
+  id: "aspect-fit",
+  family: "aspect-fit",
+  catalog: [],
+  supports: unionOf(strategies),
+  defaults: {},
+  deterministic: true,
+  pack(input: PackInput, options: AspectFitStrategyOptions, context: PackContext): PackOutput {
+    if (options.strategy === undefined) throw new RangeError("The strategy aspect-fit needs the option strategy.");
+    const inner = strategy(options.strategy);
+    const merged: unknown = { ...(inner.defaults as object), ...(options.options as object | undefined) };
+    return aspectFit(inner, options.targetAspect === undefined ? {} : { targetAspect: options.targetAspect }).pack(input, merged, context);
+  },
+};
+
 /**
  * The composite strategies of the registry: each one packs an input with other strategies. They are not in `strategies`.
- * Since 0.2.7, the list has `portfolio` of roadmap item k20.
+ * Since 0.2.7, the list has `portfolio` of roadmap item k20. Roadmap item k62 adds `aspect-fit`.
  */
-export const composites: readonly Strategy[] = Object.freeze([portfolioStrategy] as Strategy[]);
+export const composites: readonly Strategy[] = Object.freeze([portfolioStrategy, aspectFitStrategy] as Strategy[]);
 
 /** This function gives the strategy with an id, also a composite strategy. It throws a `RangeError` for an id that the registry does not have. */
 export function strategy(id: string): Strategy {

package/src/select-key.ts

@@ -0,0 +1,48 @@
+// The key of a pick over the outputs of one input: the hard breaks, then some measures of `MEASURE_SPECS`, then the hash.
+// `packPortfolio` and `aspectFit` use it. The module is internal: the package root exports only `hardBreaks`.
+
+import type { PortfolioKey, SelectLevel } from "@mark1russell7/layout-contract";
+import { checkHard } from "./check.ts";
+import type { PackInput, PackOutput } from "./contract.ts";
+import { outputHash } from "./layout-input.ts";
+import { MEASURE_SPECS, measure, roundMeasures, type LayoutMeasures } from "./measures.ts";
+
+/** This function gives the count of the hard breaks of an output: the sum of `checkHard` with `exactContainer`. */
+export function hardBreaks(input: PackInput, output: PackOutput): number {
+  return Object.values(checkHard(input, output, undefined, { exactContainer: true })).reduce((sum, n) => sum + n, 0);
+}
+
+/** This function gives the level of a measure id with its spec of `MEASURE_SPECS`. It throws a `RangeError` for an unknown id. */
+export function measureLevel(id: string): SelectLevel {
+  const spec = (MEASURE_SPECS as Readonly<Record<string, SelectLevel["spec"] | undefined>>)[id];
+  if (spec === undefined || id === "hard") throw new RangeError(`A level of a key is a measure of MEASURE_SPECS, not "${id}".`);
+  return { id, spec };
+}
+
+/**
+ * This function makes the key of a pick: `hardBreaks`, then the measures of `levels` in order, then `outputHash`.
+ *
+ * - The levels read the measures after `roundMeasures`, as a record keeps them. A replay of the records gives the same pick.
+ * - The measures of one output are computed one time.
+ * - `view` gives the input of the measures. The default is the input. The hard breaks always read the input.
+ */
+export function measureKey(levels: readonly SelectLevel[], view: (input: PackInput) => PackInput = (input) => input): PortfolioKey<PackInput, PackOutput> {
+  const cache = new WeakMap<PackOutput, LayoutMeasures>();
+  const measured = (input: PackInput, output: PackOutput): LayoutMeasures => {
+    let m = cache.get(output);
+    if (m === undefined) {
+      m = roundMeasures(measure(view(input), output));
+      cache.set(output, m);
+    }
+    return m;
+  };
+  return {
+    hard: hardBreaks,
+    levels: levels.map((level) => ({
+      id: level.id,
+      spec: level.spec,
+      value: (input: PackInput, output: PackOutput): number => (measured(input, output) as unknown as Readonly<Record<string, number>>)[level.id]!,
+    })),
+    hash: outputHash,
+  };
+}