@mark1russell7/highways 0.1.5 → 0.3.0

package/src/sections.ts

@@ -1,5 +1,5 @@
 import { center, type Box } from "./geom.ts";
-import type { Node } from "./model.ts";
+import type { LevelItem, Node } from "./model.ts";
 
 /** A section of the plane: a cell of a quadtree, with the nodes whose centers are in it. */
 export interface Section {
@@ -18,15 +18,21 @@ export interface SectionOptions {
   readonly cap?: number;
   /** The tree stops at this depth. The default is 16. */
   readonly maxDepth?: number;
+  /** A cell shrinks to one quarter at most this many times without a split. Then it stops. The default is 32. */
+  readonly collapse?: number;
 }
 
+/** The default values of `SectionOptions`. */
+export const SECTION_DEFAULTS: Readonly<Required<SectionOptions>> = Object.freeze({ cap: 8, maxDepth: 16, collapse: 32 });
+
 /**
  * This function makes the tree of sections of the nodes. A cell with more than `cap` nodes splits in four.
  * When the nodes of a cell are all in one quarter, the cell becomes that quarter and does not make a level.
  */
 export function buildSections(nodes: readonly Node[], options: SectionOptions = {}): Section {
-  const cap = Math.max(1, options.cap ?? 8);
-  const maxDepth = options.maxDepth ?? 16;
+  const cap = Math.max(1, options.cap ?? SECTION_DEFAULTS.cap);
+  const maxDepth = options.maxDepth ?? SECTION_DEFAULTS.maxDepth;
+  const collapse = options.collapse ?? SECTION_DEFAULTS.collapse;
   const centers = nodes.map((n) => center(n.box));
   let x0 = Infinity;
   let y0 = Infinity;
@@ -41,7 +47,7 @@ export function buildSections(nodes: readonly Node[], options: SectionOptions =
   const root: Box = nodes.length ? { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } : { x: 0, y: 0, w: 0, h: 0 };
   const make = (id: string, depth: number, cell: Box, list: readonly number[]): Section => {
     let box = cell;
-    for (let guard = 0; list.length > cap && depth < maxDepth && guard < 32; guard++) {
+    for (let guard = 0; list.length > cap && depth < maxDepth && guard < collapse; guard++) {
       const mx = box.x + box.w / 2;
       const my = box.y + box.h / 2;
       const parts: number[][] = [[], [], [], []];
@@ -80,3 +86,86 @@ export function allSections(root: Section): Section[] {
 export function treeDepth(root: Section): number {
   return root.children.reduce((d, c) => Math.max(d, treeDepth(c)), root.depth);
 }
+
+/**
+ * This function examines a tree of sections from a grouping rule. It throws an error when the tree is not valid for `count` nodes.
+ * In a valid tree, each node is in exactly one leaf. The children of a section split its nodes, and a child is one level deeper than its parent.
+ */
+export function checkSections(root: Section, count: number): void {
+  const seen = new Array<number>(count).fill(0);
+  const ids = new Set<string>();
+  const fail = (s: Section, what: string): never => {
+    throw new Error(`The tree of sections is not valid at the section "${s.id}": ${what}.`);
+  };
+  if (root.depth !== 0) fail(root, "the root has a depth that is not 0");
+  if (root.nodes.length !== count) fail(root, `the root has ${root.nodes.length} nodes, and the graph has ${count}`);
+  const walk = (s: Section): void => {
+    if (ids.has(s.id)) fail(s, "two sections have this id");
+    ids.add(s.id);
+    if (s.children.length === 0) {
+      for (const i of s.nodes) {
+        if (!Number.isInteger(i) || i < 0 || i >= count) fail(s, `the node index ${i} is not in the graph`);
+        seen[i]!++;
+      }
+      return;
+    }
+    let total = 0;
+    const own = new Set(s.nodes);
+    for (const c of s.children) {
+      if (c.depth !== s.depth + 1) fail(c, "a child is not one level deeper than its parent");
+      for (const i of c.nodes) if (!own.has(i)) fail(c, `the node index ${i} is not in the parent`);
+      total += c.nodes.length;
+      walk(c);
+    }
+    if (total !== s.nodes.length) fail(s, "the children do not split the nodes of the section");
+  };
+  walk(root);
+  const lost = seen.findIndex((n) => n !== 1);
+  if (lost >= 0) fail(root, `the node index ${lost} is in ${seen[lost]} leaves, not in one`);
+}
+
+/** The items of one zoom level of a tree of sections, and the item of each node. */
+export interface LevelCut {
+  /** The items of the level: a section of the depth of the level, or one node of a leaf above that depth. */
+  readonly items: LevelItem[];
+  /** The index in `items` of the item of each node, in the order of the nodes. */
+  readonly owner: readonly number[];
+}
+
+/**
+ * This function gives the items of the zoom level at `depth`. A section of that depth is one item, with the bounding box of its nodes.
+ * A node of a leaf above that depth is an item alone. The items come in the order of the walk of the tree, parents before children.
+ * A depth past the depth of the deepest section gives each node alone.
+ */
+export function levelCut(nodes: readonly Pick<Node, "id" | "box">[], root: Section, depth: number): LevelCut {
+  const items: LevelItem[] = [];
+  const owner: number[] = [];
+  const boxOf = (list: readonly number[]): Box => {
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const i of list) {
+      const b = nodes[i]!.box;
+      x0 = Math.min(x0, b.x);
+      y0 = Math.min(y0, b.y);
+      x1 = Math.max(x1, b.x + b.w);
+      y1 = Math.max(y1, b.y + b.h);
+    }
+    return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+  };
+  const visit = (s: Section): void => {
+    if (s.depth >= depth) {
+      for (const i of s.nodes) owner[i] = items.length;
+      items.push({ id: s.id, box: boxOf(s.nodes), nodes: s.nodes.map((i) => nodes[i]!.id) });
+    } else if (s.children.length > 0) for (const c of s.children) visit(c);
+    else
+      for (const i of s.nodes) {
+        const n = nodes[i]!;
+        owner[i] = items.length;
+        items.push({ id: n.id, box: n.box, nodes: [n.id] });
+      }
+  };
+  if (nodes.length > 0) visit(root);
+  return { items, owner };
+}

package/src/segments.ts

@@ -203,13 +203,77 @@ function turn(from: Point, base: Point, to: Point): number {
 }
 
 /**
- * This function gives the lane order of the edges on a shared way `run` (metro-line order). Two routes go on together
- * past the last point of the run until they part. The route that turns more to the left there gets the lane more to the left.
- * Two routes can part only before the first point. Then the route that comes from more to the left gets the lane more to the left.
- * A route that does not hold the run goes last.
+ * The lane order of the shared ways of a router.
+ * With `bundle`, two edges keep one order on all the shared ways of their common stretch.
+ * With `run`, each shared way gets its order alone. Two edges can change sides from one shared way to the next.
  */
-export function orderLanes(run: readonly Point[], routes: readonly Route[]): string[] {
-  const placed: { edge: string; p: readonly Point[]; s: number; e: number }[] = [];
+export type RunOrder = "bundle" | "run";
+
+/** The place of a route on a run. The points go in the direction of the run. `s` and `e` are the indexes of the ends of the run. */
+interface Placed {
+  readonly edge: string;
+  readonly p: readonly Point[];
+  readonly s: number;
+  readonly e: number;
+}
+
+/** The place where two routes part past one end of their common stretch, and the side of the first route there. */
+interface Parting {
+  /** The last common point. */
+  readonly at: Point;
+  /** This value is below 0 when the first route goes to the left of the second route. It is above 0 when it goes to the right. */
+  readonly side: number;
+}
+
+/** This function gives the place where the routes `P` and `Q` part after the last point of the run, or nothing. */
+function partAfter(P: Placed, Q: Placed): Parting | undefined {
+  for (let j = 1; ; j++) {
+    const a = P.p[P.e + j];
+    const b = Q.p[Q.e + j];
+    if (a === undefined || b === undefined) return undefined;
+    if (dist(a, b) > SAME) {
+      const from = P.p[P.e + j - 2]!;
+      const at = P.p[P.e + j - 1]!;
+      const side = turn(from, at, a) - turn(from, at, b);
+      return side === 0 ? undefined : { at, side };
+    }
+  }
+}
+
+/** This function gives the place where the routes `P` and `Q` part before the first point of the run, or nothing. */
+function partBefore(P: Placed, Q: Placed): Parting | undefined {
+  for (let j = 1; ; j++) {
+    const a = P.p[P.s - j];
+    const b = Q.p[Q.s - j];
+    if (a === undefined || b === undefined) return undefined;
+    if (dist(a, b) > SAME) {
+      const from = P.p[P.s - j + 2]!;
+      const at = P.p[P.s - j + 1]!;
+      // Seen backward, the left side is the right side. Thus the order turns around.
+      const side = turn(from, at, b) - turn(from, at, a);
+      return side === 0 ? undefined : { at, side };
+    }
+  }
+}
+
+const byEdge = (P: Placed, Q: Placed): number => (P.edge < Q.edge ? -1 : P.edge > Q.edge ? 1 : 0);
+
+/** This function puts the point `a` before the point `b`: the smaller x first, then the smaller y. */
+const firstPoint = (a: Point, b: Point): boolean => a.x < b.x - SAME || (Math.abs(a.x - b.x) <= SAME && a.y < b.y);
+
+/**
+ * This function gives the lane order of the edges on a shared way `run` (metro-line order).
+ * The routes are polylines that hold the points of the run in a row, in either direction. A route that does not hold the run goes last.
+ *
+ * Two routes go on together past each end of the run until they part. The route that turns more to the left there gets the lane more to the left.
+ *
+ * With the order `run`, the default, the end after the last point of the run tells the side first.
+ * With the order `bundle`, two routes that part on one side at both ends keep that side.
+ * When the two ends disagree, the two routes must cross. The end with the smaller x, then the smaller y, tells the side.
+ * Thus each shared way of a common stretch gives two routes the same order, and the crossing is where they part.
+ */
+export function orderLanes(run: readonly Point[], routes: readonly Route[], order: RunOrder = "run"): string[] {
+  const placed: Placed[] = [];
   const lost: string[] = [];
   for (const r of routes) {
     let at = indexOf(r.points, run, 0);
@@ -221,30 +285,16 @@ export function orderLanes(run: readonly Point[], routes: readonly Route[]): str
       else lost.push(r.edge);
     }
   }
-  const same = (a: Point, b: Point): boolean => dist(a, b) <= SAME;
-  placed.sort((P, Q) => {
-    for (let j = 1; ; j++) {
-      const a = P.p[P.e + j];
-      const b = Q.p[Q.e + j];
-      if (a === undefined || b === undefined) break;
-      if (!same(a, b)) {
-        const d = turn(P.p[P.e + j - 2]!, P.p[P.e + j - 1]!, a) - turn(P.p[P.e + j - 2]!, P.p[P.e + j - 1]!, b);
-        if (d !== 0) return d;
-        break;
-      }
-    }
-    for (let j = 1; ; j++) {
-      const a = P.p[P.s - j];
-      const b = Q.p[Q.s - j];
-      if (a === undefined || b === undefined) break;
-      if (!same(a, b)) {
-        // Seen backward, the left side is the right side. Thus the order turns around.
-        const d = turn(P.p[P.s - j + 2]!, P.p[P.s - j + 1]!, b) - turn(P.p[P.s - j + 2]!, P.p[P.s - j + 1]!, a);
-        if (d !== 0) return d;
-        break;
-      }
-    }
-    return P.edge < Q.edge ? -1 : P.edge > Q.edge ? 1 : 0;
-  });
+  if (order === "run") placed.sort((P, Q) => partAfter(P, Q)?.side ?? partBefore(P, Q)?.side ?? byEdge(P, Q));
+  else {
+    // The sort starts from the order of the edges, so that each run sorts the same edges the same way.
+    placed.sort(byEdge);
+    placed.sort((P, Q) => {
+      const after = partAfter(P, Q);
+      const before = partBefore(P, Q);
+      if (after && before && Math.sign(after.side) !== Math.sign(before.side)) return firstPoint(after.at, before.at) ? after.side : before.side;
+      return after?.side ?? before?.side ?? byEdge(P, Q);
+    });
+  }
   return [...placed.map((x) => x.edge), ...lost.sort()];
 }

package/src/strategies/builtins.ts

@@ -1,16 +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 { 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">;
@@ -22,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`. */
@@ -54,6 +66,7 @@ export const routerStrategies: {
     10_000,
     {},
     cornersRouter,
+    CORNERS_SCHEMA,
   ),
   "corners-smooth": routerStrategy<RouterPreset<CornersOptions>>(
     "corners-smooth",
@@ -61,6 +74,7 @@ export const routerStrategies: {
     10_000,
     { smooth: true },
     cornersRouter,
+    CORNERS_SCHEMA,
   ),
   trunks: routerStrategy<RouterPreset<TrunksOptions>>(
     "trunks",
@@ -68,6 +82,7 @@ export const routerStrategies: {
     10_000,
     { rule: byCollection },
     trunksRouter,
+    TRUNKS_SCHEMA,
   ),
   shared: routerStrategy<RouterPreset<SharedOptions>>(
     "shared",
@@ -75,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",
@@ -90,6 +107,7 @@ export const routerStrategies: {
     100_000,
     { stretch: Infinity },
     sectionsRouter,
+    SECTIONS_SCHEMA,
   ),
 });
 
@@ -112,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({
@@ -132,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({
@@ -139,27 +195,117 @@ 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 built-in room strategies: the methods of `roomDemand`. */
+/** 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`, 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({
+    step: "group",
+    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])`. */
 export const BUILT_IN_STRATEGIES: readonly AnyStrategy[] = Object.freeze([
+  ...Object.values(groupStrategies),
   ...Object.values(routerStrategies),
   ...Object.values(curveStrategies),
   ...Object.values(roomStrategies),

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

@@ -3,6 +3,8 @@ import type { CurveSpace } from "../curves/space.ts";
 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 {
@@ -20,16 +22,23 @@ 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;
 }
 
 /**
  * The steps that have strategies, with the fixed input and output type of each step.
  *
+ * - `group`: a graph in, the tree of sections out. The router `sections` makes its hubs and its zoom levels from this tree.
  * - `router`: a graph in, the routes (and the `levels`, `bundles` and `runs`) out.
  * - `curve`: a polyline in, the segments of a curve out.
  * - `room`: the boxes and links of a board in, the gaps of the board with their need out.
  */
 export interface StepTypes {
+  readonly group: { readonly input: Graph; readonly output: Section };
   readonly router: { readonly input: Graph; readonly output: Result };
   readonly curve: { readonly input: CurveInput; readonly output: CurveSegment[] };
   readonly room: { readonly input: RoomInput; readonly output: Gap[] };
@@ -45,7 +54,7 @@ export type StepInput<S extends Step> = StepTypes[S]["input"];
 export type StepOutput<S extends Step> = StepTypes[S]["output"];
 
 /** The steps that have strategies, in the order of the pipeline. */
-export const STEPS: readonly Step[] = ["router", "curve", "room"];
+export const STEPS: readonly Step[] = ["group", "router", "curve", "room"];
 
 /**
  * A strategy: one way to do one step, with a name and a description.
@@ -60,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`. */
@@ -76,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 };
@@ -105,29 +126,30 @@ export function defineStrategy<S extends Step, O extends object>(definition: Str
 /**
  * A registry: the strategies of each step, in order. A registry is data. No import changes it.
  * A consumer makes its own registry with `createRegistry`, and adds a strategy with `register`.
+ * The list `group` is optional in the type, so a registry from version 0.1.5 stays a registry. `createRegistry` always gives it.
  */
-export type Registry = { readonly [S in Step]: readonly Strategy<S>[] };
+export type Registry = { readonly [S in Exclude<Step, "group">]: readonly Strategy<S>[] } & { readonly group?: readonly Strategy<"group">[] };
 
 /** This function makes a registry from a list of strategies. It keeps their order. Two strategies with one step and one name are an error. */
 export function createRegistry(strategies: readonly AnyStrategy[]): Registry {
-  const out: { [S in Step]: Strategy<S>[] } = { router: [], curve: [], room: [] };
+  const out: { [S in Step]: Strategy<S>[] } = { group: [], router: [], curve: [], room: [] };
   for (const s of strategies) {
     const list = out[s.step] as AnyStrategy[] | undefined;
     if (!list) throw new Error(`There is no step "${String(s.step)}". The steps are ${STEPS.join(", ")}.`);
     if (list.some((t) => t.name === s.name)) throw new Error(`The step "${s.step}" has two strategies with the name "${s.name}".`);
     list.push(s);
   }
-  return Object.freeze({ router: Object.freeze(out.router), curve: Object.freeze(out.curve), room: Object.freeze(out.room) });
+  return Object.freeze({ group: Object.freeze(out.group), router: Object.freeze(out.router), curve: Object.freeze(out.curve), room: Object.freeze(out.room) });
 }
 
 /** This function gives a new registry with the strategies of `registry` and then `strategies`. It does not change `registry`. */
 export function register(registry: Registry, ...strategies: readonly AnyStrategy[]): Registry {
-  return createRegistry([...registry.router, ...registry.curve, ...registry.room, ...strategies]);
+  return createRegistry([...(registry.group ?? []), ...registry.router, ...registry.curve, ...registry.room, ...strategies]);
 }
 
 /** This function gives the strategies of one step of a registry, in order. */
 export function listStrategies<S extends Step>(registry: Registry, step: S): readonly Strategy<S>[] {
-  return registry[step];
+  return (registry[step] ?? []) as readonly Strategy<S>[];
 }
 
 /** This function gives the strategy of one step with a name, or `undefined` when the registry has no such strategy. */