@mark1russell7/highways 0.8.1 → 0.9.1

package/src/families/cases.ts

@@ -0,0 +1,108 @@
+// The 3 case families of the screen sets: `hub-chain`, `many-groups` and `packed-grid` (CORPUS-GEN).
+import type { CorpusDimension, DimensionValues, GenerateContext } from "@mark1russell7/layout-contract";
+import { hubChainBoard, manyGroupsBoard, packedGridBoard } from "../cases.ts";
+import type { Graph } from "../model.ts";
+import { changedDimensions, numberDimension, numberOf, type HighwaysBoard, type HighwaysFamily } from "./model.ts";
+
+/** This function gives a whole-number dimension with a linear scale. */
+const count = (name: string, min: number, max: number, value: number, meaning: string): CorpusDimension =>
+  numberDimension({ name, kind: "int", min, max, default: value, meaning });
+
+/** This function gives the numbers of the full dimension values, by name. */
+function numbers(dimensions: readonly CorpusDimension[], dims: DimensionValues): Record<string, number> {
+  return Object.fromEntries(dimensions.map((d) => [d.name, numberOf(dims, d.name)]));
+}
+
+/** The fields of a case family of `caseFamily`. */
+interface CaseFields {
+  readonly name: string;
+  readonly meaning: string;
+  readonly dimensions: readonly CorpusDimension[];
+  /** The name of the generator record, for example `case.hub-chain`. */
+  readonly generator: string;
+  /** This function gives the parameters of the generator record from the full values. The default gives the values that differ from their defaults. */
+  readonly params?: (dims: DimensionValues) => Readonly<Record<string, unknown>>;
+  /** This function makes the board. It gets the values by name, the input seed and the source of random numbers of the registry. */
+  readonly make: (values: Readonly<Record<string, number>>, seed: number, random: () => number) => Graph;
+}
+
+/** This function gives a case family. Its stream is mulberry32 of the input seed, and it uses only the stream, `Math.floor` and `Math.ceil`. */
+function caseFamily(fields: CaseFields): HighwaysFamily {
+  const { name, meaning, dimensions } = fields;
+  const params = fields.params ?? ((dims: DimensionValues) => changedDimensions(dimensions, dims));
+  return Object.freeze({
+    name,
+    version: 1,
+    owner: "highways",
+    meaning,
+    dimensions,
+    seeding: "mulberry32 of the input seed. The fixed part of the board takes no number. Then one stream gives the random links.",
+    crossEngine: "exact",
+    generate(seed: number, dims: DimensionValues, context: GenerateContext): HighwaysBoard {
+      return { graph: fields.make(numbers(dimensions, dims), seed, context.random), generator: { name: fields.generator, version: 1, params: params(dims), seed } };
+    },
+  });
+}
+
+/** The dimensions of `hub-chain`. */
+const HUB_CHAIN_DIMENSIONS: readonly CorpusDimension[] = Object.freeze([
+  count("rows", 1, 8, 3, "The number of rows of cards."),
+  count("cols", 4, 64, 32, "The number of cards in each row."),
+  count("long", 0, 200, 40, "The number of tries for a long link between two rows."),
+  count("gap", 0, 96, 48, "The free space between two cards, in units."),
+]);
+
+/** The family `hub-chain`: rows of cards in a chain, and long links between rows. At its defaults, it is `hubChainBoard`. */
+export const HUB_CHAIN: HighwaysFamily = caseFamily({
+  name: "hub-chain",
+  meaning: "Rows of cards in a chain, and long links that climb a chain of hubs away from their targets.",
+  dimensions: HUB_CHAIN_DIMENSIONS,
+  generator: "case.hub-chain",
+  make: (v, seed, random) => hubChainBoard({ seed, rows: v["rows"]!, cols: v["cols"]!, long: v["long"]!, gap: v["gap"]! }, random),
+});
+
+/** The dimensions of `many-groups`. */
+const MANY_GROUPS_DIMENSIONS: readonly CorpusDimension[] = Object.freeze([
+  count("groupCols", 1, 16, 8, "The number of columns of groups."),
+  count("groupRows", 1, 8, 4, "The number of rows of groups."),
+  count("perGroup", 1, 16, 4, "The number of cards in each group."),
+  count("crossLinksPerGroup", 0, 8, 3, "The number of random links between groups, for each group."),
+  count("groupGap", 0, 120, 60, "The free space between two groups, in units."),
+]);
+
+/** The family `many-groups`: groups of cards in a grid, with links between groups. At its defaults, it is `manyGroupsBoard`. */
+export const MANY_GROUPS: HighwaysFamily = caseFamily({
+  name: "many-groups",
+  meaning: "A grid of groups of cards, with random links between groups that go around the board.",
+  dimensions: MANY_GROUPS_DIMENSIONS,
+  generator: "case.many-groups",
+  make: (v, seed, random) =>
+    manyGroupsBoard(
+      { seed, groupCols: v["groupCols"]!, groupRows: v["groupRows"]!, perGroup: v["perGroup"]!, crossLinksPerGroup: v["crossLinksPerGroup"]!, groupGap: v["groupGap"]! },
+      random,
+    ),
+});
+
+/** The dimensions of `packed-grid`. */
+const PACKED_GRID_DIMENSIONS: readonly CorpusDimension[] = Object.freeze([
+  count("cols", 2, 32, 12, "The number of columns of boxes."),
+  count("rows", 2, 32, 8, "The number of rows of boxes."),
+  count("long", 0, 256, 48, "The number of long links between boxes far apart."),
+  count("reach", 1, 4, 2, "The largest step, in rows and in columns, of the link of a box to a box near it."),
+]);
+
+/**
+ * The family `packed-grid`: a grid of boxes that touch. At its defaults, it is `packedGridBoard` with 12 columns, 8 rows and 48 long links.
+ * Its generator record always has `cols`, `rows` and `long`, as the screen sets of today. It has `reach` only away from its default.
+ */
+export const PACKED_GRID: HighwaysFamily = caseFamily({
+  name: "packed-grid",
+  meaning: "A packed grid of boxes that touch, with no channel for the routes.",
+  dimensions: PACKED_GRID_DIMENSIONS,
+  generator: "case.packed-grid",
+  params: (dims) => {
+    const reach = numberOf(dims, "reach");
+    return { cols: numberOf(dims, "cols"), rows: numberOf(dims, "rows"), long: numberOf(dims, "long"), ...(reach === 2 ? {} : { reach }) };
+  },
+  make: (v, seed, random) => packedGridBoard({ seed, cols: v["cols"]!, rows: v["rows"]!, long: v["long"]!, reach: v["reach"]! }, random),
+});

