@mark1russell7/highways 0.2.0 → 0.3.0

package/src/strategies/builtins.ts

@@ -1,19 +1,27 @@
 import { arcCurve, type ArcOptions } from "../curves/arc/index.ts";
+import { clothoidCurve, type ClothoidOptions } from "../curves/clothoid/index.ts";
+import { highwayCurve, type JogStyle } from "../curves/highway/index.ts";
 import { roundedCurve, type RoundedOptions } from "../curves/rounded/index.ts";
+import { smoothCurve, type SmoothOptions } from "../curves/smooth/index.ts";
 import { splineCurve, type SplineOptions } from "../curves/spline/index.ts";
 import { straightCurve } from "../curves/straight/index.ts";
+import { CUT_DEFAULTS, cutGroups, type CutOptions } from "../groups/cut/index.ts";
+import { KD_DEFAULTS, kdGroups, type KdOptions } from "../groups/kd/index.ts";
 import { byDataGroup, keyGroups, type KeyOptions } from "../groups/keys/index.ts";
 import { quadtreeGroups } from "../groups/quadtree/index.ts";
 import type { Graph, Result, Router } from "../model.ts";
 import { roomDemand, type RoomMethod, type RoomOptions } from "../room/index.ts";
+import { levelRoom, type LevelRoomOptions } from "../room/levels/index.ts";
 import { cornersRouter, type CornersOptions } from "../routers/corners.ts";
 import { plugsRouter } from "../routers/plugs.ts";
 import { sectionsRouter, type SectionsOptions } from "../routers/sections.ts";
 import { sharedRouter, type SharedOptions } from "../routers/shared.ts";
 import { straightRouter } from "../routers/straight.ts";
 import { byCollection, trunksRouter, type TrunksOptions } from "../routers/trunks.ts";
-import { SECTION_DEFAULTS, type SectionOptions } from "../sections.ts";
+import { buildSections, SECTION_DEFAULTS, type SectionOptions } from "../sections.ts";
 import { createRegistry, defineStrategy, type AnyStrategy, type CurveInput, type Registry, type Strategy } from "./model.ts";
+import type { OptionSchema } from "./options.ts";
+import { CLOTHOID_SCHEMA, CORNERS_SCHEMA, CUT_SCHEMA, HIGHWAY_SCHEMA, KD_SCHEMA, KEY_SCHEMA, LEVEL_ROOM_SCHEMA, RADIUS_SCHEMA, ROOM_SCHEMA, SECTION_SCHEMA, SECTIONS_SCHEMA, SHARED_SCHEMA, SMOOTH_SCHEMA, TENSION_SCHEMA, TRUNKS_SCHEMA } from "./schemas.ts";
 
 /** The options of a router strategy: the options of its router, without the name and the limit of the benchmark. */
 export type RouterPreset<O> = Omit<O, "name" | "maxNodes">;
@@ -25,13 +33,14 @@ function routerStrategy<O extends object>(
   maxNodes: number,
   defaults: O,
   make: (options: O & { readonly name: string }) => Router,
+  schema: OptionSchema<O>,
 ): Strategy<"router", O> {
-  return defineStrategy({ step: "router", name, describe, defaults, maxNodes, run: (graph: Graph, options: Readonly<O>): Result => make({ ...options, name }).route(graph) });
+  return defineStrategy({ step: "router", name, describe, defaults, schema, maxNodes, run: (graph: Graph, options: Readonly<O>): Result => make({ ...options, name }).route(graph) });
 }
 
 /** This function makes a router strategy for a router without options. */
 function fixedRouter(router: Router, describe: string): Strategy<"router", object> {
-  return defineStrategy({ step: "router", name: router.name, describe, defaults: {}, run: (graph: Graph): Result => router.route(graph) });
+  return defineStrategy({ step: "router", name: router.name, describe, defaults: {}, schema: {}, run: (graph: Graph): Result => router.route(graph) });
 }
 
 /** The built-in router strategies, in the order of the benchmark. They route as the routers of `ROUTERS`. */
