@mark1russell7/layout-contract 0.2.12 → 0.2.14

package/build/index.d.ts

@@ -64,33 +64,128 @@ export declare function overlapOf(a: Rect, b: Rect): {
   readonly x: number;
   readonly y: number;
 };
-/** The epsilon for the float compares in an engine. */
-export declare const EPS = 1e-6;
+/** One broken claim of a corpus, with the ids of the inputs that break it. */
+export interface ClaimBreak {
+  /** The name of the claim, for example `declared`, `split` or `index`. */
+  readonly claim: string;
+  /** The text of the break. */
+  readonly detail: string;
+  /** The ids of the inputs that break the claim. The list is empty when the break has no input. */
+  readonly inputs: readonly string[];
+}
+/** The claim `claims.declared` of a manifest: the count of the inputs for each declared property. */
+export interface DeclaredClaim {
+  /** A property with fewer inputs than this count is thin. */
+  readonly minCount: number;
+  /** The ids of the properties with a count below `minCount`. */
+  readonly thin: readonly string[];
+  /** The count of the inputs for each property id. */
+  readonly counts: Readonly<Record<string, number>>;
+  /** The key of the family of an input. `familyOf` gives the key of one cell. The family is the unit of a verdict. */
+  readonly familyBy?: FamilyBy;
+  /** The minimum count of the inputs of each family. Without it, `checkDeclared` does not count the families. */
+  readonly familyMin?: number;
+}
 /**
- * The count of grid steps in one unit of a written file. A file rounds each number `v` to `Math.round(v * RECORD_SCALE) / RECORD_SCALE`.
- * Use a multiplication by this value, not a division by `RECORD_EPS`. The two differ at some half steps.
+ * The key of the family of a cell (`docs/CORPUS-CHECKS.md`).
+ *
+ * - The flat form is a list of dimensions. The key is the values of these dimensions of the cell, in order, with `/` between them.
+ * - The map form chooses an entry by the field `kind` of the cell, or the entry `"*"`. The key is the kind, then the values of the dimensions of the entry.
  */
-export declare const RECORD_SCALE = 1e3;
+export type FamilyBy = readonly string[] | {
+  readonly [kind: string]: readonly string[];
+};
+/** A cell of an input: one value for each dimension. The map form of `FamilyBy` also reads the field `kind`. */
+export type FamilyCell = Readonly<Record<string, unknown>>;
+/** The entry of the map form of `FamilyBy` for each kind without its own entry. */
+export declare const FAMILY_ANY_KIND = "*";
 /**
- * The epsilon for the float compares on a written file. A file rounds each number to 3 decimals,
- * so a difference of two values can move by up to 0.001. It is `1 / RECORD_SCALE`.
+ * This function gives the family key of a cell. It throws a `RangeError` when the cell does not have a dimension of the key.
+ * In the map form, it also throws for a cell without `kind`, and for a kind with no entry and no entry `"*"`.
+ * For example, `{ "rect-grid": ["obstacles"], "*": [] }` gives `rect-grid/wall` for a `rect-grid` cell and `gallery` for a `gallery` cell.
  */
-export declare const RECORD_EPS = .001;
+export declare function familyOf(cell: FamilyCell, familyBy: FamilyBy): string;
+/** The hook that gives the ids of the properties that one input declares. */
+export type Declares<I> = (input: I) => readonly string[];
 /**
- * The tolerance of each hard rule, in layout units. A record writes the tolerance that its run used,
- * in its field `tolerance`, next to `hard`.
+ * This function gives the count of the inputs for each property id. Each id of `ids` has a count, also when the count is 0.
+ * An id from `declares` that is not in `ids` comes after the ids of `ids`, in the order of the first input that declares it.
  */