package/src/families/fixtures.ts

@@ -0,0 +1,101 @@
+// The 3 fixture families of the screen sets: `tiny-uniform`, `small-clustered` and `dense-groups` (CORPUS-GEN).
+import type { CorpusDimension, DimensionValues, GenerateContext } from "@mark1russell7/layout-contract";
+import { fixtureRngSeed, makeFixture, type FixtureKind, type FixtureSpec } from "../fixtures.ts";
+import { enumDimension, numberDimension, numberOf, type HighwaysBoard, type HighwaysFamily } from "./model.ts";
+
+/** The values of the dimension `layout`: each `FixtureKind`. */
+export const FIXTURE_LAYOUTS: readonly FixtureKind[] = Object.freeze(["uniform", "clustered", "grid", "hubs", "collections"]);
+
+/** The share of the edges near the source when a spec has no `locality`: the default of `makeFixture`. */
+export const FIXTURE_LOCALITY = 0.65;
+
+/** The defaults of the dimensions of one fixture family: the spec of its board in the benchmark. */
+interface FixtureDefaults {
+  readonly layout: FixtureKind;
+  readonly nodes: number;
+  readonly edgesPerNode: number;
+  readonly fixedPorts: number;
+}
+
+/**
+ * This function gives the 5 dimensions of a fixture family. The name `kind` is reserved, so the dimension of the `FixtureKind` is `layout`.
+ * No dimension has a `when`, because each kind reads `locality` and `fixedPorts`.
+ */
+function fixtureDimensions(d: FixtureDefaults): readonly CorpusDimension[] {
+  return Object.freeze([
+    enumDimension("layout", FIXTURE_LAYOUTS, d.layout, "The way that the board puts its nodes and picks its edges: the `kind` of the `FixtureSpec`."),
+    numberDimension({ name: "nodes", kind: "int", min: 2, max: 400, default: d.nodes, scale: "log", meaning: "The number of nodes of the board." }),
+    numberDimension({ name: "edgesPerNode", kind: "real", min: 0, max: 6, default: d.edgesPerNode, meaning: "The number of edges, divided by the number of nodes." }),
+    numberDimension({ name: "locality", kind: "real", min: 0, max: 1, default: FIXTURE_LOCALITY, meaning: "The share of the edges that join a node near the source." }),
+    numberDimension({ name: "fixedPorts", kind: "real", min: 0, max: 1, default: d.fixedPorts, meaning: "The share of the nodes with one fixed plug for their outgoing edges." }),
+  ]);
+}
+
+/** This function gives the spec of a fixture board from the full dimension values. A field at the default of `makeFixture` stays out of the spec. */
+export function fixtureSpecOf(name: string, seed: number, dims: DimensionValues): FixtureSpec {
+  const layout = dims["layout"];
+  if (typeof layout !== "string" || !FIXTURE_LAYOUTS.includes(layout as FixtureKind)) throw new RangeError(`The dimension "layout" is ${String(layout)}, not a fixture kind.`);
+  const locality = numberOf(dims, "locality");
+  const fixedPorts = numberOf(dims, "fixedPorts");
+  return {
+    name,
+    kind: layout as FixtureKind,
+    nodes: numberOf(dims, "nodes"),
+    edgesPerNode: numberOf(dims, "edgesPerNode"),
+    seed,
+    ...(locality === FIXTURE_LOCALITY ? {} : { locality }),
+    ...(fixedPorts === 0 ? {} : { fixedPorts }),
+  };
+}
+
+/**
+ * This function gives the parameters of the generator record of a fixture board: the spec without its name and its seed.
+ * Thus the record of each screen board stays the record of today, for example `{ kind, nodes, edgesPerNode, fixedPorts }` of `small-clustered`.
+ */
+export function fixtureParams(spec: FixtureSpec): Readonly<Record<string, unknown>> {
+  const { name: _name, seed: _seed, ...params } = spec;
+  return params;
+}
+
+/** This function gives one fixture family with the defaults of its board in the benchmark. */
+function fixtureFamily(name: string, meaning: string, defaults: FixtureDefaults): HighwaysFamily {
+  return Object.freeze({
+    name,
+    version: 1,
+    owner: "highways",
+    meaning,
+    dimensions: fixtureDimensions(defaults),
+    seeding: "mulberry32 of (seed × 2654435761 + nodes) >>> 0. One stream gives the boxes, the plugs and then the edges, in a fixed order.",
+    // The kinds `clustered` and `collections` use `Math.log` and `Math.cos`, and the kind `hubs` uses `**`. Each fixture family has these kinds in `layout`.
+    crossEngine: "libm-dependent",
+    rngSeed: (seed: number, dims: DimensionValues) => fixtureRngSeed(seed, numberOf(dims, "nodes")),
+    generate(seed: number, dims: DimensionValues, context: GenerateContext): HighwaysBoard {
+      const spec = fixtureSpecOf(name, seed, dims);
+      return { graph: makeFixture(spec, context.random), generator: { name: "fixture", version: 1, params: fixtureParams(spec), seed } };
+    },
+  });
+}
+
+/** The family `tiny-uniform`: 10 nodes at random places. It is the fixture `tiny-uniform` of `FIXTURES` at its defaults. */
+export const TINY_UNIFORM: HighwaysFamily = fixtureFamily("tiny-uniform", "A tiny board of nodes at random places: the cost of a strategy at its start.", {
+  layout: "uniform",
+  nodes: 10,
+  edgesPerNode: 1.5,
+  fixedPorts: 0,
+});
+
+/** The family `small-clustered`: 100 nodes in clusters, with a fixed plug on 20% of the nodes. It is the fixture `small-clustered` at its defaults. */
+export const SMALL_CLUSTERED: HighwaysFamily = fixtureFamily("small-clustered", "Nodes in clusters, and fixed plugs on a share of the nodes.", {
+  layout: "clustered",
+  nodes: 100,
+  edgesPerNode: 2,
+  fixedPorts: 0.2,
+});
+
+/** The family `dense-groups`: 150 nodes in tight clusters. It is `denseGroupsBoard` at its defaults. */
+export const DENSE_GROUPS: HighwaysFamily = fixtureFamily("dense-groups", "Dense clusters whose groups overlap at the far view.", {
+  layout: "clustered",
+  nodes: 150,
+  edgesPerNode: 2,
+  fixedPorts: 0,
+});

