@mark1russell7/layout-contract 0.2.11 → 0.2.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/layout-contract",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "The shared contract of the packing and highways layout engines: the input and record formats, the turn rule, margins, tolerances and hard rules.",
   "keywords": [
     "layout",

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./geometry.ts";
+export * from "./shapes.ts";
 export * from "./tolerance.ts";
 export * from "./input.ts";
 export * from "./output.ts";

package/src/input.ts

@@ -1,4 +1,5 @@
 import type { Margin, Region, Side } from "./geometry.ts";
+import type { ShapeKind } from "./shapes.ts";
 
 /**
  * A port of a box: a place where edges go into the box.
@@ -28,6 +29,11 @@ export interface LayoutBox {
   readonly group?: string;
   /** A region relative to the origin of the box. Without it, the box is the rectangle `w` by `h`. */
   readonly shape?: Region;
+  /**
+   * The shape kind of the box (`docs/SHAPES.md`). Without it, `shapeKindOf` gives the kind of `shape`, or `rect` without a shape.
+   * The kind `free` tells that the contract knows only the bounding box `w` by `h`.
+   */
+  readonly shapeKind?: ShapeKind;
   readonly ports?: readonly Port[];
   /** A ring around the box. No other box enters it. Only a route from a port of the box enters it, at a right angle. */
   readonly margin?: Margin;
@@ -92,6 +98,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`. */

package/src/measures.ts

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

package/src/record.ts

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

package/src/rules.ts

@@ -1,6 +1,7 @@
 import { boundsOf, grow, overlapOf, type Rect, type Region } from "./geometry.ts";
 import type { LayoutBox, LayoutInput, Obstacle } from "./input.ts";
 import { applyPack, type PackOutput } from "./output.ts";
+import { SHAPE_KIND_IDS, shapeKindProblem, type ShapeSupport } from "./shapes.ts";
 import { DEFAULT_TOLERANCE, EPS, RECORD_EPS } from "./tolerance.ts";
 
 /** This function gives the area of a placed box: its shape or its rectangle, at its position. A box without a position gives `undefined`. */
@@ -96,6 +97,18 @@ export interface PackHard {
   readonly complete: number;
 }
 
+/**
+ * The hard rules of a pack, with the shape kinds that each rule supports.
+ * `no-overlap` and `in-container` test the bounding box of a shape. That count is exact only for a `rect`.
+ * `locked-kept` and `complete` read only the positions and the ids, so they support each kind.
+ */
+export const PACK_HARD_RULES: readonly ShapeSupport<keyof PackHard>[] = Object.freeze([
+  { id: "no-overlap", shapes: ["rect"] },
+  { id: "in-container", shapes: ["rect"] },
+  { id: "locked-kept", shapes: SHAPE_KIND_IDS },
+  { id: "complete", shapes: SHAPE_KIND_IDS },
+] as const);
+
 /** This function tells if the inside of `region` and the inside of `rect` have a common point. */
 export function regionHitsRect(region: Region, rect: Rect): boolean {
   if (rect.w <= 0 || rect.h <= 0) return false;
@@ -314,6 +327,8 @@ export function checkInput(input: LayoutInput): readonly string[] {
     ids.add(box.id);
     if (!(box.w > 0 && box.h > 0 && Number.isFinite(box.w) && Number.isFinite(box.h))) problems.push(`box ${box.id}: the size is not positive and finite`);
     if (box.locked === true && (box.x === undefined || box.y === undefined)) problems.push(`box ${box.id}: a locked box has no position`);
+    const shape = shapeKindProblem(box);
+    if (shape !== undefined) problems.push(shape);
   }
   if (countPortsOffBorder(input.boxes) > 0) problems.push("a fixed port is not on the border of its box");
   for (const edge of input.edges ?? []) {

package/src/shapes.ts

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

package/src/strategy-space.ts

@@ -2,6 +2,7 @@
 import type { ClaimBreak } from "./corpus.ts";
 import { canonicalJson, sha256Hex } from "./hash.ts";
 import { stepRandom } from "./random.ts";
+import { isShapeKind, SHAPE_KIND_IDS, type ShapeKind } from "./shapes.ts";
 
 /** The schema of a strategy space. */
 export const STRATEGY_SPACE_SCHEMA = "strategy-space/1";
@@ -47,11 +48,25 @@ export interface MemberRule {
   readonly ordered: boolean;
 }
 
+/** 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. */
@@ -113,7 +128,7 @@ export interface SpaceSize {
 }
 
 /** 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`. */
@@ -121,7 +136,7 @@ export interface SpaceSizeOptions {
 }
 
 /** 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. */
@@ -129,7 +144,7 @@ export interface GridOptions {
 }
 
 /** 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;
@@ -271,6 +286,7 @@ function optionProblems(stage: SpaceStage, o: StageOption): Problem[] {
       if (problem !== undefined) out.push(["when", `${pat} has a when value that is not a value of ${p.when.param}: ${problem}`]);
     }
   });
+  if (o.supports !== undefined) out.push(...supportsProblems(o.supports, at));
   if (o.members !== undefined) {
     const { min, max, ordered } = o.members;
     if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || min > max || typeof ordered !== "boolean")
@@ -279,6 +295,24 @@ function optionProblems(stage: SpaceStage, o: StageOption): Problem[] {
   return out;
 }
 
+/** This function gives the problems of the `supports` of an option. */
+function supportsProblems(supports: unknown, at: string): Problem[] {
+  if (!isObject(supports)) return [["shape", `the supports of ${at} are not an object`]];
+  const shape = supports["shape"];
+  if (shape === undefined) return [];
+  if (!Array.isArray(shape) || shape.length === 0) return [["shape", `${at} supports no shape kind. Remove shape to support each kind`]];
+  const out: Problem[] = [];
+  shape.forEach((k: unknown, i) => {
+    if (!isShapeKind(k)) out.push(["shape", `${at} supports the shape kind ${show(k)}, which is not one of ${SHAPE_KIND_IDS.join(", ")}`]);
+    else if (shape.indexOf(k) !== i) out.push(["duplicate", `${at} has the shape kind ${k} two times`]);
+  });
+  return out;
+}
+
+/** This function tells if an option supports each shape kind of the list. */
+const supportsShapes = (o: StageOption, shapes: readonly ShapeKind[] | undefined): boolean =>
+  shapes === undefined || o.supports?.shape === undefined || shapes.every((k) => o.supports!.shape!.includes(k));
+
 /** This function gives the problems of the params of one stage choice. */
 function choiceParamProblems(o: StageOption, params: unknown, at: string): Problem[] {
   if (params !== undefined && !isObject(params)) return [["config", `the params of ${at} are not an object`]];
@@ -301,7 +335,7 @@ function choiceParamProblems(o: StageOption, params: unknown, at: string): Probl
 }
 
 /** This function gives the problems of a config of a space. A member of a meta option has `member: true`. */
-function configProblems(space: StrategySpace, config: unknown, member: boolean): Problem[] {
+function configProblems(space: StrategySpace, config: unknown, member: boolean, shapes?: readonly ShapeKind[]): Problem[] {
   if (!isObject(config) || !isObject(config["stages"])) return [["config", "the config is not an object with stages"]];
   const out: Problem[] = [];
   const stages = config["stages"];
@@ -339,6 +373,10 @@ function configProblems(space: StrategySpace, config: unknown, member: boolean):
     }
     chosen.set(s.name, o.id);
     const at = `the option ${s.name}.${o.id}`;
+    if (!supportsShapes(o, shapes)) {
+      const missing = shapes!.filter((k) => !o.supports!.shape!.includes(k));
+      out.push(["shape", `${at} supports the shape kinds ${o.supports!.shape!.join(", ")}, not ${missing.join(", ")}`]);
+    }
     if (meta !== undefined && meta !== s.name) out.push(["meta", `the stage ${s.name} is set, but the meta option of ${meta} replaces the other stages of its part`]);
     out.push(...choiceParamProblems(o, c["params"], at));
     if (o.members === undefined) {
@@ -349,20 +387,20 @@ function configProblems(space: StrategySpace, config: unknown, member: boolean):
       out.push(["depth", `a member has the meta option ${s.name}.${o.id}. The depth of a meta config is 1`]);
       continue;
     }
-    out.push(...memberProblems(partOf(space, s.name).space, o.members, c["members"], at));
+    out.push(...memberProblems(partOf(space, s.name).space, o.members, c["members"], at, shapes));
   }
   for (const c of space.constraints ?? []) if (!holds(c, chosen)) out.push(["constraint", `the config breaks the constraint ${describe(c)}`]);
   return out;
 }
 
 /** This function gives the problems of the members of a meta option. `part` is the space of the members. */