-export interface Tolerance {
-  /** Two boxes with their margins break `no-overlap` when their insides overlap by more than this on each axis. */
-  readonly overlap: number;
-  /** A route breaks `no-pass-through` when a part longer than this is inside a box made this much smaller. */
-  readonly through: number;
+export declare function declaredCounts<I>(inputs: Iterable<I>, declares: Declares<I>, ids?: readonly string[]): Record<string, number>;
+/**
+ * This function reads the field `claims.declared` of a manifest. A manifest without it gives `undefined`.
+ * It throws an `Error` for a claim without a whole `minCount`, a list `thin` of ids and a whole count for each id.
+ */
+export declare function declaredClaimOf(manifest: object): DeclaredClaim | undefined;
+/**
+ * This function checks the claim `claims.declared` against the inputs. It gives one break `declared` for each problem. An empty list tells that the claim is true.
+ *
+ * - `ids` are the property ids. The default is the ids of `claim.counts`.
+ * - Each id of `ids` has a count in `claim.counts`, and `claim.counts` has no other id. Each count is the count of the inputs.
+ * - An id with a count below `minCount` is in `thin`. Each id of `thin` is an id of `ids`.
+ * - Each id that `declares` gives is an id of `ids`.
+ *
+ * With `claim.familyBy`, the hook `cellOf` gives the cell of each input. The default reads the field `cell` of the input.
+ *
+ * - Each cell has each dimension of its key. In the map form, each cell has a `kind`, and the kind has an entry or the entry `"*"` is there.
+ * - Two cells with different dimension values do not give the same key.
+ * - With `claim.familyMin`, each family has `familyMin` inputs or more.
+ */
+export declare function checkDeclared<I>(inputs: Iterable<I>, declares: Declares<I>, claim: DeclaredClaim, ids?: readonly string[], cellOf?: (input: I) => FamilyCell | undefined): ClaimBreak[];
+/** The id and the hash of one input of a corpus. */
+export interface CorpusEntry {
+  readonly id: string;
+  readonly hash: string;
 }
 /**
- * The default tolerance of each rule. The packer is exact, so `overlap` is one unit of the rounding.
- * Routes are sampled curves that follow the margin line, so `through` is larger.
+ * This function gives the hash of a corpus: the first 16 hex characters of a SHA-256. The text of the SHA-256 is `canonicalJson`
+ * of the corpus id and the `[id, hash]` of each input, in the order of the manifest. A change of one input changes the hash.
  */
-export declare const DEFAULT_TOLERANCE: Tolerance;
+export declare function corpusHashOf(corpus: string, inputs: readonly CorpusEntry[]): string;
+/** The schema of a split file. */
+export declare const SPLIT_SCHEMA = "corpus-split/1";
+/** One fold of a split: the seeds that fit a selector and the seeds that score it. */
+export interface SplitFold {
+  readonly train: readonly number[];
+  readonly heldOut: readonly number[];
+}
+/** A split file `corpus-split/1`. Its name is `<corpus id>.<corpus hash>.json`. It is beside the corpus, so the corpus does not change. */
+export interface CorpusSplit {
+  readonly schema: typeof SPLIT_SCHEMA;
+  readonly corpus: string;
+  /** The hash of the corpus: `corpusHashOf` of its manifest. */
+  readonly corpusHash: string;
+  /** The splits by name. Each split has one fold or more. */
+  readonly splits: Readonly<Record<string, {
+    readonly folds: readonly SplitFold[];
+  }>>;
+}
+/** The fields of a manifest that the split check reads. */
+export interface SplitCorpus {
+  readonly corpus: string;
+  readonly specs: readonly {
+    readonly seeds: readonly number[];
+  }[];
+  readonly inputs: readonly CorpusEntry[];
+}
+/** This function gives the name of the split file of a corpus. */
+export declare function splitFileName(corpus: string, hash: string): string;
+/**
+ * This function checks a split file against a manifest. It gives one break `split` for each problem. An empty list tells that the file is good.
+ *
+ * - The schema is `corpus-split/1`, the corpus is the id of the manifest and `corpusHash` is `corpusHashOf` of the manifest.
+ * - Each split has one fold or more. In each fold, `train` and `heldOut` are lists of seeds, not empty and with no common seed.
+ * - Each seed is a seed of a spec of the manifest.
+ * - With `name`, the file has the split `name`.
+ */
+export declare function checkSplit(split: unknown, corpus: SplitCorpus, name?: string): ClaimBreak[];
+/**
+ * This function gives a copy of the folds of the split `name` of a split file. `where` names the file in the text of an error.
+ * It throws an `Error` for each problem of `checkSplit`, and then for an unknown split name.
+ */
+export declare function splitFolds(split: unknown, corpus: SplitCorpus, name: string, where?: string): SplitFold[];
+/** This function gives the folds that hold out one seed each, in the order of the seeds. Each fold trains on the other seeds. */
+export declare function leaveOneSeedOut(seeds: readonly number[]): SplitFold[];
 /**
  * A port of a box: a place where edges go into the box.
  * With `x` and `y`, the port is fixed on the border of the box, relative to its top-left corner.
@@ -118,6 +213,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;
@@ -166,6 +266,18 @@ export interface LayoutGenerator {
   readonly params: Readonly<Record<string, unknown>>;
   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";
@@ -178,6 +290,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`. */
 export interface LayoutInput {
@@ -201,6 +315,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[];
@@ -217,9 +333,99 @@ 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. */
 export declare function toPackInput(input: LayoutInput): PackInput;
+/**
+ * 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 declare function canonicalInput<T extends LayoutInput>(input: T): T;
+/**
+ * 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 declare const SHAPE_KINDS: readonly ShapeKindSpec[];
+/** The ids of `SHAPE_KINDS`, in their order. */
+export declare const SHAPE_KIND_IDS: readonly ShapeKind[];
+/** The shape kinds of a measure or a rule without `shapes`. The contract measured only rectangles before L46. */
+export declare const DEFAULT_SHAPES: readonly ShapeKind[];
+/** 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[];
+}
+/** This function tells if a value is a declared shape kind. */
+export declare function isShapeKind(value: unknown): value is ShapeKind;
+/**
+ * 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 declare function shapeKindOf(box: LayoutBox): ShapeKind;
+/** 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 declare function shapeKindsOf(input: Pick<LayoutInput, "boxes">): ShapeKind[];
+/** 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 declare function itemShapeOf(input: Pick<LayoutInput, "boxes">): ShapeKind | "mixed";
+/** This function gives the problem of the shape kind of a box, or `undefined` when `shapeKind` and `shape` agree. */
+export declare function shapeKindProblem(box: LayoutBox): string | undefined;
+/** This function gives the shape kinds that a measure or a rule supports. */
+export declare function shapesOf(use: Pick<ShapeSupport, "shapes">): readonly ShapeKind[];
+/**
+ * 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 declare function checkShapes(input: Pick<LayoutInput, "id" | "boxes">, uses: readonly ShapeSupport[]): ClaimBreak[];
+/** The epsilon for the float compares in an engine. */
+export declare const EPS = 1e-6;
+/**
+ * The count of grid steps in one unit of a written file. A file rounds each number `v` to `Math.round(v * RECORD_SCALE) / RECORD_SCALE`.
+ * Use a multiplication by this value, not a division by `RECORD_EPS`. The two differ at some half steps.
+ */
+export declare const RECORD_SCALE = 1e3;
+/**
+ * The epsilon for the float compares on a written file. A file rounds each number to 3 decimals,
+ * so a difference of two values can move by up to 0.001. It is `1 / RECORD_SCALE`.
+ */
+export declare const RECORD_EPS = .001;
+/**
+ * The tolerance of each hard rule, in layout units. A record writes the tolerance that its run used,
+ * in its field `tolerance`, next to `hard`.
+ */
+export interface Tolerance {
+  /** Two boxes with their margins break `no-overlap` when their insides overlap by more than this on each axis. */
+  readonly overlap: number;
+  /** A route breaks `no-pass-through` when a part longer than this is inside a box made this much smaller. */
+  readonly through: number;
+}
+/**
+ * The default tolerance of each rule. The packer is exact, so `overlap` is one unit of the rounding.
+ * Routes are sampled curves that follow the margin line, so `through` is larger.
+ */
+export declare const DEFAULT_TOLERANCE: Tolerance;
 /** The position of one item. `turn` is 90 when the packer turned a turnable item. */
 export interface Placement {
   readonly id: string;
@@ -276,6 +482,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. */
@@ -319,16 +527,22 @@ export interface RunEnv {
   readonly cpus: number;
 }
 /** The facts of a run that the input does not give. */
-export type RunFacts = Omit<LayoutRecord, "schema" | "input" | "inputHash" | "set" | "nodes" | "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. */
+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.
+ * The input also gives `shapes`. An input with only `rect` boxes gets no `shapes`, so its record does not change.
+ */
 export declare function toLayoutRecord(input: LayoutInput, run: RunFacts): LayoutRecord;
 /** This function gives the area of a placed box: its shape or its rectangle, at its position. A box without a position gives `undefined`. */
 export declare 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 declare function countOverlaps(boxes: readonly LayoutBox[], tolerance?: number): number;
+export declare function countOverlaps(boxes: readonly LayoutBox[], tolerance?: number, pairGaps?: readonly PairGap[]): number;
 /** The options of the container test of `countOutside` and `packHard`. */
 export interface ContainerTest {
   /**
@@ -355,6 +569,12 @@ export interface PackHard {
   readonly "locked-kept": number;
   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 declare const PACK_HARD_RULES: readonly ShapeSupport<keyof PackHard>[];
 /** This function tells if the inside of `region` and the inside of `rect` have a common point. */
 export declare function regionHitsRect(region: Region, rect: Rect): boolean;
 /**
@@ -370,7 +590,8 @@ export declare function countObstacleHits(boxes: readonly LayoutBox[], obstacles
 /**
  * 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`.
@@ -381,6 +602,7 @@ export declare function packHard(input: LayoutInput, output: PackOutput, toleran
 /**
  * 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 declare function checkInput(input: LayoutInput): readonly string[];
 /** This function gives the side after a turn of 90 degrees clockwise. */
@@ -425,10 +647,15 @@ export interface MeasureSpec<Id extends string = string> {
   };
   /** 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. */
 export type JointMeasureId = "joint.fill" | "joint.aspectError" | "joint.spill" | "joint.straight.crossings" | "joint.straight.length" | "joint.stability.mean" | "joint.stability.moved" | "joint.proxy.rank" | "joint.ms";
-/** The specs of the joint measures, in the order of `docs/JOINT-MEASURES.md`. */
+/**
+ * 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 declare const JOINT_MEASURES: readonly MeasureSpec<JointMeasureId>[];
 /** The threshold of `joint.stability.moved`, in widths `W` of the base. */
 export declare const JOINT_MOVED_MIN = .01;
@@ -530,6 +757,7 @@ export declare function outputHash(value: unknown, options?: HashOptions): strin
 /**
  * This function gives the hash of a document. It uses the rule of `outputHash`, but the form does not include the field `hash` of the document.
  * With the default grid, it is the input hash of `docs/FORMAT.md` of `packing`.
+ * A document with the schema `layout-input/1` goes through `canonicalInput` first. Thus the order of its `pairGaps` does not change the hash.
  */
 export declare function documentHash(doc: object, options?: HashOptions): string;
 /** One output group: the candidates with the same output hash on each decision input. */
@@ -697,128 +925,6 @@ export declare function pickMoves(trace: Pick<PortfolioTrace, "picked">): {
  * It also throws a `RangeError` for an empty list of members, or for two members with the same id.
  */
 export declare function portfolio<I, O>(id: string, members: readonly Member<I, O>[] | ((input: I) => readonly Member<I, O>[]), key: PortfolioKey<I, O>, options?: PortfolioOptions): Portfolio<I, O>;
-/** One broken claim of a corpus, with the ids of the inputs that break it. */
-export interface ClaimBreak {
-  /** The name of the claim, for example `declared`, `split` or `index`. */
-  readonly claim: string;
-  /** The text of the break. */
-  readonly detail: string;
-  /** The ids of the inputs that break the claim. The list is empty when the break has no input. */
-  readonly inputs: readonly string[];
-}
-/** The claim `claims.declared` of a manifest: the count of the inputs for each declared property. */
-export interface DeclaredClaim {
-  /** A property with fewer inputs than this count is thin. */
-  readonly minCount: number;
-  /** The ids of the properties with a count below `minCount`. */
-  readonly thin: readonly string[];
-  /** The count of the inputs for each property id. */
-  readonly counts: Readonly<Record<string, number>>;
-  /** The key of the family of an input. `familyOf` gives the key of one cell. The family is the unit of a verdict. */
-  readonly familyBy?: FamilyBy;
-  /** The minimum count of the inputs of each family. Without it, `checkDeclared` does not count the families. */
-  readonly familyMin?: number;
-}
-/**
- * The key of the family of a cell (`docs/CORPUS-CHECKS.md`).
- *
- * - The flat form is a list of dimensions. The key is the values of these dimensions of the cell, in order, with `/` between them.
- * - The map form chooses an entry by the field `kind` of the cell, or the entry `"*"`. The key is the kind, then the values of the dimensions of the entry.
- */
-export type FamilyBy = readonly string[] | {
-  readonly [kind: string]: readonly string[];
-};
-/** A cell of an input: one value for each dimension. The map form of `FamilyBy` also reads the field `kind`. */
-export type FamilyCell = Readonly<Record<string, unknown>>;
-/** The entry of the map form of `FamilyBy` for each kind without its own entry. */
-export declare const FAMILY_ANY_KIND = "*";
-/**
- * This function gives the family key of a cell. It throws a `RangeError` when the cell does not have a dimension of the key.
- * In the map form, it also throws for a cell without `kind`, and for a kind with no entry and no entry `"*"`.
- * For example, `{ "rect-grid": ["obstacles"], "*": [] }` gives `rect-grid/wall` for a `rect-grid` cell and `gallery` for a `gallery` cell.
- */
-export declare function familyOf(cell: FamilyCell, familyBy: FamilyBy): string;
-/** The hook that gives the ids of the properties that one input declares. */
-export type Declares<I> = (input: I) => readonly string[];
-/**
- * This function gives the count of the inputs for each property id. Each id of `ids` has a count, also when the count is 0.
- * An id from `declares` that is not in `ids` comes after the ids of `ids`, in the order of the first input that declares it.
- */
-export declare function declaredCounts<I>(inputs: Iterable<I>, declares: Declares<I>, ids?: readonly string[]): Record<string, number>;
-/**
- * This function reads the field `claims.declared` of a manifest. A manifest without it gives `undefined`.
- * It throws an `Error` for a claim without a whole `minCount`, a list `thin` of ids and a whole count for each id.
- */
-export declare function declaredClaimOf(manifest: object): DeclaredClaim | undefined;
-/**
- * This function checks the claim `claims.declared` against the inputs. It gives one break `declared` for each problem. An empty list tells that the claim is true.
- *
- * - `ids` are the property ids. The default is the ids of `claim.counts`.
- * - Each id of `ids` has a count in `claim.counts`, and `claim.counts` has no other id. Each count is the count of the inputs.
- * - An id with a count below `minCount` is in `thin`. Each id of `thin` is an id of `ids`.
- * - Each id that `declares` gives is an id of `ids`.
- *
- * With `claim.familyBy`, the hook `cellOf` gives the cell of each input. The default reads the field `cell` of the input.
- *
- * - Each cell has each dimension of its key. In the map form, each cell has a `kind`, and the kind has an entry or the entry `"*"` is there.
- * - Two cells with different dimension values do not give the same key.
- * - With `claim.familyMin`, each family has `familyMin` inputs or more.
- */
-export declare function checkDeclared<I>(inputs: Iterable<I>, declares: Declares<I>, claim: DeclaredClaim, ids?: readonly string[], cellOf?: (input: I) => FamilyCell | undefined): ClaimBreak[];
-/** The id and the hash of one input of a corpus. */
-export interface CorpusEntry {
-  readonly id: string;
-  readonly hash: string;
-}
-/**
- * This function gives the hash of a corpus: the first 16 hex characters of a SHA-256. The text of the SHA-256 is `canonicalJson`
- * of the corpus id and the `[id, hash]` of each input, in the order of the manifest. A change of one input changes the hash.
- */
-export declare function corpusHashOf(corpus: string, inputs: readonly CorpusEntry[]): string;
-/** The schema of a split file. */
-export declare const SPLIT_SCHEMA = "corpus-split/1";
-/** One fold of a split: the seeds that fit a selector and the seeds that score it. */
-export interface SplitFold {
-  readonly train: readonly number[];
-  readonly heldOut: readonly number[];
-}
-/** A split file `corpus-split/1`. Its name is `<corpus id>.<corpus hash>.json`. It is beside the corpus, so the corpus does not change. */
-export interface CorpusSplit {
-  readonly schema: typeof SPLIT_SCHEMA;
-  readonly corpus: string;
-  /** The hash of the corpus: `corpusHashOf` of its manifest. */
-  readonly corpusHash: string;
-  /** The splits by name. Each split has one fold or more. */
-  readonly splits: Readonly<Record<string, {
-    readonly folds: readonly SplitFold[];
-  }>>;
-}
-/** The fields of a manifest that the split check reads. */
-export interface SplitCorpus {
-  readonly corpus: string;
-  readonly specs: readonly {
-    readonly seeds: readonly number[];
-  }[];
-  readonly inputs: readonly CorpusEntry[];
-}
-/** This function gives the name of the split file of a corpus. */
-export declare function splitFileName(corpus: string, hash: string): string;
-/**
- * This function checks a split file against a manifest. It gives one break `split` for each problem. An empty list tells that the file is good.
- *
- * - The schema is `corpus-split/1`, the corpus is the id of the manifest and `corpusHash` is `corpusHashOf` of the manifest.
- * - Each split has one fold or more. In each fold, `train` and `heldOut` are lists of seeds, not empty and with no common seed.
- * - Each seed is a seed of a spec of the manifest.
- * - With `name`, the file has the split `name`.
- */
-export declare function checkSplit(split: unknown, corpus: SplitCorpus, name?: string): ClaimBreak[];
-/**
- * This function gives a copy of the folds of the split `name` of a split file. `where` names the file in the text of an error.
- * It throws an `Error` for each problem of `checkSplit`, and then for an unknown split name.
- */
-export declare function splitFolds(split: unknown, corpus: SplitCorpus, name: string, where?: string): SplitFold[];
-/** This function gives the folds that hold out one seed each, in the order of the seeds. Each fold trains on the other seeds. */
-export declare function leaveOneSeedOut(seeds: readonly number[]): SplitFold[];
 /** The schema of a strategy space. */
 export declare const STRATEGY_SPACE_SCHEMA = "strategy-space/1";
 /** The kind of a param: a whole number, a real number, one value of a list, or `true` and `false`. */
@@ -856,12 +962,30 @@ export interface MemberRule {
   readonly min: number;
   readonly max: number;
   readonly ordered: boolean;
+  /**
+   * The member lists that the option permits. Each entry is a list of whole configs of the space of the members.
+   * Without `pool`, each list of base configs with a good count is a member list.
+   * With `pool`, a config of the option has the members of one entry, and `spaceSize` counts each entry one time.
+   */
+  readonly pool?: readonly (readonly StrategyConfig[])[];
+}
+/** The inputs that an option supports. A missing field supports each value. */
+export interface OptionSupports {
+  /** The shape kinds of the boxes (`docs/SHAPES.md`). Without it, the option supports each kind. */
+  readonly shape?: readonly ShapeKind[];
 }
 /** One implementation of a stage. An option with `members` is a meta option: it chooses between whole configs, or wraps them. */
 export interface StageOption {
   readonly id: string;
   readonly params: readonly SpaceParam[];
   readonly members?: MemberRule;
+  /** The inputs that the option supports. It describes the option, so it is not part of a config or of its id. */
+  readonly supports?: OptionSupports;
+}
+/** The shape kinds of the inputs of a check, a count or an enumeration. Without `shapes`, each option counts. */
+export interface ShapeFilter {
+  /** The shape kinds of the input. Only the options that support each of these kinds count. */
+  readonly shapes?: readonly ShapeKind[];
 }
 /** One stage of the pipeline of an engine. A config of an `optional` stage can have no option. */
 export interface SpaceStage {
@@ -917,40 +1041,50 @@ export interface SpaceSize {
   readonly meta: bigint | null;
 }
 /** The options of `spaceSize`. */
-export interface SpaceSizeOptions {
+export interface SpaceSizeOptions extends ShapeFilter {
   /** The count of the levels of each numeric param, a whole number of 1 or more. */
   readonly levels: number;
   /** The largest meta count that `spaceSize` gives. The default is `10n ** 18n`. */
   readonly maxMeta?: bigint;
 }
 /** The options of a grid. The grid gives only the configs without a meta option. */
-export interface GridOptions {
+export interface GridOptions extends ShapeFilter {
   readonly mode: "grid";
   readonly levels: number;
   /** The largest count of configs. A larger grid causes a `RangeError`. The default is 100000. */
   readonly limit?: number;
 }
 /** The options of a sample. */
-export interface SampleOptions {
+export interface SampleOptions extends ShapeFilter {
   readonly mode: "sample";
   /** The count of the configs, a whole number of 0 or more. */
   readonly n: number;
   readonly seed: number;
-  /** With `skip` (the default), the sample has no meta option. With `sample`, a meta option draws its members from base samples. */
+  /** With `skip` (the default), the sample has no meta option. With `sample`, a meta option draws its members from base samples, or one entry of its `pool`. */
   readonly meta?: "skip" | "sample";
   /** The largest count of option draws. The default is the larger value of 1000 and `100 * n`. */
   readonly maxTries?: number;
 }
 /** The options of `enumerateSpace`. */
 export type EnumerateOptions = GridOptions | SampleOptions;
+/** This function gives the problem of a value of a param, or `undefined` for a value in its range. The corpus dimensions of `families.ts` use it. */
+export declare function paramProblem(param: SpaceParam, value: unknown): string | undefined;
+/** This function tells if a param is active for the values of the earlier params. A param without `when` is always active. */
+export declare function paramActive(param: SpaceParam, values: Readonly<Record<string, ParamValue>>): boolean;
+/** This function gives the stable form of a value of a param: a real number gets 12 significant digits, and `-0` becomes `0`. */
+export declare function paramValue(param: SpaceParam, value: ParamValue): ParamValue;
 /**
  * This function checks one config of a space. It gives one break for each problem. An empty list tells that the config is good.
  * The `claim` of a break is the kind of the problem, for example `missing`, `unknown`, `inactive`, `param`, `constraint`, `members` or `depth`.
+ *
+ * A member list that is not an entry of the `pool` of its option gives the claim `pool`.
+ * With `shapes`, an option that does not support a kind of the list gives the claim `shape`. A member of a meta option gets the same check.
  */
-export declare function checkConfig(space: StrategySpace, config: StrategyConfig): ClaimBreak[];
+export declare function checkConfig(space: StrategySpace, config: StrategyConfig, options?: ShapeFilter): ClaimBreak[];
 /**
  * This function checks a space. It gives one break for each problem. An empty list tells that the space is good.
  * It finds duplicate names, empty ranges, defaults out of range, enums without values, bad log scales, unknown names and bad named configs.
+ * It also checks each entry of a `pool`: the count of its members, each member and a repeated entry.
  * The `inputs` of a break of a named config have the name of the config.
  */
 export declare function checkSpace(space: StrategySpace): ClaimBreak[];
@@ -973,6 +1107,8 @@ export declare function paramLevels(param: SpaceParam, levels: number): ParamVal
 /**
  * This function gives the count of the grid points of a space, with `levels` levels for each numeric param.
  * It counts only the active params and the combinations that keep the constraints. It gives the meta configs apart.
+ * A meta option with a `pool` counts each entry of the pool one time.
+ * With `shapes`, it counts only the options that support each kind of the list.
  */
 export declare function spaceSize(space: StrategySpace, options: SpaceSizeOptions): SpaceSize;
 /**
@@ -981,8 +1117,15 @@ export declare function spaceSize(space: StrategySpace, options: SpaceSizeOption
  * - The mode `grid` gives each grid point without a meta option, in a stable order. Stages, options and values go in the order of the space.
  * - The mode `sample` gives `n` configs of a seeded Latin hypercube. The options of a stage get equal strata, and each active param gets its own strata.
  * - A sample draws again when a point breaks a constraint. After `maxTries` draws, it throws an `Error`. Two sampled configs can be equal.
+ * - With `shapes`, only the options that support each kind of the list count. Without `shapes`, the result does not change.
+ * - A meta option with a `pool` gives only the entries of its pool. With `shapes`, only the entries whose members support each kind count.
  */
 export declare function enumerateSpace(space: StrategySpace, options: EnumerateOptions): StrategyConfig[];
+/**
+ * This function gives the shape kinds that a space accepts, in the order of `SHAPE_KINDS`. The value comes from the `supports` of the options.
+ * A space accepts a kind when it has at least one config without a meta option on that kind.
+ */
+export declare function spaceShapeKinds(space: StrategySpace): ShapeKind[];
 /**
  * This function joins configs of the parts of a product space into one config of the space `space`.
  * The name of each stage gets the prefix `<space of the part>.`. The members of a meta option do not change.
@@ -1128,4 +1271,186 @@ export interface VerdictResult {
  * It throws a `RangeError` for a missing `tie` or `level`, and for no pair. Two records of one side and input, or a value that is not finite, also cause a `RangeError`.
  */
 export declare function verdict<R extends VerdictRecord>(records: Iterable<R>, options: VerdictOptions<R>): VerdictResult;
+/**
+ * One dimension of a corpus: a param of `strategy-space.ts` with its meaning and the engines that use it.
+ * The field `when` has the form of `SpaceParam.when`: the dimension is active only for some values of an earlier dimension.
+ */
+export interface CorpusDimension extends SpaceParam {
+  /** The meaning of the dimension, in one sentence. */
+  readonly meaning: string;
+  /** The engines that read the dimension, for example `packing`, `highways` and `joint`. */
+  readonly engines: readonly string[];
+  /** The values of a sweep. Without them, a sweep uses the values of an `enum`, `false` and `true` of a `bool`, or the default. */
+  readonly levels?: readonly ParamValue[];
+}
+/** The values of the dimensions of one input: one value for each name. */
+export type DimensionValues = Readonly<Record<string, ParamValue>>;
+/** A factory of seeded random numbers: it gives a source of numbers in [0, 1) for a seed. */
+export type RngFactory = (seed: number) => () => number;
+/**
+ * The cross-engine note of a family. `exact` tells that each JavaScript engine gives the same output.
+ * `libm-dependent` tells that the family uses a function that is not correctly rounded in each engine, for example `Math.log`, `Math.cos` or `**`.
+ */
+export type CrossEngine = "exact" | "libm-dependent";
+/** The random numbers of the default factory: `mulberry32` of `random.ts`. Its stream is pinned in `families.test.ts`. */
+export declare const DEFAULT_RNG: RngFactory;
+/** The context that a registry gives to `generate`. */
+export interface GenerateContext {
+  /** The random factory of the family: its own `rng`, or `DEFAULT_RNG`. */
+  readonly rng: RngFactory;
+  /** The source of random numbers of the input: `rng(rngSeed(seed, dims))`. A family that does not use it takes no numbers from it. */
+  readonly random: () => number;
+  /** The name of the corpus of the input, when the caller gives one. */
+  readonly set?: string;
+}
+/**
+ * A family of a corpus: a seeded generator with declared dimensions. The engine that owns it gives it to a registry.
+ * The registry gives `generate` the raw seed and the full dimension values. It does not change the output, and it does not calculate a hash.
+ */
+export interface CorpusFamily<O = LayoutInput> {
+  /** The name of the family, for example `rect-grid`. */
+  readonly name: string;
+  /** The version. A change of the output of the family needs a new version. A dimension of only some versions is in the list of those versions only. */
+  readonly version: number;
+  /** The engine that owns the definition of the family, for example `packing`. */
+  readonly owner: string;
+  /** The meaning of the family, in one sentence. */
+  readonly meaning: string;
+  /** The dimensions of the family, in their order. A dimension with `when` comes after the dimension that its `when` names. The name `kind` is reserved. */
+  readonly dimensions: readonly CorpusDimension[];
+  /** The text of the rule that gives the random numbers of an input from its seed and its dimensions. */
+  readonly seeding: string;
+  /** The cross-engine note of the family. */
+  readonly crossEngine: CrossEngine;
+  /** The random factory of the family. The default is `DEFAULT_RNG`. */
+  readonly rng?: RngFactory;
+  /** This function gives the seed of `context.random` from the input seed and the full dimension values. The default gives the input seed. */
+  readonly rngSeed?: (seed: number, dims: DimensionValues) => number;
+  /** The dimensions of the family key of `familyBy`, after the kind of the cell. A dimension with `when` is not permitted. The default is no dimension. */
+  readonly familyBy?: readonly string[];
+  /** This function gives the input of a seed. `dims` has a value for each dimension, also for an inactive dimension. */
+  generate(seed: number, dims: DimensionValues, context: GenerateContext): O;
+}
+/** The options of `generate` of a registry. */
+export interface GenerateOptions {
+  /** The version of the family. The default is the first version that the registry got. */
+  readonly version?: number;
+  /** The name of the corpus. The registry gives it to the family in `context.set`. */
+  readonly set?: string;
+}
+/** The options of `cells` and `cellCount` of a registry. */
+export interface CellsOptions {
+  readonly version?: number;
+  /** The dimensions of the sweep. The other dimensions keep their defaults. The default is each dimension of the family. */
+  readonly sweep?: readonly string[];
+  /** The values of a sweep for some dimensions, in place of the levels of the dimensions. */
+  readonly levels?: Readonly<Record<string, readonly ParamValue[]>>;
+}
+/** The cell of an input of a registry: `<name>@<version>` of its family in `kind` (`familyKind`), and the value of each active dimension. */
+export type RegistryCell = Readonly<Record<string, ParamValue>> & {
+  readonly kind: string;
+};
+/** This function gives the `kind` of the cells of a version of a family: `<name>@<version>`, for example `rect-grid@2`. Thus two versions do not share a family key. */
+export declare function familyKind(name: string, version: number): string;
+/** A registry of families. An import registers nothing: a host makes a registry from the lists of families of the engines. */
+export interface FamilyRegistry<O = LayoutInput> {
+  /** This method adds a family. It throws a `RangeError` for a second family with the same name and version, or for a bad dimension. */
+  register(family: CorpusFamily<O>): FamilyRegistry<O>;
+  /** This method gives a family. Without a version, it gives the first version that the registry got. It throws a `RangeError` for an unknown family. */
+  family(name: string, version?: number): CorpusFamily<O>;
+  /** This method gives each family, in the order of registration. */
+  families(): readonly CorpusFamily<O>[];
+  /**
+   * This method gives the full dimension values of an input. It throws a `RangeError` for an unknown dimension or a bad value.
+   * The methods with `dims` accept a cell of `cellOf`: they ignore a `kind` that is the `familyKind` of the family, and refuse another `kind`.
+   */
+  resolve(name: string, dims?: Readonly<Record<string, ParamValue>>, version?: number): DimensionValues;
+  /** This method gives the input of a seed. The output is the output of the family, with no change. */
+  generate(name: string, seed: number, dims?: Readonly<Record<string, ParamValue>>, options?: GenerateOptions): O;
+  /** This method gives the cell of an input: the `familyKind` of the family version and the value of each active dimension. */
+  cellOf(name: string, dims?: Readonly<Record<string, ParamValue>>, version?: number): RegistryCell;
+  /** This method gives the full dimension values of each cell of a sweep, without the dead combinations of `when`. */
+  cells(name: string, options?: CellsOptions): Generator<DimensionValues>;
+  /** This method gives the count of the cells of `cells`. It makes no input. */
+  cellCount(name: string, options?: CellsOptions): number;
+  /** This method gives the defaults, and each end of each numeric range. The dimensions that a `when` needs get its first value. The other dimensions keep their defaults. */
+  boundaryCells(name: string, version?: number): DimensionValues[];
+  /** This method gives the random source of an input: the stream that `generate` gets in `context.random`. */
+  rngOf(name: string, version?: number): (seed: number, dims?: Readonly<Record<string, ParamValue>>) => () => number;
+  /** This method gives the map form of `FamilyBy` for the cells of `cellOf`: the `familyKind` of each family version, with its own `familyBy`. */
+  familyBy(): FamilyBy;
+}
+/** The default key of a family in a manifest: the kind of the cell alone. It is the map form of `FamilyBy` with the entry `"*"`. */
+export declare const DEFAULT_FAMILY_BY: FamilyBy;
+/**
+ * The shared dimension table. A family takes a dimension of it with `sharedDimension`, or declares its own dimension.
+ * The coverage table of each dimension and each engine is in `docs/CORPUS.md`.
+ */
+export declare const CORPUS_DIMENSIONS: Readonly<Record<string, CorpusDimension>>;
+/** This function gives a dimension of `CORPUS_DIMENSIONS`, with the fields of `patch` over it. It throws a `RangeError` for an unknown name. */
+export declare function sharedDimension(name: string, patch?: Partial<CorpusDimension>): CorpusDimension;
+/**
+ * This function gives the value at the fraction `t` of the range of a numeric dimension, on its scale. A slider of a site uses it.
+ * A log scale with a `min` of 0 or less is the log of `1 + x - min`. An `int` dimension gives a whole number.
+ */
+export declare function dimensionAt(dim: SpaceParam, t: number): number;
+/** This function gives the fraction of the range of a numeric dimension at a value, on its scale. It is the inverse of `dimensionAt`. */
+export declare function dimensionUnit(dim: SpaceParam, value: number): number;
+/**
+ * This function gives the values of a sweep of a dimension. `levels` of the dimension come first. Then an `enum` gives its values, and a `bool` gives `false` and `true`.
+ * With `steps`, a numeric dimension gives `steps` points from `min` to `max` on its scale. Else it gives its default.
+ */
+export declare function levelsOf(dim: CorpusDimension, steps?: number): ParamValue[];
+/**
+ * This function gives the full dimension values of an input. A missing dimension gets its default. An inactive dimension of `when` also gets its default.
+ * Thus a default that the caller gives, a missing value and an inactive value give the same values. A real number gets its stable form.
+ * The function throws a `RangeError` for an unknown dimension or a bad value, also for a bad value of an inactive dimension.
+ */
+export declare function resolveDimensions(dimensions: readonly CorpusDimension[], dims?: Readonly<Record<string, ParamValue>>, where?: string): DimensionValues;
+/** This function gives a new registry with the families of the list. Each engine gives the list of its families. An import registers nothing. */
+export declare function createFamilyRegistry<O = LayoutInput>(families?: Iterable<CorpusFamily<O>>): FamilyRegistry<O>;
+/** A step of a composed family: a pure function that changes an input after its base family, as `edgeStep` does. */
+export interface CorpusStep {
+  readonly name: string;
+  readonly version: number;
+  /** The engine that owns the definition of the step. */
+  readonly owner: string;
+  readonly meaning: string;
+  /** The dimensions of the step. Their names are not names of the dimensions of the base family. */
+  readonly dimensions: readonly CorpusDimension[];
+  /** The text of the rule that gives the random numbers of the step from the seed. */
+  readonly seeding: string;
+  readonly crossEngine: CrossEngine;
+  /** This function gives the part of the family of the input that tells the values of the step. Without it, the family does not change. */
+  readonly familyPart?: (dims: DimensionValues) => string;
+  /** This function gives the changed input. It removes the old `hash` of the input. */
+  apply(input: LayoutInput, seed: number, dims: DimensionValues): LayoutInput;
+}
+/** The options of `composeFamily`. */
+export interface ComposeOptions {
+  /** The default is the name of the base family and the names of the steps, with `+` between them. */
+  readonly name?: string;
+  /** The default is the owner of the base family. */
+  readonly owner?: string;
+  readonly meaning?: string;
+  /** The hash of the composed input. The default is `documentHash` of `hash.ts`. */
+  readonly hash?: (input: LayoutInput) => string;
+}
+/**
+ * This function gives a family that runs the base family and then each step, with the same seed.
+ * The family of the input gets the part of each step after a dot. The id becomes `<set>/<family>/s<seed>`, and the input gets the hash of `options.hash`.
+ * The function throws a `RangeError` when a step has a dimension with the name of an earlier dimension.
+ */
+export declare function composeFamily(base: CorpusFamily<LayoutInput>, steps: readonly CorpusStep[], options?: ComposeOptions): CorpusFamily<LayoutInput>;
+/**
+ * The step `edges` of `edgeStep` (version 1), as a corpus step. Its family part is `e-<edgeDensity>.<edgeShape>.<groups>.<ports>`.
+ * The value `random` of `hubBy` adds the part `.hub-random`.
+ */
+export declare const EDGES_STEP: CorpusStep;
+/**
+ * The shared family `rect-scattered`, version 1: a fixed rectangle container, rectangle obstacles at random places and boxes without positions.
+ * It is the one copy of the generator of `docs/FORMAT.md` of `packing`. Its input is the input of `packing`, byte for byte.
+ * The steps `container`, `obstacles` and `boxes` each have a stream of `stepRandom`. Each value is a whole number, so the family is `exact`.
+ */
+export declare const RECT_SCATTERED: CorpusFamily<LayoutInput>;
 //# sourceMappingURL=index.d.ts.map