package/src/families/index.ts

@@ -0,0 +1,36 @@
+// The corpus families of highways on the shared registry of `@mark1russell7/layout-contract` (CORPUS-GEN, L45).
+import { createFamilyRegistry, type FamilyRegistry } from "@mark1russell7/layout-contract";
+import { HUB_CHAIN, MANY_GROUPS, PACKED_GRID } from "./cases.ts";
+import { DENSE_GROUPS, SMALL_CLUSTERED, TINY_UNIFORM } from "./fixtures.ts";
+import type { HighwaysBoard, HighwaysFamily } from "./model.ts";
+
+export * from "./model.ts";
+export { DENSE_GROUPS, FIXTURE_LAYOUTS, FIXTURE_LOCALITY, fixtureParams, fixtureSpecOf, SMALL_CLUSTERED, TINY_UNIFORM } from "./fixtures.ts";
+export { HUB_CHAIN, MANY_GROUPS, PACKED_GRID } from "./cases.ts";
+// The parts of the shared registry that a host of the families uses. The site imports only `@mark1russell7/highways`.
+export {
+  createFamilyRegistry,
+  DEFAULT_RNG,
+  dimensionAt,
+  dimensionUnit,
+  familyKind,
+  levelsOf,
+  paramProblem,
+  type CorpusDimension,
+  type CorpusFamily,
+  type DimensionValues,
+  type FamilyRegistry,
+  type GenerateContext,
+  type ParamValue,
+} from "@mark1russell7/layout-contract";
+
+/**
+ * The corpus families of highways, in the order of the screen sets. Each family at its defaults makes the board of its screen family.
+ * An import registers nothing. A host makes a registry with `createFamilyRegistry(HIGHWAYS_FAMILIES)`, or with the lists of other engines too.
+ */
+export const HIGHWAYS_FAMILIES: readonly HighwaysFamily[] = Object.freeze([TINY_UNIFORM, SMALL_CLUSTERED, DENSE_GROUPS, HUB_CHAIN, MANY_GROUPS, PACKED_GRID]);
+
+/** This function gives a new registry of `HIGHWAYS_FAMILIES`. */
+export function highwaysRegistry(): FamilyRegistry<HighwaysBoard> {
+  return createFamilyRegistry(HIGHWAYS_FAMILIES);
+}