-function memberProblems(part: StrategySpace, rule: MemberRule, members: unknown, at: string): Problem[] {
+function memberProblems(part: StrategySpace, rule: MemberRule, members: unknown, at: string, shapes?: readonly ShapeKind[]): Problem[] {
   if (!Array.isArray(members)) return [["members", `${at} is a meta option without a list of members`]];
   const out: Problem[] = [];
   if (members.length < rule.min || members.length > rule.max) out.push(["members", `${at} has ${members.length} members, not ${rule.min} to ${rule.max}`]);
   const ids = new Map<string, number>();
   members.forEach((m: unknown, k) => {
-    const inner = configProblems(part, m, true);
+    const inner = configProblems(part, m, true, shapes);
     for (const [claim, detail] of inner) out.push([claim, `the member ${k} of ${at}: ${detail}`]);
     if (inner.length > 0) return;
     const id = idOf(canonicalOf(part, m as StrategyConfig, true));
@@ -377,9 +415,10 @@ const toBreaks = (problems: readonly Problem[], inputs: readonly string[] = []):
 /**
  * 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`.
+ * 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 function checkConfig(space: StrategySpace, config: StrategyConfig): ClaimBreak[] {
-  return toBreaks(configProblems(space, config, false));
+export function checkConfig(space: StrategySpace, config: StrategyConfig, options: ShapeFilter = {}): ClaimBreak[] {
+  return toBreaks(configProblems(space, config, false, options.shapes));
 }
 
 /**
@@ -646,14 +685,40 @@ function combos(space: StrategySpace, levels: number, meta: boolean, limit: bigi
 /**
  * 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.
+ * With `shapes`, it counts only the options that support each kind of the list.
  */
 export function spaceSize(space: StrategySpace, options: SpaceSizeOptions): SpaceSize {
   assertSpace(space);
   assertWhole(options.levels, "levels", 1);
-  const limit = options.maxMeta ?? 10n ** 18n;
+  assertShapes(options.shapes);
+  return sizeOf(restrict(space, options.shapes), options.levels, options.maxMeta ?? 10n ** 18n);
+}
+
+/**
+ * This function gives the space with only the options that support each shape kind of `shapes`. Without `shapes`, it gives the same space.
+ * A stage can lose all of its options. Then the space has no config with that stage.
+ */
+function restrict(space: StrategySpace, shapes: readonly ShapeKind[] | undefined): StrategySpace {
+  if (shapes === undefined) return space;
+  return {
+    ...space,
+    stages: space.stages.map((s) => ({ ...s, options: s.options.filter((o) => supportsShapes(o, shapes)) })),
+    ...(space.parts === undefined ? {} : { parts: space.parts.map((p) => restrict(p, shapes)) }),
+  };
+}
+
+/** This function throws a `RangeError` for a list of shape kinds with a kind that is not declared. */
+function assertShapes(shapes: readonly ShapeKind[] | undefined): void {
+  if (shapes === undefined) return;
+  if (!Array.isArray(shapes)) throw new RangeError("The option shapes is not a list of shape kinds.");
+  for (const k of shapes) if (!isShapeKind(k)) throw new RangeError(`The shape kind ${show(k)} is not one of ${SHAPE_KIND_IDS.join(", ")}.`);
+}
+
+/** This function gives the count of the grid points of a space that is known to be good. */
+function sizeOf(space: StrategySpace, levels: number, limit: bigint): SpaceSize {
   let base = 0n;
   let meta: bigint | null = 0n;
-  for (const c of combos(space, options.levels, true, limit)) {
+  for (const c of combos(space, levels, true, limit)) {
     if (c.base) base += c.weight!;
     else meta = meta === null || c.weight === null || meta + c.weight > limit ? null : meta + c.weight;
   }
@@ -674,11 +739,12 @@ function* product<T>(lists: readonly (readonly T[])[], i = 0, acc: T[] = []): Ge
 }
 
 /** This function gives the configs of the grid of a space, without meta options. */
-function gridConfigs(space: StrategySpace, levels: number, limit: number): StrategyConfig[] {
-  const size = spaceSize(space, { levels, maxMeta: 0n }).base;
+function gridConfigs(space: StrategySpace, levels: number, limit: number, shapes: readonly ShapeKind[] | undefined): StrategyConfig[] {
+  const kept = restrict(space, shapes);
+  const size = sizeOf(kept, levels, 0n).base;
   if (size > BigInt(limit)) throw new RangeError(`The grid of the space ${space.engine} has ${size} configs, more than the limit ${limit}.`);
   const out: StrategyConfig[] = [];
-  for (const c of combos(space, levels, false, 0n)) {
+  for (const c of combos(kept, levels, false, 0n)) {
     const names = [...c.choices.keys()];
     const lists = names.map((k) => {
       const o = c.choices.get(k)!;
@@ -724,6 +790,7 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
   const lists = stages.map((s) => {
     const list: (StageOption | null)[] = s.options.filter((o) => meta || o.members === undefined);
     if (s.optional) list.push(null);
+    if (list.length === 0) throw new Error(`The stage ${s.name} of the space ${space.engine} has no option for a sample. A shape filter can remove all of its options.`);
     return list;
   });
   const points: Map<string, StageOption | null>[] = [];
@@ -794,12 +861,14 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
  * - 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.
  */
 export function enumerateSpace(space: StrategySpace, options: EnumerateOptions): StrategyConfig[] {
   assertSpace(space);
+  assertShapes(options.shapes);
   if (options.mode === "grid") {
     assertWhole(options.levels, "levels", 1);
-    return gridConfigs(space, options.levels, options.limit ?? 100_000);
+    return gridConfigs(space, options.levels, options.limit ?? 100_000, options.shapes);
   }
   if (options.mode !== "sample") throw new RangeError(`The mode ${String((options as { mode?: unknown }).mode)} is not grid or sample.`);
   assertWhole(options.n, "n", 0);
@@ -807,7 +876,16 @@ export function enumerateSpace(space: StrategySpace, options: EnumerateOptions):
   const meta = options.meta ?? "skip";
   if (meta !== "skip" && meta !== "sample") throw new RangeError(`The option meta is ${String(meta)}, not skip or sample.`);
   if (options.n === 0) return [];
-  return sampleConfigs(space, options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1000, 100 * options.n));
+  return sampleConfigs(restrict(space, options.shapes), options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1000, 100 * options.n));
+}
+
+/**
+ * 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 function spaceShapeKinds(space: StrategySpace): ShapeKind[] {
+  assertSpace(space);
+  return SHAPE_KIND_IDS.filter((k) => sizeOf(restrict(space, [k]), 1, 0n).base > 0n);
 }
 
 /**

package/src/verdict.ts

@@ -91,6 +91,25 @@ export interface VerdictSignTest {
 /** The label of a verdict. `better` and `worse` tell the side of `b`. */
 export type VerdictLabel = "better" | "worse" | "depends on the mix" | "no verdict";
 
+/**
+ * The scope of a verdict. The test keeps the families of the corpus as fixed, so its claim is about these families only.
+ * It is not a claim about a new kind of input.
+ */
+export type VerdictScope = "these families";
+
+/**
+ * The breadth of a verdict: the count of the families against its side.
+ * The side is the side of the label. For `depends on the mix` and `no verdict`, it is the sign of the stratified mean.
+ */
+export interface VerdictBreadth {
+  /** The count of the families with a sign against the side. A stratified mean of exactly 0 has no side, so this count is 0. */
+  readonly against: number;
+  /** The count of the families. */
+  readonly of: number;
+  /** The count of the families with the sign 0. */
+  readonly ties: number;
+}
+
 /** The result of `verdict`. */
 export interface VerdictResult {
   readonly measure: string;
@@ -107,6 +126,12 @@ export interface VerdictResult {
   /** `true` only when the two means have the same sign, the two intervals are clear of 0 and the permutation p is below `level`. */
   readonly agree: boolean;
   readonly label: VerdictLabel;
+  /** The scope of the claim: the families of the corpus, not a new kind of input. */
+  readonly scope: VerdictScope;
+  /** The count of the families against the side of the verdict, of all the families and of the ties. */
+  readonly breadth: VerdictBreadth;
+  /** The label, the scope and the breadth in one line, for example `better on these families, worse on 2 of 6 (1 tie)`. */
+  readonly summary: string;
   /** The inputs without a pair: one side has no record, a skipped record or no value of the measure. */
   readonly dropped: readonly string[];
 }
@@ -154,6 +179,24 @@ function signP(wins: number, losses: number): number {
   return Math.min(1, (2 * tail) / 2 ** n);
 }
 
+/** This function gives the breadth of a verdict with the side `side`: 1, -1, or 0 for no side. */
+function breadthOf(families: readonly FamilyVerdict[], side: number): VerdictBreadth {
+  const ties = families.filter((f) => f.sign === 0).length;
+  const against = side === 0 ? 0 : families.filter((f) => f.sign === -side).length;
+  return { against, of: families.length, ties };
+}
+
+/** This function gives the line of a verdict: its label, its scope and its breadth (`docs/VERDICT.md`). */
+function summaryOf(label: VerdictLabel, side: number, breadth: VerdictBreadth): string {
+  const ties = breadth.ties === 0 ? "" : ` (${breadth.ties} ${breadth.ties === 1 ? "tie" : "ties"})`;
+  const word = side > 0 ? "better" : "worse";
+  const other = side > 0 ? "worse" : "better";
+  const count = breadth.against === 0 ? "none" : String(breadth.against);
+  if (label === "better" || label === "worse") return `${label} on these families, ${other} on ${count} of ${breadth.of}${ties}`;
+  if (side === 0) return `${label}: the family mean is 0, on ${breadth.of} families${ties}`;
+  return `${label}: ${word} on the family mean, ${other} on ${count} of ${breadth.of}${ties}`;
+}
+
 /** This function tells if a value is a positive whole number. */
 const isCount = (v: number): boolean => Number.isInteger(v) && v > 0;
 
@@ -206,6 +249,7 @@ function pairsOf<R extends VerdictRecord>(records: Iterable<R>, options: Verdict
  * - `stratified` is the mean of the family means. Its bootstrap draws the seeds inside each family. `pooled` is the mean of the inputs.
  * - The permutation test changes the sign of each difference inside its family. Its statistic is the mean of the family means.
  * - The label is `better` or `worse` only when `agree` is `true`. Opposite signs of the two means give `depends on the mix`.
+ * - `scope`, `breadth` and `summary` tell that the claim is about these families, and how many families are against it.
  *
  * 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`.
  */
@@ -292,5 +336,7 @@ export function verdict<R extends VerdictRecord>(records: Iterable<R>, options:
   const sign = Math.sign(stratified.mean);
   const agree = sign !== 0 && sign === Math.sign(pooled.mean) && clearOn(stratified, sign) && clearOn(pooled, sign) && permutation.p < level;
   const label: VerdictLabel = agree ? (sign > 0 ? "better" : "worse") : sign * Math.sign(pooled.mean) < 0 ? "depends on the mix" : "no verdict";
-  return { measure: measure.id, n, stratified, pooled, permutation, families, signTest, agree, label, dropped };
+  const breadth = breadthOf(families, sign);
+  const summary = summaryOf(label, sign, breadth);
+  return { measure: measure.id, n, stratified, pooled, permutation, families, signTest, agree, label, scope: "these families", breadth, summary, dropped };
 }