@mark1russell7/layout-contract 0.2.14 → 0.2.16

package/build/index.js

@@ -73,6 +73,28 @@ function boundsOf(region) {
 		}
 	}
 }
+/**
+* This function gives the exact area of a region. A `rect` gives `w` by `h`, a circle gives `PI * r * r`, and an ellipse gives `PI * rx * ry`.
+* A polygon gives the absolute value of the shoelace formula, less the area of each hole. A ring with fewer than 3 points has the area 0.
+*/
+function regionArea(region) {
+	switch (region.kind) {
+		case "rect": return region.w * region.h;
+		case "circle": return Math.PI * region.r * region.r;
+		case "ellipse": return Math.PI * region.rx * region.ry;
+		case "polygon": return (region.holes ?? []).reduce((area, hole) => area - ringArea(hole), ringArea(region.points));
+	}
+}
+/** This function gives the area of one ring of a polygon: the absolute value of the shoelace formula. */
+function ringArea(ring) {
+	let twice = 0;
+	for (let i = 0; i < ring.length; i++) {
+		const [ax, ay] = ring[i];
+		const [bx, by] = ring[(i + 1) % ring.length];
+		twice += ax * by - bx * ay;
+	}
+	return Math.abs(twice) / 2;
+}
 /** This function gives the region moved by `dx` and `dy`. */
 function translate(region, dx, dy) {
 	switch (region.kind) {
@@ -111,7 +133,10 @@ function overlapOf(a, b) {
 	};
 }
 // src/shapes.ts
-/** The declared shape kinds, in their order. Only `rect` has all of its geometry. The other kinds have their bounding box only. */
+/**
+* The declared shape kinds, in their order. Only `rect` has all of its geometry.
+* `polygon` and `circle` have their bounding box and their exact area. `free` has its bounding box only.
+*/
 const SHAPE_KINDS = Object.freeze([
 	{
 		id: "rect",
@@ -130,7 +155,7 @@ const SHAPE_KINDS = Object.freeze([
 		regions: ["polygon"],
 		geometry: {
 			bounds: true,
-			area: false,
+			area: true,
 			contains: false,
 			overlap: false
 		}
@@ -145,7 +170,7 @@ const SHAPE_KINDS = Object.freeze([
 		regions: ["circle"],
 		geometry: {
 			bounds: true,
-			area: false,
+			area: true,
 			contains: false,
 			overlap: false
 		}
@@ -175,6 +200,35 @@ const SHAPE_KINDS = Object.freeze([
 const SHAPE_KIND_IDS = 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. */
 const DEFAULT_SHAPES = Object.freeze(["rect"]);
+/** This function gives the level of a rule on a shape kind. A kind of `shapesOf` is `exact`, a kind of `safe` is `safe`, and another kind is `none`. */
+function ruleLevel(rule, kind) {
+	if (shapesOf(rule).includes(kind)) return "exact";
+	return rule.safe?.includes(kind) === true ? "safe" : "none";
+}
+/**
+* This function gives the problems of a list of measures and rules. An empty list tells that the list is good.
+* It refuses an unknown kind, a kind two times in one list, and a kind in `safe` that is also in `shapesOf`.
+*/
+function shapeSupportProblems(uses) {
+	const out = [];
+	for (const use of uses) {
+		for (const [name, list] of [["shapes", use.shapes], ["safe", use.safe]]) {
+			if (list === void 0) continue;
+			if (!Array.isArray(list)) {
+				out.push(`${use.id}: the ${name} value is not a list of shape kinds`);
+				continue;
+			}
+			list.forEach((k, i) => {
+				if (!isShapeKind(k)) out.push(`${use.id}: the ${name} kind ${String(k)} is not a declared kind`);
+				else if (list.indexOf(k) !== i) out.push(`${use.id}: the ${name} list has the kind ${k} two times`);
+			});
+		}
+		if (!Array.isArray(use.safe)) continue;
+		const exact = use.shapes === void 0 ? DEFAULT_SHAPES : Array.isArray(use.shapes) ? use.shapes : [];
+		for (const k of new Set(use.safe)) if (exact.includes(k)) out.push(`${use.id}: the kind ${String(k)} is in shapes and in safe`);
+	}
+	return out;
+}
 const REGION_KIND = {
 	rect: "rect",
 	polygon: "polygon",
@@ -193,6 +247,18 @@ function shapeKindOf(box) {
 	if (box.shapeKind !== void 0) return box.shapeKind;
 	return box.shape === void 0 ? "rect" : REGION_KIND[box.shape.kind];
 }
+/**
+* This function gives the exact area of a box, or `undefined` when the contract knows only its bounding box.
+* A box with `shape` gives `regionArea` of the shape. A `rect` box without `shape` gives `w` by `h`.
+* A box of the kind `free` gives `undefined`, also with a shape. Thus a box with an ellipse shape gives `undefined`, because `shapeKindOf` makes an ellipse `free`.
+* A box of another kind without `shape` is a bad input, and gives `undefined`.
+*/
+function boxArea(box) {
+	const kind = shapeKindOf(box);
+	if (kind === "free") return void 0;
+	if (box.shape !== void 0) return regionArea(box.shape);
+	return kind === "rect" ? box.w * box.h : void 0;
+}
 /** 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. */
 function shapeKindsOf(input) {
 	const seen = new Set(input.boxes.map(shapeKindOf));
@@ -219,19 +285,22 @@ function shapesOf(use) {
 /**
 * 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.
+* By default, a kind of `safe` is a break, because the count of the rule is not exact. With the level `safe`, it is not a break.
 */
-function checkShapes(input, uses) {
+function checkShapes(input, uses, options = {}) {
 	const kinds = shapeKindsOf(input);
 	const out = [];
 	for (const use of uses) {
 		const shapes = shapesOf(use);
 		for (const kind of kinds) {
-			if (shapes.includes(kind)) continue;
+			const level = ruleLevel(use, kind);
+			if (level === "exact" || level === "safe" && options.level === "safe") 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` : "");
+			const safe = level === "safe" ? `. The count of ${use.id} on ${kind} is only safe` : "";
 			out.push({
 				claim: "shape",
-				detail: `${use.id} supports only the shape kinds ${shapes.join(", ") || "(none)"}, but the input ${input.id} has ${kind} boxes: ${shown}`,
+				detail: `${use.id} supports only the shape kinds ${shapes.join(", ") || "(none)"}, but the input ${input.id} has ${kind} boxes: ${shown}${safe}`,
 				inputs: [input.id]
 			});
 		}
@@ -260,6 +329,36 @@ const DEFAULT_TOLERANCE = Object.freeze({
 	through: .5
 });
 // src/input.ts
+/**
+* This function gives the point of a port on the border of its box, relative to the top-left corner of the box.
+* A port with `x` and `y` gives that point. A port with `side` and `along` gives the point at that fraction of the side.
+* Another port gives `undefined`, because the router picks its point.
+*/
+function portPoint(box, port) {
+	if (port.x !== void 0 && port.y !== void 0) return {
+		x: port.x,
+		y: port.y
+	};
+	if (port.side === void 0 || port.along === void 0) return void 0;
+	switch (port.side) {
+		case "top": return {
+			x: port.along * box.w,
+			y: 0
+		};
+		case "bottom": return {
+			x: port.along * box.w,
+			y: box.h
+		};
+		case "left": return {
+			x: 0,
+			y: port.along * box.h
+		};
+		case "right": return {
+			x: box.w,
+			y: port.along * box.h
+		};
+	}
+}
 /** This function gives the packer input of a file. An input without a container gets `{ fixed: "none" }`, so the packer picks the size. */
 function toPackInput(input) {
 	return {
@@ -271,7 +370,7 @@ function toPackInput(input) {
 	};
 }
 /** This function compares two strings by their UTF-16 code units, as `Array.prototype.sort` does without a compare function. */
-const byCode = (x, y) => x < y ? -1 : x > y ? 1 : 0;
+const byCode$1 = (x, y) => x < y ? -1 : x > y ? 1 : 0;
 /**
 * 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`.
@@ -279,11 +378,11 @@ const byCode = (x, y) => x < y ? -1 : x > y ? 1 : 0;
 */
 function canonicalInput(input) {
 	if (!Array.isArray(input.pairGaps)) return input;
-	const pairGaps = input.pairGaps.map((p) => byCode(p.a, p.b) > 0 ? {
+	const pairGaps = input.pairGaps.map((p) => byCode$1(p.a, p.b) > 0 ? {
 		...p,
 		a: p.b,
 		b: p.a
-	} : p).sort((x, y) => byCode(x.a, y.a) || byCode(x.b, y.b));
+	} : p).sort((x, y) => byCode$1(x.a, y.a) || byCode$1(x.b, y.b));
 	return {
 		...input,
 		pairGaps
@@ -298,14 +397,20 @@ function turnSide(side) {
 function turnPoint(x, y, h) {
 	return [h - y, x];
 }
-/** This function gives a port of a box of height `h` after the turn. Each value of the port turns, also a port with only `x` or only `y`. */
+/**
+* This function gives a port of a box of height `h` after the turn. Each value of the port turns, also a port with only `x` or only `y`.
+* The start of a side is its top end or its left end. Thus `left` goes to `top` and `right` goes to `bottom` with `along` changed to `1 - along`.
+* `top` goes to `right` and `bottom` goes to `left` with the same `along`.
+*/
 function turnPort(port, h) {
-	const { side, x, y, ...rest } = port;
+	const { side, x, y, along, ...rest } = port;
+	const flips = side === "left" || side === "right";
 	return {
 		...rest,
 		...side === void 0 ? {} : { side: turnSide(side) },
 		...y === void 0 ? {} : { x: h - y },
-		...x === void 0 ? {} : { y: x }
+		...x === void 0 ? {} : { y: x },
+		...along === void 0 ? {} : { along: flips ? 1 - along : along }
 	};
 }
 /** This function gives a margin after the turn: the value of each side moves one side clockwise. */
@@ -549,16 +654,27 @@ function countPortsOffBorder(boxes, eps = RECORD_EPS) {
 /**
 * 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`.
+* For the other kinds, the count is safe: a shape is inside its bounding box, so the count is an upper bound. A count of 0 tells that the rule has no break.
 * `locked-kept` and `complete` read only the positions and the ids, so they support each kind.
 */
 const PACK_HARD_RULES = Object.freeze([
 	{
 		id: "no-overlap",
-		shapes: ["rect"]
+		shapes: ["rect"],
+		safe: [
+			"polygon",
+			"circle",
+			"free"
+		]
 	},
 	{
 		id: "in-container",
-		shapes: ["rect"]
+		shapes: ["rect"],
+		safe: [
+			"polygon",
+			"circle",
+			"free"
+		]
 	},
 	{
 		id: "locked-kept",
@@ -764,6 +880,7 @@ function packHard(input, output, tolerance = DEFAULT_TOLERANCE.overlap, options
 * 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.
+* A port with `along` and no `side`, with `x` or `y`, or with a value outside [0, 1] is a problem.
 */
 function checkInput(input) {
 	const problems = [];
@@ -775,12 +892,23 @@ function checkInput(input) {
 		if (box.locked === true && (box.x === void 0 || box.y === void 0)) problems.push(`box ${box.id}: a locked box has no position`);
 		const shape = shapeKindProblem(box);
 		if (shape !== void 0) problems.push(shape);
+		for (const port of box.ports ?? []) problems.push(...alongProblems(box.id, port));
 	}
 	if (countPortsOffBorder(input.boxes) > 0) problems.push("a fixed port is not on the border of its box");
 	for (const edge of input.edges ?? []) if (!ids.has(edge.source) || !ids.has(edge.target)) problems.push(`edge ${edge.id}: a box of the edge is not in the input`);
 	problems.push(...pairGapProblems(input.pairGaps, ids));
 	return problems;
 }
+/** This function gives the problems of the `along` of a port: no side, a value outside [0, 1], or `x` or `y` with it. A port without `along` has no problem. */
+function alongProblems(boxId, port) {
+	if (port.along === void 0) return [];
+	const at = `box ${boxId} port ${port.id}`;
+	const problems = [];
+	if (port.side === void 0) problems.push(`${at}: a port with along has no side`);
+	if (typeof port.along !== "number" || !Number.isFinite(port.along) || port.along < 0 || port.along > 1) problems.push(`${at}: the along value ${String(port.along)} is not a finite number from 0 to 1`);
+	if (port.x !== void 0 || port.y !== void 0) problems.push(`${at}: a port with along also has x or y`);
+	return problems;
+}
 /** This function gives the problems of the `pairGaps` of an input. `ids` has the ids of the boxes. */
 function pairGapProblems(pairGaps, ids) {
 	if (pairGaps === void 0) return [];
@@ -2037,6 +2165,8 @@ function optionProblems(stage, o) {
 		if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || min > max || typeof ordered !== "boolean") out.push(["members", `${at} has a member rule without whole counts 1 <= min <= max and a boolean ordered`]);
 		const pool = o.members.pool;
 		if (pool !== void 0 && (!Array.isArray(pool) || pool.length === 0 || !pool.every((entry) => Array.isArray(entry)))) out.push(["pool", `${at} has a pool that is not a list of one or more member lists`]);
+		const view = o.members.view;
+		if (view !== void 0 && view !== "bounds") out.push(["view", `${at} has the member view ${show(view)}, not "bounds"`]);
 	}
 	return out;
 }
@@ -2055,6 +2185,15 @@ function supportsProblems(supports, at) {
 }
 /** This function tells if an option supports each shape kind of the list. */
 const supportsShapes = (o, shapes) => shapes === void 0 || o.supports?.shape === void 0 || shapes.every((k) => o.supports.shape.includes(k));
+/** The shape kinds that the members of an option with `view: "bounds"` see: a bounding box is a `rect`. */
+const BOUNDS_VIEW = Object.freeze(["rect"]);
+/**
+* This function gives the shape kinds of the members of a meta option. With `view: "bounds"`, a list with a kind becomes `BOUNDS_VIEW`.
+* Without a list, or with an empty list, the value does not change.
+*/
+const memberShapes = (rule, shapes) => rule.view === "bounds" && shapes !== void 0 && shapes.length > 0 ? BOUNDS_VIEW : shapes;
+/** This function tells if two lists have the same shape kinds. */
+const sameKinds = (a, b) => a.every((k) => b.includes(k)) && b.every((k) => a.includes(k));
 /** This function gives the problems of the params of one stage choice. */
 function choiceParamProblems(o, params, at) {
 	if (params !== void 0 && !isObject(params)) return [["config", `the params of ${at} are not an object`]];
@@ -2128,7 +2267,7 @@ function configProblems(space, config, member, shapes) {
 			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, shapes));
+		out.push(...memberProblems(partOf(space, s.name).space, o.members, c["members"], at, memberShapes(o.members, shapes)));
 	}
 	for (const c of space.constraints ?? []) if (!holds(c, chosen)) out.push(["constraint", `the config breaks the constraint ${describe(c)}`]);
 	return out;
@@ -2191,6 +2330,7 @@ const toBreaks = (problems, inputs = []) => problems.map(([claim, detail]) => ({
 *
 * 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.
+* A member of an option with `view: "bounds"` gets the check with the kind `rect`.
 */
 function checkConfig(space, config, options = {}) {
 	return toBreaks(configProblems(space, config, false, options.shapes));
@@ -2451,7 +2591,9 @@ function combos(space, levels, meta, limit) {
 	for (const s of stages) for (const o of s.options) {
 		if (o.members === void 0) continue;
 		const choices = new Map(stages.map((x) => [x.name, x === s ? o : null]));
-		const lists = o.members.pool === void 0 ? memberLists(base, o.members, limit) : BigInt(o.members.pool.length);
+		const own = memberSpaces.get(o);
+		const from = own === void 0 ? base : baseCount(own, levels, limit);
+		const lists = o.members.pool === void 0 ? memberLists(from, o.members, limit) : BigInt(o.members.pool.length);
 		if (keeps(space, choices)) out.push({
 			choices,
 			base: false,
@@ -2476,6 +2618,8 @@ function spaceSize(space, options) {
 * 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.
 * A pool keeps only the entries whose members fit the smaller space. A meta option without such an entry goes out.
+*
+* The members of an option with `view: "bounds"` come from the space for the kinds of `memberShapes`. `memberSpaces` keeps that space.
 */
 function restrict(space, shapes) {
 	if (shapes === void 0) return space;
@@ -2488,16 +2632,23 @@ function restrict(space, shapes) {
 		...space.parts === void 0 ? {} : { parts: space.parts.map((p) => restrict(p, shapes)) }
 	};
 	const withPool = (s, o) => {
-		if (o.members?.pool === void 0) return [o];
-		const part = partOf(kept, s.name).space;
+		if (o.members === void 0) return [o];
+		const inner = memberShapes(o.members, shapes);
+		const own = sameKinds(inner, shapes) ? void 0 : restrict(partOf(space, s.name).space, inner);
+		const mark = (option) => {
+			if (own !== void 0) memberSpaces.set(option, own);
+			return [option];
+		};
+		if (o.members.pool === void 0) return own === void 0 ? [o] : mark({ ...o });
+		const part = own ?? partOf(kept, s.name).space;
 		const pool = o.members.pool.filter((entry) => fits(part, entry));
-		return pool.length === 0 ? [] : [{
+		return pool.length === 0 ? [] : mark({
 			...o,
 			members: {
 				...o.members,
 				pool
 			}
-		}];
+		});
 	};
 	return {
 		...kept,
@@ -2507,6 +2658,10 @@ function restrict(space, shapes) {
 		}))
 	};
 }
+/** The space of the members of a meta option of a restricted space, when it is not the part of the option. Only `view: "bounds"` makes such a space. */
+const memberSpaces = /* @__PURE__ */ new WeakMap();
+/** This function gives the count of the base configs of a space that is known to be good. */
+const baseCount = (space, levels, limit) => combos(space, levels, false, limit).reduce((sum, c) => sum + c.weight, 0n);
 /** This function throws a `RangeError` for a list of shape kinds with a kind that is not declared. */
 function assertShapes(shapes) {
 	if (shapes === void 0) return;
@@ -2583,13 +2738,18 @@ function sampleValue(p, u) {
 }
 /** This function gives a seed of 32 bits from a seed and a step name. */
 const subSeed = (seed, step) => Math.floor(stepRandom(seed, step)() * 4294967296);
-/** This function gives a sample of a space: Latin hypercube strata over the options, the params and the member counts. */
-function sampleConfigs(space, n, seed, meta, maxTries) {
+/**
+* This function gives a sample of a space: Latin hypercube strata over the options, the params and the member counts.
+* `canon` is the space of `canonicalConfig`: the space before a shape filter. A member of an option with `view: "bounds"` can have an option that the filter removed.
+*/
+function sampleConfigs(space, n, seed, meta, maxTries, canon = space) {
 	const stages = space.stages;
 	const prefix = prefixes(space);
+	const bounded = new Set(stages.filter((s) => meta && s.options.some((o) => memberSpaces.has(o))).map((s) => prefix.get(s.name)));
 	const lists = stages.map((s) => {
 		const list = s.options.filter((o) => meta || o.members === void 0);
 		if (s.optional) list.push(null);
+		if (list.length === 0 && bounded.has(prefix.get(s.name))) 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;
 	});
@@ -2608,7 +2768,7 @@ function sampleConfigs(space, n, seed, meta, maxTries) {
 				const m = metaPart.get(prefix.get(s.name));
 				if (m !== void 0 && m !== s.name) choices.set(s.name, null);
 			}
-			if (keeps(space, choices)) points.push(choices);
+			if (stages.every((s) => s.optional === true || choices.get(s.name) !== null || metaPart.has(prefix.get(s.name))) && keeps(space, choices)) points.push(choices);
 		}
 	}
 	const values = points.map(() => stages.map(() => ({})));
@@ -2633,7 +2793,7 @@ function sampleConfigs(space, n, seed, meta, maxTries) {
 				});
 				continue;
 			}
-			const part = partOf(space, s.name).space;
+			const part = memberSpaces.get(o) ?? partOf(space, s.name).space;
 			const poolSize = Math.max(n, 4 * o.members.max, 8);
 			const seen = /* @__PURE__ */ new Set();
 			const pool = sampleConfigs(part, poolSize, subSeed(seed, `pool:${s.name}:${o.id}`), false, Math.max(1e3, 100 * poolSize)).filter((c) => {
@@ -2663,7 +2823,7 @@ function sampleConfigs(space, n, seed, meta, maxTries) {
 				members: members[i][k]
 			};
 		});
-		return canonicalConfig(space, {
+		return canonicalConfig(canon, {
 			space: space.engine,
 			stages: out
 		});
@@ -2691,7 +2851,7 @@ function enumerateSpace(space, options) {
 	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(restrict(space, options.shapes), options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1e3, 100 * options.n));
+	return sampleConfigs(restrict(space, options.shapes), options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1e3, 100 * options.n), space);
 }
 /**
 * 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.
@@ -2993,6 +3153,8 @@ function verdict(records, options) {
 	};
 }
 // src/families.ts
+/** The name of the output field that lists the fields that `generate` of a registry removed. */
+const INVALIDATED_FIELD = "invalidated";
 /** The random numbers of the default factory: `mulberry32` of `random.ts`. Its stream is pinned in `families.test.ts`. */
 const DEFAULT_RNG = mulberry32;
 /** 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. */
@@ -3141,15 +3303,135 @@ const CORPUS_DIMENSIONS = Object.freeze({
 		value: 0
 	}, "The free space between two items, in units.", [P, J])
 });
-/** This function gives a dimension of `CORPUS_DIMENSIONS`, with the fields of `patch` over it. It throws a `RangeError` for an unknown name. */
+/**
+* This function gives a dimension of `CORPUS_DIMENSIONS`, with the fields of `patch` over it. It throws a `RangeError` for an unknown name.
+* With `supported`, `invalidates` or `precision` in the patch, it also throws a `RangeError` for a bad dimension, as `ownerDimension` does.
+*/
 function sharedDimension(name, patch = {}) {
 	const base = Object.hasOwn(CORPUS_DIMENSIONS, name) ? CORPUS_DIMENSIONS[name] : void 0;
 	if (base === void 0) throw new RangeError(`The shared dimension table has no dimension "${name}".`);
-	return Object.freeze({
+	const dim = Object.freeze({
 		...base,
 		...patch,
 		name
 	});
+	if (patch.supported !== void 0 || patch.invalidates !== void 0 || patch.precision !== void 0) throwProblems(`sharedDimension: the dimension "${name}"`, ownProblems(dim));
+	return dim;
+}
+/**
+* This function gives a dimension that only its owner declares, for example `cut` of a family of `packing`.
+* It throws a `RangeError` for a name of `CORPUS_DIMENSIONS`, the reserved name `kind`, or a bad default, level, `supported`, `invalidates` or `precision`.
+* The registry examines the `when` of the dimension, because it needs the earlier dimensions.
+*/
+function ownerDimension(name, spec) {
+	const where = `ownerDimension: the dimension "${name}"`;
+	if (typeof name !== "string" || name === "") throw new RangeError("ownerDimension: the name of a dimension is a text that is not empty.");
+	if (name === "kind") throw new RangeError(`${where} has a reserved name: the cell of \`cellOf\` has the \`familyKind\` of the family in \`kind\`.`);
+	if (Object.hasOwn(CORPUS_DIMENSIONS, name)) throw new RangeError(`${where} is in the shared dimension table. Use sharedDimension("${name}") for it.`);
+	const dim = Object.freeze({
+		...spec,
+		name
+	});
+	throwProblems(where, ownProblems(dim));
+	return dim;
+}
+/** This function throws a `RangeError` with each problem of a list. An empty list throws nothing. */
+function throwProblems(where, problems) {
+	if (problems.length > 0) throw new RangeError(`${where} is not good: ${problems.join("; ")}.`);
+}
+/** This function tells if a value of the stable form of a dimension is in its `supported` values. Without `supported`, each value is in them. */
+function inSupported(dim, value) {
+	const s = dim.supported;
+	if (s === void 0) return true;
+	if (isSupportedList(s)) return s.some((v) => paramValue(dim, v) === value);
+	if (typeof value !== "number") return false;
+	return (s.min === void 0 || value >= s.min) && (s.max === void 0 || value <= s.max);
+}
+/** This function tells if `SupportedValues` has the list form. */
+const isSupportedList = (s) => Array.isArray(s);
+/**
+* This function tells if a family accepts a value of a dimension. A site uses it to show the values that a family does not support.
+* It gives `false` for a bad value, and for a value outside `supported`. Without `supported`, it gives `true` for each good value.
+*/
+function dimensionSupports(dim, value) {
+	if (paramProblem(dim, value) !== void 0) return false;
+	return inSupported(dim, paramValue(dim, value));
+}
+/** This function gives the text of the supported values of a dimension, for a message. */
+function supportedText(dim) {
+	const s = dim.supported;
+	if (s === void 0) return "each value";
+	if (isSupportedList(s)) return s.map((v) => JSON.stringify(v)).join(", ");
+	return `the values from ${s.min ?? dim.min} to ${s.max ?? dim.max}`;
+}
+/** This function gives the problems of one dimension that need no other dimension: the default, the levels, `supported`, `invalidates` and `precision`. */
+function ownProblems(d) {
+	const out = [];
+	const bad = paramProblem(d, d.default);
+	if (bad !== void 0) out.push(`the default of "${d.name}" is bad: ${bad}`);
+	for (const v of d.levels ?? []) {
+		const p = paramProblem(d, v);
+		if (p !== void 0) out.push(`a level of "${d.name}" is bad: ${p}`);
+	}
+	out.push(...supportProblems(d, bad === void 0));
+	out.push(...invalidatesProblems(d));
+	out.push(...precisionProblems(d));
+	return out;
+}
+/** This function gives the problems of the `supported` values of a dimension. `goodDefault` tells that the default is a good value. */
+function supportProblems(d, goodDefault) {
+	const s = d.supported;
+	if (s === void 0) return [];
+	const out = [];
+	const numeric = d.kind === "int" || d.kind === "real";
+	if (isSupportedList(s)) {
+		if (numeric) return [`the supported values of "${d.name}" are a range with min and max, because the dimension is numeric`];
+		if (s.length === 0) return [`the supported values of "${d.name}" are an empty list`];
+		for (const v of s) {
+			const p = paramProblem(d, v);
+			if (p !== void 0) out.push(`a supported value of "${d.name}" is bad: ${p}`);
+		}
+		if (new Set(s).size !== s.length) out.push(`the supported values of "${d.name}" have a value two times`);
+	} else {
+		if (s === null || typeof s !== "object") return [`the supported values of "${d.name}" are a list or a range`];
+		if (!numeric) return [`the supported values of "${d.name}" are a list, because the dimension is not numeric`];
+		for (const end of [s.min, s.max]) {
+			if (end === void 0) continue;
+			const p = paramProblem(d, end);
+			if (p !== void 0) out.push(`an end of the supported range of "${d.name}" is bad: ${p}`);
+		}
+		if (s.min !== void 0 && s.max !== void 0 && s.min > s.max) out.push(`the supported range of "${d.name}" has a min above its max`);
+	}
+	if (out.length > 0) return out;
+	if (goodDefault && !inSupported(d, paramValue(d, d.default))) out.push(`the default of "${d.name}" is not a supported value`);
+	for (const v of d.levels ?? []) if (paramProblem(d, v) === void 0 && !inSupported(d, paramValue(d, v))) out.push(`the level ${JSON.stringify(v)} of "${d.name}" is not a supported value`);
+	return out;
+}
+/** This function gives the problems of the `invalidates` fields of a dimension. */
+function invalidatesProblems(d) {
+	const list = d.invalidates;
+	if (list === void 0) return [];
+	if (!Array.isArray(list) || !list.every((f) => typeof f === "string" && f !== "")) return [`the invalidates of "${d.name}" is not a list of field names`];
+	const out = [];
+	if (new Set(list).size !== list.length) out.push(`the invalidates of "${d.name}" has a field two times`);
+	for (const f of ["hash", INVALIDATED_FIELD]) if (list.includes(f)) out.push(`the invalidates of "${d.name}" has the field "${f}", which the registry writes`);
+	return out;
+}
+/** This function gives the problems of the `precision` of a dimension. A bad value and a dimension that is not numeric are problems. */
+function precisionProblems(d) {
+	const p = d.precision;
+	if (p === void 0) return [];
+	if (typeof p !== "number" || !Number.isInteger(p) || p < 0) return [`the precision of "${d.name}" is ${JSON.stringify(p)}, not a whole number of 0 or more`];
+	if (d.kind !== "int" && d.kind !== "real") return [`the precision of "${d.name}" is for a numeric dimension, but the dimension is a ${d.kind}`];
+	return [];
+}
+/** This function rounds a number to `places` decimal places: `Math.round(v * 10 ** places) / 10 ** places`. */
+const roundTo = (v, places) => Math.round(v * 10 ** places) / 10 ** places;
+/** This function tells if a value is the default of a dimension. With `precision`, it compares the two numbers after it rounds them. */
+function isDefault(d, value) {
+	const def = paramValue(d, d.default);
+	if (d.precision === void 0 || typeof value !== "number" || typeof def !== "number") return value === def;
+	return roundTo(value, d.precision) === roundTo(def, d.precision);
 }
 /** This function tells if a log scale of a range starts at 0. Then the scale is the log of `1 + x - min`. */
 const fromZero = (d) => d.scale === "log" && (d.min ?? 0) <= 0;
@@ -3178,30 +3460,45 @@ function dimensionUnit(dim, value) {
 	if (fromZero(dim)) return Math.log1p(v - min) / Math.log1p(max - min);
 	return (Math.log(v) - Math.log(min)) / (Math.log(max) - Math.log(min));
 }
+/** This function gives the range of the supported values of a numeric dimension: its own `min` and `max` in place of the ends of `supported`. */
+function supportedSpan(dim) {
+	const s = dim.supported;
+	const range = s === void 0 || isSupportedList(s) ? {} : s;
+	return {
+		min: range.min ?? dim.min,
+		max: range.max ?? dim.max
+	};
+}
 /**
 * 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.
+* With `supported`, an `enum` and a `bool` give only the supported values, and the points of a numeric dimension stay in the supported range.
 */
 function levelsOf(dim, steps) {
 	if (dim.levels !== void 0) return [...dim.levels];
-	if (dim.kind === "enum" || dim.kind === "bool" || steps === void 0) return paramLevels(dim, 1);
+	if (dim.kind === "enum" || dim.kind === "bool") return paramLevels(dim, 1).filter((v) => inSupported(dim, paramValue(dim, v)));
+	if (steps === void 0) return paramLevels(dim, 1);
+	if (dim.supported !== void 0) {
+		const { supported: _supported, ...rest } = dim;
+		const span = supportedSpan(dim);
+		return levelsOf({
+			...rest,
+			...span.min === void 0 ? {} : { min: span.min },
+			...span.max === void 0 ? {} : { max: span.max }
+		}, steps);
+	}
 	if (!fromZero(dim)) return paramLevels(dim, steps);
 	if (!Number.isInteger(steps) || steps < 1) throw new RangeError(`The steps of a sweep are a whole number of 1 or more, not ${steps}.`);
 	if (steps === 1) return [paramValue(dim, dim.default)];
 	return [...new Set(Array.from({ length: steps }, (_, j) => dimensionAt(dim, j / (steps - 1))))];
 }
-/** This function gives the problems of the dimensions of a family: a repeated name, a bad default, a bad level or a bad `when`. */
+/** This function gives the problems of the dimensions of a family: a repeated name, a bad default, level, `supported`, `invalidates` or `when`. */
 function dimensionProblems(dims) {
 	const out = [];
 	const names = dims.map((d) => d.name);
 	dims.forEach((d, i) => {
 		if (names.indexOf(d.name) !== i) out.push(`the dimension "${d.name}" is in the list two times`);
-		const bad = paramProblem(d, d.default);
-		if (bad !== void 0) out.push(`the default of "${d.name}" is bad: ${bad}`);
-		for (const v of d.levels ?? []) {
-			const p = paramProblem(d, v);
-			if (p !== void 0) out.push(`a level of "${d.name}" is bad: ${p}`);
-		}
+		out.push(...ownProblems(d));
 		if (d.when === void 0) return;
 		const j = names.indexOf(d.when.param);
 		if (j < 0 || j >= i) out.push(`the when of "${d.name}" names "${d.when.param}", which is not an earlier dimension`);
@@ -3213,9 +3510,11 @@ function dimensionProblems(dims) {
 /**
 * 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.
+* It also throws a `RangeError` for a value outside `supported`, with the text "not supported by" and `by`.
 */
-function resolveDimensions(dimensions, dims = {}, where = "The family") {
+function resolveDimensions(dimensions, dims = {}, where = "The family", by = "the family") {
 	const known = new Set(dimensions.map((d) => d.name));
 	for (const key of Object.keys(dims)) if (!known.has(key)) throw new RangeError(`${where} has no dimension "${key}".`);
 	const active = {};
@@ -3225,6 +3524,7 @@ function resolveDimensions(dimensions, dims = {}, where = "The family") {
 		if (given !== void 0) {
 			const bad = paramProblem(d, given);
 			if (bad !== void 0) throw new RangeError(`${where}: the dimension "${d.name}" is bad: ${bad}.`);
+			if (!inSupported(d, paramValue(d, given))) throw new RangeError(`${where}: the value ${JSON.stringify(given)} of the dimension "${d.name}" is not supported by ${by}. The supported values are ${supportedText(d)}.`);
 		}
 		const on = paramActive(d, active);
 		const value = paramValue(d, on && given !== void 0 ? given : d.default);
@@ -3274,7 +3574,7 @@ function countOf(dimensions, levels, i = 0, values = {}) {
 	return sum;
 }
 /** This function gives the levels of each dimension of a sweep. A dimension outside the sweep has `undefined`, so it keeps its default. */
-function sweepLevels(dimensions, options, where) {
+function sweepLevels(dimensions, options, where, by) {
 	const names = new Set(dimensions.map((d) => d.name));
 	for (const name of [...options.sweep ?? [], ...Object.keys(options.levels ?? {})]) if (!names.has(name)) throw new RangeError(`${where} has no dimension "${name}".`);
 	return dimensions.map((d) => {
@@ -3283,10 +3583,49 @@ function sweepLevels(dimensions, options, where) {
 		for (const v of lv) {
 			const bad = paramProblem(d, v);
 			if (bad !== void 0) throw new RangeError(`${where}: a level of "${d.name}" is bad: ${bad}.`);
+			if (!inSupported(d, paramValue(d, v))) throw new RangeError(`${where}: the level ${JSON.stringify(v)} of "${d.name}" is not supported by ${by}.`);
 		}
 		return lv;
 	});
 }
+/**
+* This function gives the output fields that the values make wrong: the `invalidates` of each dimension with a value other than its default, sorted.
+* A dimension with `precision` compares the rounded value with the rounded default.
+*/
+function invalidFields(dimensions, full) {
+	const out = /* @__PURE__ */ new Set();
+	for (const d of dimensions) {
+		if (d.invalidates === void 0 || d.invalidates.length === 0) continue;
+		if (!isDefault(d, full[d.name])) for (const f of d.invalidates) out.add(f);
+	}
+	return [...out].sort(byCode);
+}
+/** This function compares two strings by their UTF-16 code units. */
+const byCode = (x, y) => x < y ? -1 : x > y ? 1 : 0;
+/**
+* This function removes the fields of `fields` from an output, and adds their names to its field `invalidated`, sorted.
+* Only a field of the output counts. The `hash` of text gets the value of `hash` again. An output with none of the fields is the same object.
+*/
+function dropFields(output, fields, hash, where) {
+	if (fields.length === 0) return output;
+	if (output === null || typeof output !== "object" || Array.isArray(output)) throw new RangeError(`${where} invalidates the fields ${fields.join(", ")}, but its output is not an object.`);
+	const o = output;
+	const dropped = fields.filter((f) => Object.hasOwn(o, f));
+	if (dropped.length === 0) return output;
+	const before = o[INVALIDATED_FIELD];
+	const prior = Array.isArray(before) ? before.filter((f) => typeof f === "string") : [];
+	const body = {};
+	for (const key of Object.keys(o)) if (key !== "hash" && key !== "invalidated" && !dropped.includes(key)) body[key] = o[key];
+	body[INVALIDATED_FIELD] = [.../* @__PURE__ */ new Set([...prior, ...dropped])].sort(byCode);
+	if (typeof o["hash"] !== "string") return Object.hasOwn(o, "hash") ? {
+		...body,
+		hash: o["hash"]
+	} : body;
+	return {
+		...body,
+		hash: hash(body)
+	};
+}
 /** This function gives the values that make a dimension active: the first value of its `when`, and the values that make that dimension active. */
 function activation(dimensions, dim) {
 	const out = {};
@@ -3322,6 +3661,8 @@ function createFamilyRegistry(families = []) {
 		const { kind: _kind, ...rest } = dims;
 		return rest;
 	};
+	/** This function gives the full dimension values of an input of `f`. A message names the family as `familyKind` gives it. */
+	const resolveIn = (f, dims) => resolveDimensions(f.dimensions, dims, label(f), familyKind(f.name, f.version));
 	const streamOf = (f, seed, full) => {
 		const rng = f.rng ?? DEFAULT_RNG;
 		return {
@@ -3348,46 +3689,49 @@ function createFamilyRegistry(families = []) {
 		families: () => [...list],
 		resolve(name, dims, version) {
 			const f = find(name, version);
-			return resolveDimensions(f.dimensions, ownDims(f, dims), label(f));
+			return resolveIn(f, ownDims(f, dims));
 		},
 		generate(name, seed, dims, options = {}) {
 			checkSeed(seed);
 			const f = find(name, options.version);
-			const full = resolveDimensions(f.dimensions, ownDims(f, dims), label(f));
+			const full = resolveIn(f, ownDims(f, dims));
 			const context = {
 				...streamOf(f, seed, full),
 				...options.set === void 0 ? {} : { set: options.set }
 			};
-			return f.generate(seed, full, context);
+			const output = f.generate(seed, full, context);
+			const hash = f.hash ?? documentHash;
+			return dropFields(output, invalidFields(f.dimensions, full), hash, label(f));
 		},
 		cellOf(name, dims, version) {
 			const f = find(name, version);
 			return {
 				kind: familyKind(f.name, f.version),
-				...activeValues(f.dimensions, resolveDimensions(f.dimensions, ownDims(f, dims), label(f)))
+				...activeValues(f.dimensions, resolveIn(f, ownDims(f, dims)))
 			};
 		},
 		*cells(name, options = {}) {
 			const f = find(name, options.version);
-			for (const values of sweepOf(f.dimensions, sweepLevels(f.dimensions, options, label(f)))) yield resolveDimensions(f.dimensions, values, label(f));
+			for (const values of sweepOf(f.dimensions, sweepLevels(f.dimensions, options, label(f), familyKind(f.name, f.version)))) yield resolveIn(f, values);
 		},
 		cellCount(name, options = {}) {
 			const f = find(name, options.version);
-			return countOf(f.dimensions, sweepLevels(f.dimensions, options, label(f)));
+			return countOf(f.dimensions, sweepLevels(f.dimensions, options, label(f), familyKind(f.name, f.version)));
 		},
 		boundaryCells(name, version) {
 			const f = find(name, version);
-			const base = resolveDimensions(f.dimensions, {}, label(f));
+			const base = resolveIn(f, {});
 			const out = [base];
 			const seen = /* @__PURE__ */ new Set([JSON.stringify(base)]);
 			for (const d of f.dimensions) {
 				if (d.kind !== "int" && d.kind !== "real") continue;
-				for (const end of [d.min, d.max]) {
+				const span = supportedSpan(d);
+				for (const end of [span.min, span.max]) {
 					if (end === void 0) continue;
-					const cell = resolveDimensions(f.dimensions, {
+					const cell = resolveIn(f, {
 						...activation(f.dimensions, d),
 						[d.name]: end
-					}, label(f));
+					});
 					const key = JSON.stringify(cell);
 					if (!seen.has(key)) {
 						seen.add(key);
@@ -3401,7 +3745,7 @@ function createFamilyRegistry(families = []) {
 			const f = find(name, version);
 			return (seed, dims) => {
 				checkSeed(seed);
-				return streamOf(f, seed, resolveDimensions(f.dimensions, ownDims(f, dims), label(f))).random;
+				return streamOf(f, seed, resolveIn(f, ownDims(f, dims))).random;
 			};
 		},
 		familyBy() {
@@ -3440,6 +3784,7 @@ function composeFamily(base, steps, options = {}) {
 		...base.rng === void 0 ? {} : { rng: base.rng },
 		...base.rngSeed === void 0 ? {} : { rngSeed: (seed, full) => base.rngSeed(seed, pick(base.dimensions, full)) },
 		...base.familyBy === void 0 ? {} : { familyBy: base.familyBy },
+		...options.hash === void 0 ? {} : { hash: options.hash },
 		generate(seed, full, context) {
 			let input = base.generate(seed, pick(base.dimensions, full), context);
 			const parts = [];
@@ -3582,6 +3927,6 @@ const RECT_SCATTERED = Object.freeze({
 		};
 	}
 });
-export { CORPUS_DIMENSIONS, DEFAULT_FAMILY_BY, DEFAULT_RNG, DEFAULT_SHAPES, DEFAULT_TOLERANCE, EDGES_STEP, EDGE_DENSITY, EDGE_STEP_VERSION, EPS, FAMILY_ANY_KIND, JOINT_MEASURES, JOINT_MOVED_MIN, PACK_HARD_RULES, RECORD_EPS, RECORD_SCALE, RECT_SCATTERED, SHAPE_KINDS, SHAPE_KIND_IDS, SIDES, SPLIT_SCHEMA, STRATEGY_SPACE_SCHEMA, VERDICT_DRAWS, VERDICT_EXACT_CAP, VERDICT_EXACT_MAX, VERDICT_RUNS, VERDICT_SEED, applyPack, boundsOf, canonicalConfig, canonicalInput, canonicalJson, checkConfig, checkDeclared, checkInput, checkShapes, checkSpace, checkSplit, compareMeasure, composeFamily, configId, corpusHashOf, countObstacleHits, countOutside, countOverlaps, countPortsOffBorder, createFamilyRegistry, declaredClaimOf, declaredCounts, dimensionAt, dimensionUnit, documentHash, edgeStep, enumerateSpace, exercised, familyKind, familyOf, fnv1a32, grow, isShapeKind, itemShapeOf, joinConfigs, leaveOneSeedOut, levelsOf, marginSides, minEffectOf, mulberry32, outputGroups, outputHash, overlapOf, packHard, paramActive, paramLevels, paramProblem, paramValue, pickMoves, placedRect, portfolio, productSpace, randomInt, rectInRegion, regionHitsRect, resolveDimensions, selectBest, sha256Hex, shapeKindOf, shapeKindProblem, shapeKindsOf, shapesOf, sharedDimension, spaceShapeKinds, spaceSize, splitConfig, splitFileName, splitFolds, stepRandom, toLayoutRecord, toPackInput, translate, turnBox, turnMargin, turnPoint, turnPort, turnRegion, turnSide, verdict };
+export { CORPUS_DIMENSIONS, DEFAULT_FAMILY_BY, DEFAULT_RNG, DEFAULT_SHAPES, DEFAULT_TOLERANCE, EDGES_STEP, EDGE_DENSITY, EDGE_STEP_VERSION, EPS, FAMILY_ANY_KIND, INVALIDATED_FIELD, JOINT_MEASURES, JOINT_MOVED_MIN, PACK_HARD_RULES, RECORD_EPS, RECORD_SCALE, RECT_SCATTERED, SHAPE_KINDS, SHAPE_KIND_IDS, SIDES, SPLIT_SCHEMA, STRATEGY_SPACE_SCHEMA, VERDICT_DRAWS, VERDICT_EXACT_CAP, VERDICT_EXACT_MAX, VERDICT_RUNS, VERDICT_SEED, applyPack, boundsOf, boxArea, canonicalConfig, canonicalInput, canonicalJson, checkConfig, checkDeclared, checkInput, checkShapes, checkSpace, checkSplit, compareMeasure, composeFamily, configId, corpusHashOf, countObstacleHits, countOutside, countOverlaps, countPortsOffBorder, createFamilyRegistry, declaredClaimOf, declaredCounts, dimensionAt, dimensionSupports, dimensionUnit, documentHash, edgeStep, enumerateSpace, exercised, familyKind, familyOf, fnv1a32, grow, isShapeKind, itemShapeOf, joinConfigs, leaveOneSeedOut, levelsOf, marginSides, minEffectOf, mulberry32, outputGroups, outputHash, overlapOf, ownerDimension, packHard, paramActive, paramLevels, paramProblem, paramValue, pickMoves, placedRect, portPoint, portfolio, productSpace, randomInt, rectInRegion, regionArea, regionHitsRect, resolveDimensions, ruleLevel, selectBest, sha256Hex, shapeKindOf, shapeKindProblem, shapeKindsOf, shapeSupportProblems, shapesOf, sharedDimension, spaceShapeKinds, spaceSize, splitConfig, splitFileName, splitFolds, stepRandom, toLayoutRecord, toPackInput, translate, turnBox, turnMargin, turnPoint, turnPort, turnRegion, turnSide, verdict };
 
 //# sourceMappingURL=index.js.map