package/src/families/model.ts

@@ -0,0 +1,55 @@
+// The form of the corpus families of highways (CORPUS-GEN) on the shared registry of `@mark1russell7/layout-contract` (L45).
+import type { CorpusDimension, CorpusFamily, DimensionValues, ParamValue } from "@mark1russell7/layout-contract";
+import type { LayoutGenerator } from "../bench/screen/forms.ts";
+import type { Graph } from "../model.ts";
+
+/**
+ * The output of a family of highways: the graph of the board and its generator record.
+ * A screen set puts the board into an input file with `graphInput`. The set gives the id, the member seed and the cell.
+ */
+export interface HighwaysBoard {
+  readonly graph: Graph;
+  /** The generator of the board: its name, its version, its parameters and its input seed. */
+  readonly generator: LayoutGenerator;
+}
+
+/** A corpus family of highways: a family of the shared registry whose output is a `HighwaysBoard`. */
+export type HighwaysFamily = CorpusFamily<HighwaysBoard>;
+
+/** The engine of each dimension of the families of highways. */
+export const HIGHWAYS_ENGINE = "highways";
+
+/** The fields of a numeric dimension of `numberDimension`. */
+interface NumberFields {
+  readonly name: string;
+  readonly kind: "int" | "real";
+  readonly min: number;
+  readonly max: number;
+  readonly default: number;
+  readonly scale?: "linear" | "log";
+  readonly meaning: string;
+}
+
+/** This function gives an `int` or a `real` dimension that only highways reads. */
+export function numberDimension(fields: NumberFields): CorpusDimension {
+  return Object.freeze({ ...fields, scale: fields.scale ?? "linear", engines: Object.freeze([HIGHWAYS_ENGINE]) });
+}
+
+/** This function gives an `enum` dimension that only highways reads. */
+export function enumDimension(name: string, values: readonly string[], value: string, meaning: string): CorpusDimension {
+  return Object.freeze({ name, kind: "enum", values: Object.freeze([...values]), default: value, meaning, engines: Object.freeze([HIGHWAYS_ENGINE]) });
+}
+
+/** This function gives the values of the dimensions that differ from their defaults, in the order of the dimensions. */
+export function changedDimensions(dimensions: readonly CorpusDimension[], dims: DimensionValues): Record<string, ParamValue> {
+  const out: Record<string, ParamValue> = {};
+  for (const d of dimensions) if (!Object.is(dims[d.name], d.default)) out[d.name] = dims[d.name]!;
+  return out;
+}
+
+/** This function gives the value of a numeric dimension. It throws a `RangeError` when the value is not a number. */
+export function numberOf(dims: DimensionValues, name: string): number {
+  const v = dims[name];
+  if (typeof v !== "number") throw new RangeError(`The dimension "${name}" is ${String(v)}, not a number.`);
+  return v;
+}