@@ -57,6 +66,7 @@ export const routerStrategies: {
     10_000,
     {},
     cornersRouter,
+    CORNERS_SCHEMA,
   ),
   "corners-smooth": routerStrategy<RouterPreset<CornersOptions>>(
     "corners-smooth",
@@ -64,6 +74,7 @@ export const routerStrategies: {
     10_000,
     { smooth: true },
     cornersRouter,
+    CORNERS_SCHEMA,
   ),
   trunks: routerStrategy<RouterPreset<TrunksOptions>>(
     "trunks",
@@ -71,6 +82,7 @@ export const routerStrategies: {
     10_000,
     { rule: byCollection },
     trunksRouter,
+    TRUNKS_SCHEMA,
   ),
   shared: routerStrategy<RouterPreset<SharedOptions>>(
     "shared",
@@ -78,14 +90,16 @@ export const routerStrategies: {
     10_000,
     { rule: byCollection },
     sharedRouter,
+    SHARED_SCHEMA,
   ),
-  "shared-all": routerStrategy<RouterPreset<SharedOptions>>("shared-all", "The same as `shared`, but all edges share their ways.", 10_000, {}, sharedRouter),
+  "shared-all": routerStrategy<RouterPreset<SharedOptions>>("shared-all", "The same as `shared`, but all edges share their ways.", 10_000, {}, sharedRouter, SHARED_SCHEMA),
   sections: routerStrategy<RouterPreset<SectionsOptions>>(
     "sections",
     "A tree of sections, with a hub in each section. A long edge goes through the hubs, and a short edge goes directly.",
     100_000,
     {},
     sectionsRouter,
+    SECTIONS_SCHEMA,
   ),
   "sections-tree": routerStrategy<RouterPreset<SectionsOptions>>(
     "sections-tree",
@@ -93,6 +107,7 @@ export const routerStrategies: {
     100_000,
     { stretch: Infinity },
     sectionsRouter,
+    SECTIONS_SCHEMA,
   ),
 });
 
@@ -115,19 +130,56 @@ export interface TensionOptions {
   readonly tension: number;
 }
 
-/** The built-in curve strategies, in the order of `CURVE_TYPES`. Each one gives the same segments as `curveOf` with its type. */
+/** The options of the curve strategy `highway`. */
+export interface HighwayStrategyOptions {
+  /** The radius of the center line of a bundle at a bend, and of each lone corner. The default is 12. */
+  readonly radius: number;
+  /** The smallest radius of a lane at a bend of a bundle. The default is 4. */
+  readonly minRadius: number;
+  /** The shape of the S curve where a lane changes its offset. The default is `biarc`. */
+  readonly jog: JogStyle;
+  /** The number of cubic pieces of a `quintic` S curve. The default is 4. */
+  readonly jogPieces: number;
+}
+
+/** The options of the curve strategy `smooth`. */
+export interface SmoothStrategyOptions {
+  /** The radius of the arc of each corner. The default is 12. */
+  readonly radius: number;
+  /** The share of the turn of a corner in its two spirals, from 0 to 1. The default is 0.6. */
+  readonly smoothing: number;
+}
+
+/** The options of the curve strategy `clothoid`. */
+export interface ClothoidStrategyOptions {
+  /** The radius of the arc of each corner. The default is 12. */
+  readonly radius: number;
+  /** The share of the turn of a corner in its two clothoids, from 0 to 1. The default is 0.5. */
+  readonly spiral: number;
+  /** The largest distance from the cubic pieces to the true clothoid. The default is 0.25. */
+  readonly tolerance: number;
+}
+
+/**
+ * The built-in curve strategies. The first six are in the order of `CURVE_TYPES`, and each one gives the same segments as `curveOf` with its type.
+ * The strategy `highway` gives the curve of `arc` for one polyline. `highwayCurves` bends the lanes of a bundle as one.
+ */
 export const curveStrategies: {
   readonly straight: Strategy<"curve", object>;
   readonly rounded: Strategy<"curve", RadiusOptions>;
   readonly spline: Strategy<"curve", TensionOptions>;
   readonly arc: Strategy<"curve", RadiusOptions>;
+  readonly smooth: Strategy<"curve", SmoothStrategyOptions>;
+  readonly clothoid: Strategy<"curve", ClothoidStrategyOptions>;
+  readonly highway: Strategy<"curve", HighwayStrategyOptions>;
 } = Object.freeze({
-  straight: defineStrategy({ step: "curve", name: "straight", describe: "The polyline as it is.", defaults: {}, run: (input: CurveInput) => straightCurve(input.points) }),
+  straight: defineStrategy({ step: "curve", name: "straight", describe: "The polyline as it is.", defaults: {}, schema: {}, run: (input: CurveInput) => straightCurve(input.points) }),
   rounded: defineStrategy({
     step: "curve",
     name: "rounded",
     describe: "A quadratic Bezier curve at each corner, as `roundCorners` draws it. The first and the last legs stay.",
     defaults: { radius: 12 },
+    schema: RADIUS_SCHEMA,
     run: (input: CurveInput, o: Readonly<RadiusOptions>) => roundedCurve(input.points, { ...contextOf(input), radius: o.radius } satisfies RoundedOptions),
   }),
   spline: defineStrategy({
@@ -135,6 +187,7 @@ export const curveStrategies: {
     name: "spline",
     describe: "A centripetal Catmull-Rom spline through each point. It does not overshoot or make loops in a piece.",
     defaults: { tension: 0 },
+    schema: TENSION_SCHEMA,
     run: (input: CurveInput, o: Readonly<TensionOptions>) => splineCurve(input.points, { ...contextOf(input), tension: o.tension } satisfies SplineOptions),
   }),
   arc: defineStrategy({
@@ -142,35 +195,86 @@ export const curveStrategies: {
     name: "arc",
     describe: "A circular arc at each corner, tangent to the two legs. The first and the last legs stay.",
     defaults: { radius: 12 },
+    schema: RADIUS_SCHEMA,
     run: (input: CurveInput, o: Readonly<RadiusOptions>) => arcCurve(input.points, { ...contextOf(input), radius: o.radius } satisfies ArcOptions),
   }),
+  smooth: defineStrategy({
+    step: "curve",
+    name: "smooth",
+    describe: "A cubic spiral, an arc and a second cubic spiral at each corner, as the corner smoothing of Figma. The curvature has no jump.",
+    defaults: { radius: 12, smoothing: 0.6 },
+    schema: SMOOTH_SCHEMA,
+    run: (input: CurveInput, o: Readonly<SmoothStrategyOptions>) =>
+      smoothCurve(input.points, { ...(input.space ? { space: input.space } : {}), radius: o.radius, smoothing: o.smoothing } satisfies SmoothOptions),
+  }),
+  clothoid: defineStrategy({
+    step: "curve",
+    name: "clothoid",
+    describe: "A clothoid, an arc and a second clothoid at each corner, as a transition curve of a road. Cubic pieces draw each clothoid.",
+    defaults: { radius: 12, spiral: 0.5, tolerance: 0.25 },
+    schema: CLOTHOID_SCHEMA,
+    run: (input: CurveInput, o: Readonly<ClothoidStrategyOptions>) =>
+      clothoidCurve(input.points, {
+        ...(input.space ? { space: input.space } : {}),
+        radius: o.radius,
+        spiral: o.spiral,
+        tolerance: o.tolerance,
+      } satisfies ClothoidOptions),
+  }),
+  highway: defineStrategy({
+    step: "curve",
+    name: "highway",
+    describe: "The lanes of a bundle bend as one, with concentric arcs at the lane spacing. One lane alone gets the curve of `arc`.",
+    defaults: { radius: 12, minRadius: 4, jog: "biarc" as JogStyle, jogPieces: 4 },
+    schema: HIGHWAY_SCHEMA,
+    run: (input: CurveInput, o: Readonly<HighwayStrategyOptions>) => highwayCurve(input.points, { radius: o.radius, ...(input.space ? { space: input.space } : {}) }),
+  }),
 });
 
 /** The options of a room strategy: the options of `roomDemand`, without the method. */
 export type RoomPreset = Omit<RoomOptions, "method">;
 
 const roomStrategy = (method: RoomMethod, describe: string): Strategy<"room", RoomPreset> =>
-  defineStrategy<"room", RoomPreset>({ step: "room", name: method, describe, defaults: {}, run: (input, o) => roomDemand(input.items, input.links, { ...o, method }) });
+  defineStrategy<"room", RoomPreset>({ step: "room", name: method, describe, defaults: {}, schema: ROOM_SCHEMA, run: (input, o) => roomDemand(input.items, input.links, { ...o, method }) });
+
+/** The options of the room strategy `levels`: the options of `levelRoom` without the method, and the limits of the quadtree. */
+export type LevelRoomPreset = Omit<LevelRoomOptions, "method"> & SectionOptions;
 
-/** The built-in room strategies: the methods of `roomDemand`. */
+/** The built-in room strategies: the methods of `roomDemand`, and the room of each zoom level (`levelRoom`). */
 export const roomStrategies: {
   readonly routes: Strategy<"room", RoomPreset>;
   readonly lines: Strategy<"room", RoomPreset>;
+  readonly levels: Strategy<"room", LevelRoomPreset>;
 } = Object.freeze({
   routes: roomStrategy("routes", "The lanes of a gap are the most routes that run along it side by side, with each gap open to the gutter."),
   lines: roomStrategy("lines", "The lanes of a gap are the straight lines between the centers of the boxes that cross the gap."),
+  levels: defineStrategy<"room", LevelRoomPreset>({
+    step: "room",
+    name: "levels",
+    describe: "Each zoom level gets the gaps that its links need. The far levels open first, and a box moves with its parent.",
+    defaults: {},
+    schema: LEVEL_ROOM_SCHEMA,
+    run: (input, o) => {
+      const { cap, maxDepth, collapse, ...room } = o;
+      const root = input.sections ?? buildSections(input.items, { cap: cap ?? SECTION_DEFAULTS.cap, maxDepth: maxDepth ?? SECTION_DEFAULTS.maxDepth, collapse: collapse ?? SECTION_DEFAULTS.collapse });
+      return levelRoom(input.items, input.links, root, room).gaps;
+    },
+  }),
 });
 
 /** The built-in grouping rules: the strategies of the step `group`. The router `sections` makes its hubs and its zoom levels from their tree. */
 export const groupStrategies: {
   readonly quadtree: Strategy<"group", Required<SectionOptions>>;
   readonly keys: Strategy<"group", KeyOptions>;
+  readonly kd: Strategy<"group", Required<KdOptions>>;
+  readonly cut: Strategy<"group", Required<CutOptions>>;
 } = Object.freeze({
   quadtree: defineStrategy({
     step: "group",
     name: "quadtree",
     describe: "The cells of a quadtree of the plane. A cell with more than `cap` nodes splits in four. It is the default rule of the router `sections`.",
     defaults: { ...SECTION_DEFAULTS },
+    schema: SECTION_SCHEMA,
     run: (graph: Graph, o: Readonly<Required<SectionOptions>>) => quadtreeGroups(graph, o),
   }),
   keys: defineStrategy({
@@ -178,8 +282,25 @@ export const groupStrategies: {
     name: "keys",
     describe: "One group for each key of the nodes. The default key is the string `data.group` of the node. A node without a key is a group alone.",
     defaults: { key: byDataGroup } as KeyOptions,
+    schema: KEY_SCHEMA,
     run: (graph: Graph, o: Readonly<KeyOptions>) => keyGroups(graph, o),
   }),
+  kd: defineStrategy({
+    step: "group",
+    name: "kd",
+    describe: "The cells of a k-d tree of the plane. A cell with more than `cap` nodes splits in two with a line across one axis, and each half splits again.",
+    defaults: { ...KD_DEFAULTS },
+    schema: KD_SCHEMA,
+    run: (graph: Graph, o: Readonly<Required<KdOptions>>) => kdGroups(graph, o),
+  }),
+  cut: defineStrategy({
+    step: "group",
+    name: "cut",
+    describe: "A guillotine cut that reads the edges. Each line goes where it cuts the fewest edges for its balance, so the far view has fewer links.",
+    defaults: { ...CUT_DEFAULTS },
+    schema: CUT_SCHEMA,
+    run: (graph: Graph, o: Readonly<Required<CutOptions>>) => cutGroups(graph, o),
+  }),
 });
 
 /** The built-in strategies of each step, in order. A consumer adds its own: `createRegistry([...BUILT_IN_STRATEGIES, mine])`. */

package/src/strategies/index.ts

@@ -1,2 +1,3 @@
 export * from "./model.ts";
 export * from "./builtins.ts";
+export * from "./options.ts";

package/src/strategies/model.ts

@@ -4,6 +4,7 @@ import type { Point } from "../geom.ts";
 import type { Graph, Result, Router } from "../model.ts";
 import type { Boxed, Gap, RoomLink } from "../room/index.ts";
 import type { Section } from "../sections.ts";
+import type { OptionSchema } from "./options.ts";
 
 /** The input of a curve strategy: one polyline and the context of its route. */
 export interface CurveInput {
@@ -21,6 +22,11 @@ export interface CurveInput {
 export interface RoomInput {
   readonly items: readonly Boxed[];
   readonly links: readonly RoomLink[];
+  /**
+   * The tree of sections of the items, for a strategy that gives room to each zoom level. The indices of its nodes are the indices of `items`.
+   * Without it, such a strategy makes the quadtree of `buildSections`. The other strategies do not read it.
+   */
+  readonly sections?: Section;
 }
 
 /**
@@ -63,6 +69,8 @@ export interface Strategy<S extends Step = Step, O extends object = object> {
   readonly describe: string;
   /** The values of the options when the caller gives no value. */
   readonly defaults: Readonly<O>;
+  /** The declarations of the options: the type, the range, the step and the meaning of each one. A strategy without it declares nothing. */
+  readonly schema?: OptionSchema<O>;
   /** The benchmark skips an input with more nodes than this. Without it, the strategy takes each input. */
   readonly maxNodes?: number;
   /** This method does the step. Each option that `options` does not give gets its value from `defaults`. */
@@ -79,23 +87,33 @@ export interface StrategyDefinition<S extends Step, O extends object> {
   readonly describe: string;
   /** These values are the options when the caller gives no value. Give `{}` for a strategy without options. */
   readonly defaults: O;
+  /** These declarations tell the type, the range, the step and the meaning of each option. `checkSchema` examines them. */
+  readonly schema?: NoInfer<OptionSchema<O>>;
   readonly maxNodes?: number;
   /** This function does the step. It gets each option, from the caller or from `defaults`. */
   run(input: StepInput<S>, options: Readonly<O>): StepOutput<S>;
 }
 
+/** This function gives a frozen copy of a schema, with each declaration frozen. */
+function freezeSchema<O>(schema: OptionSchema<O>): OptionSchema<O> {
+  const out: Record<string, unknown> = {};
+  for (const [key, d] of Object.entries(schema)) out[key] = Object.freeze({ ...(d as object) });
+  return Object.freeze(out) as OptionSchema<O>;
+}
+
 /**
  * This function makes a strategy from its definition. The strategy fills the missing options from `defaults`.
  * When the caller gives no option, the definition gets the `defaults` object itself.
  */
 export function defineStrategy<S extends Step, O extends object>(definition: StrategyDefinition<S, O>): Strategy<S, O> {
-  const { step, name, describe, defaults, maxNodes } = definition;
+  const { step, name, describe, defaults, schema, maxNodes } = definition;
   if (name.length === 0) throw new Error(`A strategy of the step "${step}" has no name.`);
   const strategy: Strategy<S, O> = {
     step,
     name,
     describe,
     defaults: Object.freeze({ ...defaults }),
+    ...(schema === undefined ? {} : { schema: freezeSchema(schema) }),
     ...(maxNodes === undefined ? {} : { maxNodes }),
     run(input: StepInput<S>, options?: Partial<O>): StepOutput<S> {
       const all = options === undefined || Object.keys(options).length === 0 ? strategy.defaults : { ...strategy.defaults, ...options };

package/src/strategies/options.ts

@@ -0,0 +1,296 @@
+import type { Step, Strategy } from "./model.ts";
+
+/** The scale of a number option. A sweep on the scale `log` gives values with equal ratios, not with equal differences. */
+export type OptionScale = "linear" | "log";
+
+/** The fields of each option declaration. */
+interface OptionBase {
+  /** One short sentence that tells what the option sets. The site and the documents show it. */
+  readonly describe: string;
+}
+
+/**
+ * The declaration of a number option. The range from `min` to `max` is the range of a control and of a sweep.
+ * The strategy can take a value outside the range. `checkOptions` reports such a value, and `clampOptions` moves it into the range.
+ */
+export interface NumberOption extends OptionBase {
+  /** The type `integer` takes only whole numbers. */
+  readonly type: "number" | "integer";
+  readonly min: number;
+  readonly max: number;
+  /** The grain of a control and of a sweep. A value off the step is valid. Without it, the grain is free (or 1 for an integer). */
+  readonly step?: number;
+  /** The scale of a control and of a sweep. The default is `linear`. The scale `log` needs a `min` above 0. */
+  readonly scale?: OptionScale;
+  /** These values are valid outside the range. For example, `Infinity` sets no limit. */
+  readonly special?: readonly number[];
+  /** These values are the notable values of the option: the default and the values of the sweeps of the benchmark. */
+  readonly marks?: readonly number[];
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: number;
+}
+
+/** The declaration of a boolean option. */
+export interface BooleanOption extends OptionBase {
+  readonly type: "boolean";
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: boolean;
+}
+
+/** The declaration of an option with a fixed list of string values. */
+export interface EnumOption<V extends string = string> extends OptionBase {
+  readonly type: "enum";
+  /** The values of the option, in the order of a control. */
+  readonly values: readonly V[];
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: V;
+}
+
+/**
+ * The declaration of an option that a control or a sweep cannot set from a range.
+ * The type `function` is a rule, `strategy` is a strategy of the step `step`, `list` is an array and `object` is any other object.
+ */
+export interface ValueOption<V = unknown> extends OptionBase {
+  readonly type: "function" | "strategy" | "list" | "object";
+  /** The step of the strategy, for the type `strategy`. A control lists the strategies of this step of a registry. */
+  readonly step?: Step;
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: V;
+}
+
+/** The declaration of one option of any type. */
+export type AnyOption = NumberOption | BooleanOption | EnumOption | ValueOption;
+
+/** The declaration that fits the type of an option value: numbers, booleans, string unions or other values. */
+export type OptionDeclaration<V> = [V] extends [number] ? NumberOption : [V] extends [boolean] ? BooleanOption : [V] extends [string] ? EnumOption<V> : ValueOption<V>;
+
+/** The declarations of the options of a strategy. The schema has one declaration for each key of the options type, and no other key. */
+export type OptionSchema<O> = { readonly [K in keyof O]-?: OptionDeclaration<NonNullable<O[K]>> };
+
+/** One problem of an option value against its declaration. */
+export interface OptionIssue {
+  /** The key of the option. */
+  readonly key: string;
+  readonly value: unknown;
+  /** The kind of the problem: no declaration, the wrong type, out of the range, not a whole number or not one of the values. */
+  readonly problem: "unknown" | "type" | "range" | "integer" | "value";
+  /** One sentence that tells the problem. */
+  readonly message: string;
+}
+
+/** One setting of a sweep: a name for the rows of a table, and the options of the strategy. */
+export interface OptionSetting<O extends object> {
+  /** The key and the value of each option of the setting, for example `stretch 1.5`. */
+  readonly name: string;
+  readonly options: Partial<O>;
+}
+
+/** The options of `sweepValues`, `sweepOf` and `sweepGrid`. */
+export interface SweepOptions {
+  /**
+   * The number of values on the range of a number option. Without it, the sweep gives the `marks` of the declaration.
+   * A declaration without `marks` gets 5 values.
+   */
+  readonly count?: number;
+  /** With `true`, a sweep of a number option on the range also gives the `special` values. The default is `false`. */
+  readonly special?: boolean;
+}
+
+/** The number of values of a sweep on a range when the call and the declaration give no number. */
+const SWEEP_COUNT = 5;
+
+/** This function gives the declarations of a strategy as a record. A strategy without a schema gives an empty record. */
+function schemaOf(strategy: Strategy<Step, object>): Readonly<Record<string, AnyOption>> {
+  return (strategy.schema ?? {}) as Readonly<Record<string, AnyOption>>;
+}
+
+/** This function gives the declared options of a strategy, in the order of its schema, with the effective default of each one. */
+export function listOptions<S extends Step, O extends object>(
+  strategy: Strategy<S, O>,
+): { readonly key: keyof O & string; readonly declaration: AnyOption; readonly value: unknown }[] {
+  const defaults = optionDefaults(strategy) as Record<string, unknown>;
+  return Object.entries(schemaOf(strategy)).map(([key, declaration]) => ({ key: key as keyof O & string, declaration, value: defaults[key] }));
+}
+
+/**
+ * This function gives the effective default of each declared option: the value of `defaults`, else the `default` of the declaration.
+ * An option without either value stays out. The strategy gives the same output with this object as with no options.
+ */
+export function optionDefaults<S extends Step, O extends object>(strategy: Strategy<S, O>): Partial<O> {
+  const out: Record<string, unknown> = {};
+  const defaults = strategy.defaults as Readonly<Record<string, unknown>>;
+  for (const [key, declaration] of Object.entries(schemaOf(strategy))) {
+    if (key in defaults) out[key] = defaults[key];
+    else if (declaration.default !== undefined) out[key] = declaration.default;
+  }
+  for (const key of Object.keys(defaults)) if (!(key in out)) out[key] = defaults[key];
+  return out as Partial<O>;
+}
+
+/** This function gives `true` if the number is one of the special values of the declaration. */
+const isSpecial = (d: NumberOption, v: number): boolean => (d.special ?? []).some((s) => Object.is(s, v) || s === v);
+
+/** This function gives the problem of one value against its declaration, or `undefined` when the value fits. */
+function issueOf(key: string, value: unknown, d: AnyOption): OptionIssue | undefined {
+  const issue = (problem: OptionIssue["problem"], message: string): OptionIssue => ({ key, value, problem, message });
+  if (value === undefined) return undefined;
+  switch (d.type) {
+    case "number":
+    case "integer": {
+      if (typeof value !== "number" || Number.isNaN(value)) return issue("type", `The option "${key}" takes a number.`);
+      if (isSpecial(d, value)) return undefined;
+      if (value < d.min || value > d.max) return issue("range", `The option "${key}" is ${value}, out of the range ${d.min} to ${d.max}.`);
+      if (d.type === "integer" && !Number.isInteger(value)) return issue("integer", `The option "${key}" takes a whole number, not ${value}.`);
+      return undefined;
+    }
+    case "boolean":
+      return typeof value === "boolean" ? undefined : issue("type", `The option "${key}" takes true or false.`);
+    case "enum":
+      return d.values.includes(value as string) ? undefined : issue("value", `The option "${key}" takes ${d.values.join(", ")}, not ${String(value)}.`);
+    case "function":
+      return typeof value === "function" ? undefined : issue("type", `The option "${key}" takes a function.`);
+    case "list":
+      return Array.isArray(value) ? undefined : issue("type", `The option "${key}" takes a list.`);
+    default:
+      return typeof value === "object" && value !== null ? undefined : issue("type", `The option "${key}" takes an object.`);
+  }
+}
+
+/**
+ * This function examines option values against the schema of a strategy. It gives one issue for each key without a declaration.
+ * It also gives one issue for each value of the wrong type, out of the range, not whole or not one of the values.
+ * It changes no value.
+ * A strategy without a schema gives no issue.
+ */
+export function checkOptions<S extends Step, O extends object>(strategy: Strategy<S, O>, options: Partial<O>): OptionIssue[] {
+  if (strategy.schema === undefined) return [];
+  const schema = schemaOf(strategy);
+  const out: OptionIssue[] = [];
+  for (const [key, value] of Object.entries(options)) {
+    const d = schema[key];
+    const issue = d ? issueOf(key, value, d) : { key, value, problem: "unknown" as const, message: `The strategy "${strategy.name}" has no option "${key}".` };
+    if (issue) out.push(issue);
+  }
+  return out;
+}
+
+/**
+ * This function moves each number option into the range of its declaration, for a control. An integer option gets the nearest whole number.
+ * A special value stays. The function keeps each other value as it is. `checkOptions` reports the values that this function cannot correct.
+ */
+export function clampOptions<S extends Step, O extends object>(strategy: Strategy<S, O>, options: Partial<O>): Partial<O> {
+  const schema = schemaOf(strategy);
+  const out: Record<string, unknown> = { ...options };
+  for (const [key, value] of Object.entries(options)) {
+    const d = schema[key];
+    if (!d || (d.type !== "number" && d.type !== "integer") || typeof value !== "number" || Number.isNaN(value) || isSpecial(d, value)) continue;
+    const v = Math.min(d.max, Math.max(d.min, value));
+    out[key] = d.type === "integer" ? Math.min(d.max, Math.max(d.min, Math.round(v))) : v;
+  }
+  return out as Partial<O>;
+}
+
+/** This function gives `count` values from `min` to `max` on the scale, on the grain of the step, without repeats. */
+function rangeValues(d: NumberOption, count: number): number[] {
+  const n = Math.max(1, Math.floor(count));
+  const log = d.scale === "log" && d.min > 0;
+  const at = (t: number): number => (log ? d.min * (d.max / d.min) ** t : d.min + (d.max - d.min) * t);
+  const step = d.step ?? (d.type === "integer" ? 1 : undefined);
+  const snap = (v: number): number => {
+    const s = step === undefined ? v : d.min + Math.round((v - d.min) / step) * step;
+    const r = Number(s.toPrecision(12));
+    return Math.min(d.max, Math.max(d.min, d.type === "integer" ? Math.round(r) : r));
+  };
+  const out: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const v = snap(at(n === 1 ? 0 : i / (n - 1)));
+    if (!out.includes(v)) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * This function gives the values of a sweep of one option declaration.
+ * A number option gives its `marks`, or `count` values on its range and its scale. A boolean gives `false` and `true`. An enum gives its values.
+ * An option of another type has no sweep, so the function throws an error.
+ */
+export function sweepValues(declaration: AnyOption, options: SweepOptions = {}): unknown[] {
+  switch (declaration.type) {
+    case "number":
+    case "integer": {
+      if (options.count === undefined && declaration.marks !== undefined) return [...declaration.marks];
+      const values = rangeValues(declaration, options.count ?? SWEEP_COUNT);
+      return options.special ? [...values, ...(declaration.special ?? []).filter((s) => !values.includes(s))] : values;
+    }
+    case "boolean":
+      return [false, true];
+    case "enum":
+      return [...declaration.values];
+    default:
+      throw new Error(`An option of the type "${declaration.type}" has no sweep. A sweep takes a number, an integer, a boolean or an enum.`);
+  }
+}
+
+/** This function gives the declaration of one option of a strategy. When the strategy has no such declaration, the function throws an error. */
+function declarationOf(strategy: Strategy<Step, object>, key: string): AnyOption {
+  const d = schemaOf(strategy)[key];
+  if (!d) throw new Error(`The strategy "${strategy.name}" has no declaration of the option "${key}".`);
+  return d;
+}
+
+/**
+ * This function gives the settings of a sweep of one option of a strategy, from its declaration only.
+ * The name of each setting is the key and the value, for example `stretch 1.5`.
+ */
+export function sweepOf<S extends Step, O extends object>(strategy: Strategy<S, O>, key: keyof O & string, options: SweepOptions = {}): OptionSetting<O>[] {
+  return sweepValues(declarationOf(strategy, key), options).map((value) => ({ name: `${key} ${String(value)}`, options: { [key]: value } as Partial<O> }));
+}
+
+/**
+ * This function gives the settings of a grid of options: each combination of the values of the sweeps of the keys.
+ * The name of a setting joins the names of its values with commas, in the order of the keys.
+ */
+export function sweepGrid<S extends Step, O extends object>(strategy: Strategy<S, O>, keys: readonly (keyof O & string)[], options: SweepOptions = {}): OptionSetting<O>[] {
+  let out: OptionSetting<O>[] = [{ name: "", options: {} }];
+  for (const key of keys) {
+    const sweep = sweepOf(strategy, key, options);
+    out = out.flatMap((s) => sweep.map((t) => ({ name: s.name === "" ? t.name : `${s.name}, ${t.name}`, options: { ...s.options, ...t.options } })));
+  }
+  return keys.length === 0 ? [] : out;
+}
+
+/** This function gives the problems of one declaration: a bad range, a bad step, or marks and a default that do not fit. */
+function declarationIssues(key: string, d: AnyOption): string[] {
+  const out: string[] = [];
+  if (d.describe.trim().length === 0) out.push(`The option "${key}" has no description.`);
+  if (d.type === "number" || d.type === "integer") {
+    if (!Number.isFinite(d.min) || !Number.isFinite(d.max) || d.min > d.max) out.push(`The option "${key}" has the bad range ${d.min} to ${d.max}.`);
+    if (d.type === "integer" && (!Number.isInteger(d.min) || !Number.isInteger(d.max))) out.push(`The integer option "${key}" has a range that is not whole.`);
+    if (d.step !== undefined && !(d.step > 0)) out.push(`The option "${key}" has the step ${d.step}. A step is more than 0.`);
+    if (d.scale === "log" && !(d.min > 0)) out.push(`The option "${key}" has the scale log and the min ${d.min}. The scale log needs a min above 0.`);
+    for (const v of [...(d.marks ?? []), ...(d.default === undefined ? [] : [d.default])]) {
+      const issue = issueOf(key, v, d);
+      if (issue) out.push(issue.message);
+    }
+  } else if (d.type === "enum") {
+    if (d.values.length === 0) out.push(`The enum option "${key}" has no values.`);
+    if (d.default !== undefined && !d.values.includes(d.default)) out.push(`The default of the option "${key}" is not one of its values.`);
+  } else if (d.type === "boolean") {
+    if (d.default !== undefined && typeof d.default !== "boolean") out.push(`The default of the option "${key}" is not true or false.`);
+  }
+  return out;
+}
+
+/**
+ * This function examines the schema of a strategy. It gives one message for each option of `defaults` without a declaration.
+ * It also gives one message for each bad declaration, and for each value of `defaults` that does not fit its declaration.
+ * A good schema gives an empty list.
+ */
+export function checkSchema(strategy: Strategy<Step, object>): string[] {
+  const schema = schemaOf(strategy);
+  const out: string[] = [];
+  for (const key of Object.keys(strategy.defaults)) if (!(key in schema)) out.push(`The strategy "${strategy.name}" has the option "${key}" in its defaults, without a declaration.`);
+  for (const [key, d] of Object.entries(schema)) out.push(...declarationIssues(key, d).map((m) => `The strategy "${strategy.name}": ${m}`));
+  out.push(...checkOptions(strategy, strategy.defaults).filter((i) => i.problem !== "unknown").map((i) => `The strategy "${strategy.name}": ${i.message}`));
+  return out;
+}