package/src/fixtures.ts

@@ -52,12 +52,18 @@ const SIDES: readonly Side[] = ["north", "east", "south", "west"];
 const GAP = 12;
 const SPACING = 90;
 
+/** This function gives the seed of the random numbers of a fixture: `(seed × 2654435761 + nodes) >>> 0`. */
+export function fixtureRngSeed(seed: number, nodes: number): number {
+  return (seed * 2654435761 + nodes) >>> 0;
+}
+
 /**
  * This function makes the graph of a fixture. The same spec always gives the same graph.
  * Node boxes do not overlap, and a gap of 12 units stays between them.
+ * The default source of random numbers is `rng(fixtureRngSeed(spec.seed, spec.nodes))`. A corpus family gives the same stream from its registry.
  */
-export function makeFixture(spec: FixtureSpec): Graph {
-  const R = rng(spec.seed * 2654435761 + spec.nodes);
+export function makeFixture(spec: FixtureSpec, random: () => number = rng(fixtureRngSeed(spec.seed, spec.nodes))): Graph {
+  const R = random;
   const gauss = (): number => Math.sqrt(-2 * Math.log(R() + 1e-12)) * Math.cos(2 * Math.PI * R());
   const side = Math.sqrt(spec.nodes) * SPACING;
   const grid = new Grid<Box>(SPACING);

package/src/highways/fixtures.test-util.ts

@@ -49,6 +49,19 @@ export const parallel: Graph = {
   edges: [0, 1, 2].map((i) => ({ id: `e${i}`, source: { node: `l${i}` }, target: { node: `r${i}` } })),
 };
 
+/** Three rows of nodes on the left and on the right, with three edges between the rows. The gaps between the rows are 40 wide. */
+export const rows: Graph = {
+  nodes: [0, 1, 2].flatMap((i) => [
+    { id: `l${i}`, box: box(0, 60 * i) },
+    { id: `r${i}`, box: box(600, 60 * i) },
+  ]),
+  edges: [
+    { id: "a", source: { node: "l0" }, target: { node: "r2" } },
+    { id: "b", source: { node: "l1" }, target: { node: "r1" } },
+    { id: "c", source: { node: "l2" }, target: { node: "r0" } },
+  ],
+};
+
 /**
  * This function adds the common tests of a highway strategy. The strategy is in the registry, and it gives a correct plan the same each time.
  * Its routes break no hard rule after `follow`.

package/src/highways/follow.ts

@@ -1,5 +1,5 @@
 import { center, dist, pointBoxDistance, type Point } from "../geom.ts";
-import { fixedPortPoint, nodeIndex, type End, type Graph, type Node, type Result, type Route, type SharedRun } from "../model.ts";
+import { fixedPortPoint, nodeIndex, resolvePorts, type End, type Graph, type Node, type Result, type Route, type SharedRun } from "../model.ts";
 import { placePlug } from "../plugs.ts";
 import { orderLanes, type RunOrder } from "../segments.ts";
 import { WayFinder, type WayOptions } from "../ways.ts";
@@ -68,7 +68,8 @@ function slice(stops: Stops, on: number, off: number): Point[] {
  * The result has a shared run for each stretch of a spine where the same two edges or more go. Each run holds the points of its routes in a row.
  * The same graph, plan and options give the same result.
  */
-export function follow(graph: Graph, plan: HighwayPlan, options: FollowOptions = {}): Result {
+export function follow(input: Graph, plan: HighwayPlan, options: FollowOptions = {}): Result {
+  const graph = resolvePorts(input);
   const byId = nodeIndex(graph);
   const ways = new WayFinder(graph.nodes, options);
   const base = new Map((options.routes?.routes ?? []).map((r) => [r.edge, r.points]));

package/src/highways/free-lines.ts

@@ -0,0 +1,141 @@
+import { dist, polylineLength, type Point } from "../geom.ts";
+import type { Graph } from "../model.ts";
+import { boardGaps } from "../room/index.ts";
+import type { WayFinder } from "../ways.ts";
+import { firstRoutes } from "./base.ts";
+import type { HighwayInput } from "./model.ts";
+import { edgePlugs } from "./stretches.ts";
+
+/** The source of the candidate streets: the middle lines of the gaps of the room step, or the lines through the corners. */
+export type StreetSource = "room" | "corners";
+
+/** The values of `StreetSource`. */
+export const STREET_SOURCES: readonly StreetSource[] = Object.freeze(["room", "corners"]);
+
+/** One axis-parallel street in the free space, from `a` to `b`. */
+export interface FreeLine {
+  readonly a: Point;
+  readonly b: Point;
+}
+
+/** One edge for the streets: its two points out of its plugs, and the length of its first route. */
+export interface StreetEdge {
+  readonly edge: string;
+  readonly s: Point;
+  readonly t: Point;
+  readonly base: number;
+}
+
+/** The ride of one edge on one street. It has the points where the edge joins and leaves the street, and two lengths. */
+export interface StreetRide {
+  readonly on: Point;
+  readonly off: Point;
+  /** The length on the street. */
+  readonly ride: number;
+  /** The length of the two ramps, to the street and from it. */
+  readonly ramps: number;
+}
+
+const round = (v: number): number => Math.round(v * 2) / 2;
+
+/**
+ * This function gives the free pieces of the line `x = c` (axis `x`) or `y = c` (axis `y`). A box closer than `pad` to the line blocks it.
+ * A piece shorter than `min` is not in the list. The pieces run over the board and `2 pad` past it.
+ */
+function freePieces(finder: WayFinder, axis: "x" | "y", c: number, pad: number, min: number, lo: number, hi: number): FreeLine[] {
+  const blocks: [number, number][] = [];
+  const strip = axis === "x" ? { x: c - pad, y: lo, w: 2 * pad, h: hi - lo } : { x: lo, y: c - pad, w: hi - lo, h: 2 * pad };
+  finder.obstacles.query(strip, (n) => {
+    const a = axis === "x" ? n.box.x : n.box.y;
+    const w = axis === "x" ? n.box.w : n.box.h;
+    if (c <= a - pad || c >= a + w + pad) return;
+    const b = axis === "x" ? n.box.y : n.box.x;
+    const h = axis === "x" ? n.box.h : n.box.w;
+    blocks.push([b - pad, b + h + pad]);
+  });
+  blocks.sort((p, q) => p[0] - q[0] || p[1] - q[1]);
+  const out: FreeLine[] = [];
+  const at = (u: number): Point => (axis === "x" ? { x: c, y: u } : { x: u, y: c });
+  let from = lo;
+  for (const [s, e] of blocks) {
+    if (s - from >= min) out.push({ a: at(from), b: at(s) });
+    from = Math.max(from, e);
+  }
+  if (hi - from >= min) out.push({ a: at(from), b: at(hi) });
+  return out;
+}
+
+/**
+ * This function gives the candidate streets of a board. Each street is an axis-parallel piece of free space.
+ * The source `room` takes the middle line of each gap of `boardGaps` that is two margins wide or more.
+ * The source `corners` takes the lines one margin out from each side of each box.
+ * A street is two margins long or more. The list has no copies, and its order is the same each time.
+ */
+export function freeLines(graph: Graph, finder: WayFinder, source: StreetSource): FreeLine[] {
+  const nodes = graph.nodes;
+  if (nodes.length === 0) return [];
+  const m = finder.margin;
+  const pad = m / 2;
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const n of nodes) {
+    x0 = Math.min(x0, n.box.x);
+    y0 = Math.min(y0, n.box.y);
+    x1 = Math.max(x1, n.box.x + n.box.w);
+    y1 = Math.max(y1, n.box.y + n.box.h);
+  }
+  const lines: { axis: "x" | "y"; c: number }[] = [];
+  if (source === "room") {
+    for (const g of boardGaps(nodes)) if (g.width >= 2 * m) lines.push({ axis: g.axis, c: round(g.at - g.width / 2) });
+  } else {
+    for (const n of nodes) {
+      lines.push({ axis: "x", c: round(n.box.x - m) }, { axis: "x", c: round(n.box.x + n.box.w + m) });
+      lines.push({ axis: "y", c: round(n.box.y - m) }, { axis: "y", c: round(n.box.y + n.box.h + m) });
+    }
+  }
+  const seen = new Set<string>();
+  const out: FreeLine[] = [];
+  const sorted = [...lines].sort((p, q) => (p.axis === q.axis ? p.c - q.c : p.axis < q.axis ? -1 : 1));
+  for (const l of sorted) {
+    const k = `${l.axis}${l.c}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    const [lo, hi] = l.axis === "x" ? [y0 - 2 * m, y1 + 2 * m] : [x0 - 2 * m, x1 + 2 * m];
+    out.push(...freePieces(finder, l.axis, l.c, pad, 2 * m, lo, hi));
+  }
+  return out;
+}
+
+/** This function gives the edges of the input for the streets, with the points out of their plugs and the lengths of their first routes. */
+export function streetEdges(input: HighwayInput, finder: WayFinder): StreetEdge[] {
+  const first = firstRoutes(input);
+  const out: StreetEdge[] = [];
+  for (const p of edgePlugs(input.graph)) {
+    const route = first.get(p.edge.id);
+    const s = finder.out(p.ps);
+    const t = finder.out(p.pt);
+    out.push({ edge: p.edge.id, s, t, base: route ? polylineLength(route) : dist(s, t) });
+  }
+  return out;
+}
+
+/** This function gives the point of the street nearest to `p`. */
+export function streetPoint(line: FreeLine, p: Point): Point {
+  if (line.a.x === line.b.x) {
+    const lo = Math.min(line.a.y, line.b.y);
+    const hi = Math.max(line.a.y, line.b.y);
+    return { x: line.a.x, y: Math.min(hi, Math.max(lo, p.y)) };
+  }
+  const lo = Math.min(line.a.x, line.b.x);
+  const hi = Math.max(line.a.x, line.b.x);
+  return { x: Math.min(hi, Math.max(lo, p.x)), y: line.a.y };
+}
+
+/** This function gives the ride of an edge on a street. The edge joins the street at the point nearest to `s`, and leaves it at the point nearest to `t`. */
+export function streetRide(line: FreeLine, e: StreetEdge): StreetRide {
+  const on = streetPoint(line, e.s);
+  const off = streetPoint(line, e.t);
+  return { on, off, ride: dist(on, off), ramps: dist(e.s, on) + dist(off, e.t) };
+}

package/src/highways/gaps/index.ts

@@ -0,0 +1,85 @@
+import { WayFinder } from "../../ways.ts";
+import { freeLines, streetEdges, streetRide, type FreeLine, type StreetEdge, type StreetSource } from "../free-lines.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { snapPlan, type SnapLine } from "../snap.ts";
+
+/** The options of the highway strategy `gaps` (HWY-057 of the note on highways). */
+export interface GapOptions {
+  /** A street with fewer edges than this number (the demand `k`) is not a highway. The default is 3. */
+  readonly minSize: number;
+  /** The cost of a length on a street against a length off the streets, from 0.1 to 0.8. The default is 0.5. */
+  readonly discount: number;
+  /** An edge rides a street only when its way along the street is this many times its first route or less. The default is 1.3. */
+  readonly detour: number;
+  /** The source of the streets: the gaps of the room step, or the lines through the corners. The default is `room`. */
+  readonly source: StreetSource;
+}
+
+/** The default options of the strategy `gaps`. */
+export const GAP_DEFAULTS: Readonly<GapOptions> = Object.freeze({ minSize: 3, discount: 0.5, detour: 1.3, source: "room" });
+
+/** The best street of an edge, from the streets in `open`. The ride costs `discount` times its length. The way is at most `detour` times the first route. */
+function bestStreet(lines: readonly FreeLine[], open: ReadonlySet<number>, e: StreetEdge, o: Readonly<GapOptions>, min: number): number {
+  let best = -1;
+  let bestSaving = 1e-9;
+  for (const i of open) {
+    const r = streetRide(lines[i]!, e);
+    if (r.ride < min) continue;
+    if (r.ramps + r.ride > o.detour * e.base) continue;
+    const saving = e.base - (r.ramps + o.discount * r.ride);
+    if (saving > bestSaving || (saving === bestSaving && i < best)) [best, bestSaving] = [i, saving];
+  }
+  return best;
+}
+
+/**
+ * This function gives the highways on the gaps of the board (HWY-057). The streets are the free middle lines of the gaps.
+ * Each edge takes the street that saves it the most cost, when a length on a street costs `discount` times its length.
+ * A street with `minSize` edges or more becomes a highway. The edges of the other streets then choose again among the highways, two times.
+ */
+export function gapPlan(input: HighwayInput, o: Readonly<GapOptions>): HighwayPlan {
+  const finder = new WayFinder(input.graph.nodes);
+  const lines = freeLines(input.graph, finder, o.source);
+  const edges = streetEdges(input, finder);
+  const min = 2 * finder.margin;
+  const size = Math.max(2, Math.round(o.minSize));
+  let open = new Set(lines.map((_, i) => i));
+  let choice = new Map<string, number>();
+  for (let round = 0; round < 3; round++) {
+    choice = new Map();
+    const count = new Map<number, number>();
+    for (const e of edges) {
+      const i = bestStreet(lines, open, e, o, min);
+      if (i < 0) continue;
+      choice.set(e.edge, i);
+      count.set(i, (count.get(i) ?? 0) + 1);
+    }
+    const kept = new Set([...open].filter((i) => (count.get(i) ?? 0) >= size));
+    if (kept.size === open.size) break;
+    open = kept;
+  }
+  const byLine = new Map<number, SnapLine["members"][number][]>();
+  for (const e of edges) {
+    const i = choice.get(e.edge);
+    if (i === undefined || !open.has(i)) continue;
+    const r = streetRide(lines[i]!, e);
+    const list = byLine.get(i) ?? [];
+    list.push({ edge: e.edge, from: r.on, to: r.off, at: 0 });
+    byLine.set(i, list);
+  }
+  const snaps: SnapLine[] = [...byLine.keys()]
+    .sort((p, q) => p - q)
+    .map((i) => {
+      const members = byLine.get(i)!;
+      // The spine runs only over the part of the street that its members ride.
+      const line = lines[i]!;
+      const vertical = line.a.x === line.b.x;
+      const us = members.flatMap((m) => (vertical ? [m.from.y, m.to.y] : [m.from.x, m.to.x]));
+      const lo = Math.min(...us);
+      const hi = Math.max(...us);
+      const a = vertical ? { x: line.a.x, y: lo } : { x: lo, y: line.a.y };
+      const b = vertical ? { x: line.a.x, y: hi } : { x: hi, y: line.a.y };
+      return { key: `gap${i}`, a, b, members };
+    });
+  return snapPlan(input, snaps, { minSize: size, direct: true });
+}

package/src/highways/index.ts

@@ -97,5 +97,11 @@ export { LINK_COMMUNITY_DEFAULTS, linkCommunities, linkCommunityGroups, linkComm
 export { cellSteps, nearestCentre, pointGroups, TERRITORY_DEFAULTS, TERRITORY_POINTS, territoryPlan, type CellStep, type TerritoryOptions, type TerritoryPoints } from "./territories/index.ts";
 export { coAssociation, CONSENSUS_DEFAULTS, CONSENSUS_LINKAGES, consensusGroups, consensusLabels, consensusPlan, type ConsensusLinkage, type ConsensusOptions } from "./consensus/index.ts";
 export { HUB_ALLOCATIONS, HUB_CANDIDATES, hubCandidates, P_HUB_DEFAULTS, pHubPlan, pMedian, type HubAllocation, type HubCandidates, type PHubOptions } from "./p-hub/index.ts";
+export { freeLines, STREET_SOURCES, streetEdges, streetPoint, streetRide, type FreeLine, type StreetEdge, type StreetRide, type StreetSource } from "./free-lines.ts";
+export { oneSteiner, spanningTree, STEINER_DEFAULTS, STEINER_GROUPS, STEINER_METHODS, STEINER_METRICS, steinerPlan, type SteinerGroup, type SteinerMethod, type SteinerMetric, type SteinerOptions } from "./steiner/index.ts";
+export { GAP_DEFAULTS, gapPlan, type GapOptions } from "./gaps/index.ts";
+export { STREET_DEFAULTS, streetPlan, type StreetOptions } from "./streets/index.ts";
+export { SEARCH_DEFAULTS, SEARCH_MOVES, searchPlan, searchScore, type SearchMove, type SearchOptions } from "./search/index.ts";
+export { INTERCHANGE_BASES, INTERCHANGE_DEFAULTS, interchangeCandidates, interchangePlan, type Interchange, type InterchangeBase, type InterchangeOptions } from "./interchanges/index.ts";
 export { SCALE_SPACE_DEFAULTS, scaleClusters, scaleSpaceGroups, scaleSpacePlan, type ScaleCluster, type ScaleSpaceOptions } from "./scale-space/index.ts";
 export * from "./gates/index.ts";