@mark1russell7/highways 0.9.4 → 0.9.5

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/core"
   },
   "homepage": "https://mark1russell7.github.io/highways/",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/src/bench/screen/exercise.ts

@@ -84,13 +84,14 @@ export const MOVE_NAMES: Readonly<Record<string, string>> = Object.freeze({
   interchanges: "networkRoad",
   knee: "tree",
   bronchial: "tree",
+  manifolds: "manifold",
 });
 
 /**
  * The highway strategies that change the plan of another strategy (`from`). Their own move is a change of that plan, so they count no move.
  * The output against the plan `from` tells if they ran.
  */
-export const PLAN_CHANGERS: readonly string[] = Object.freeze(["crossbars", "divided", "lanes", "level-links", "meet", "stubs", "weiszfeld", "zipper"]);
+export const PLAN_CHANGERS: readonly string[] = Object.freeze(["balance", "crossbars", "divided", "lanes", "level-links", "meet", "slots", "stubs", "weiszfeld", "zipper"]);
 
 const FINDERS: readonly string[] = [...new Set([...Object.keys(highwayStrategies).filter((n) => !n.includes("+")), "shared-ways-all"])].sort((a, b) => b.length - a.length);
 

package/src/highways/balance/index.ts

@@ -0,0 +1,93 @@
+/**
+ * The highway strategy `balance` (EDA-017): the stretch of each edge of a bundle stays near a target.
+ * A Lagrange price for each edge grows while its stretch is above the target, and the price moves the exit of the edge forward.
+ */
+import { polylineLength } from "../../geom.ts";
+import { outerGraph, type Graph } from "../../model.ts";
+import { basePlan, tidyPlan, type HighwayBase } from "../base.ts";
+import { follow } from "../follow.ts";
+import { lengthBetween, memberAt, type HighwayInput, type HighwayMember, type HighwayPlan } from "../model.ts";
+
+/** The end of a ride that the price moves: the exit, the entry, or both by half. */
+export type BalanceEnd = "exit" | "entry" | "both";
+
+/** The values of `BalanceEnd`. */
+export const BALANCE_ENDS: readonly BalanceEnd[] = Object.freeze(["exit", "entry", "both"]);
+
+/** The options of the highway strategy `balance` (EDA-017). */
+export interface BalanceOptions {
+  /** The target of the stretch of an edge: its route on the plan over its route alone, from 1.1 to 2. The default is 1.2. */
+  readonly tau: number;
+  /** The number of updates of the prices, from 5 to 30. The default is 5. */
+  readonly iterations: number;
+  /** The end of a ride that the price moves. The default is `exit`. */
+  readonly end: BalanceEnd;
+  /** The plan that the strategy balances. The default is `shared-ways`. */
+  readonly from: HighwayBase;
+}
+
+/** The default options of the strategy `balance`. */
+export const BALANCE_DEFAULTS: Readonly<BalanceOptions> = Object.freeze({ tau: 1.2, iterations: 5, end: "exit", from: "shared-ways" });
+
+/** The margin of the way finder of `follow`. A ride shorter than this length leaves the plan. */
+const MARGIN = 5;
+
+/** This function gives the length of the route of each edge of a plan after `follow`. */
+function routeLengths(graph: Graph, plan: HighwayPlan): Map<string, number> {
+  return new Map(follow(graph, plan).routes.map((r) => [r.edge, polylineLength(r.points)]));
+}
+
+/**
+ * This function gives the plan of the highway strategy `balance` (EDA-017, after the Lagrange relaxation of the stretch).
+ * The stretch of an edge is its route on the plan over its route alone, as the gate `stretch` measures it.
+ * At each update, an edge with a stretch above `tau` adds `stretch - tau` to its price. Each of its rides keeps the share `1 - price` of its first length.
+ * A ride shorter than the margin leaves the plan. The updates stop when no edge is above `tau`.
+ */
+export function balancePlan(input: HighwayInput, options: Partial<BalanceOptions> = {}): HighwayPlan {
+  const o = { ...BALANCE_DEFAULTS, ...options };
+  const graph = outerGraph(input.graph);
+  return balanceOf(graph, basePlan({ ...input, graph }, o.from), o);
+}
+
+/** This function balances the plan `first` of the graph, as `balancePlan` does. It reads all the options except `from`. */
+export function balanceOf(graph: Graph, first: HighwayPlan, options: Partial<BalanceOptions> = {}): HighwayPlan {
+  const o = { ...BALANCE_DEFAULTS, ...options };
+  const riders = new Set(first.highways.flatMap((h) => h.members.map((m) => m.edge)));
+  if (riders.size === 0) return first;
+  const sub: Graph = { nodes: graph.nodes, edges: graph.edges.filter((e) => riders.has(e.id)) };
+  const alone = routeLengths(sub, { highways: [] });
+  const price = new Map<string, number>();
+  let plan = first;
+  for (let k = 0; k < Math.max(1, Math.floor(o.iterations)); k++) {
+    const along = routeLengths(sub, plan);
+    let over = false;
+    for (const [edge, length] of along) {
+      const base = alone.get(edge) ?? 0;
+      if (base <= 1e-9) continue;
+      const stretch = length / base;
+      if (stretch <= o.tau + 1e-9) continue;
+      price.set(edge, (price.get(edge) ?? 0) + stretch - o.tau);
+      over = true;
+    }
+    if (!over) break;
+    // Each update cuts the rides of the first plan by the prices as they are now.
+    plan = tidyPlan({
+      highways: first.highways.map((h) => ({
+        ...h,
+        members: h.members.flatMap((m): HighwayMember[] => {
+          const keep = 1 - Math.min(1, price.get(m.edge) ?? 0);
+          if (keep >= 1) return [m];
+          const span = m.off - m.on;
+          // The exit moves back toward the entry, the entry moves forward toward the exit, or each moves by half the cut.
+          const cut = (1 - keep) * span;
+          const on = o.end === "entry" ? m.on + cut : o.end === "both" ? m.on + cut / 2 : m.on;
+          const off = o.end === "exit" ? m.off - cut : o.end === "both" ? m.off - cut / 2 : m.off;
+          if (lengthBetween(h.spine, Math.min(on, off), Math.max(on, off)) < MARGIN) return [];
+          return [memberAt(h.spine, m.edge, on, off, m.seq)];
+        }),
+      })),
+    });
+    if (plan.highways.length === 0) break;
+  }
+  return plan;
+}

package/src/highways/index.ts

@@ -103,6 +103,9 @@ 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 { KNEE_DEFAULTS, KNEE_RULES, kneeOf, kneePlan, type KneeOptions, type KneeRule, type KneeTree } from "./knee/index.ts";
+export { BALANCE_DEFAULTS, BALANCE_ENDS, balanceOf, balancePlan, type BalanceEnd, type BalanceOptions } from "./balance/index.ts";
+export { SLOT_DEFAULTS, SLOT_KEYS, slotJoin, slotPlan, slotsOf, type SlotJoin, type SlotKeys, type SlotOptions } from "./slots/index.ts";
+export { MANIFOLD_DEFAULTS, MANIFOLD_SIDES, manifoldPlan, type ManifoldOptions, type ManifoldSide } from "./manifolds/index.ts";
 export { BRONCHIAL_DEFAULTS, BRONCHIAL_SPLITS, bronchialPlan, diamondAngle, splitTargets, type BronchialOptions, type BronchialSplit } from "./bronchial/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";

package/src/highways/manifolds/index.ts

@@ -0,0 +1,157 @@
+/**
+ * The highway strategy `manifolds` (WILD-036): a header for a fan from one node to a row of nodes.
+ * The header lies in the gap before the row, the taps leave it at right angles, and the feed joins it from the node.
+ */
+import { center, dist, type Point } from "../../geom.ts";
+import { nodeIndex, outerGraph, type Node } from "../../model.ts";
+import { basePlan, tidyPlan, type HighwayBase } from "../base.ts";
+import { keepMembers } from "../gates/model.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { snapPlan, type SnapLine } from "../snap.ts";
+
+/** The place of the header in the gap before the row: near the row, or near the feed node. */
+export type ManifoldSide = "near" | "far";
+
+/** The values of `ManifoldSide`. */
+export const MANIFOLD_SIDES: readonly ManifoldSide[] = Object.freeze(["near", "far"]);
+
+/** The options of the highway strategy `manifolds` (WILD-036). */
+export interface ManifoldOptions {
+  /** A manifold has this number of taps or more, from 3 to 8. The default is 3. */
+  readonly kMin: number;
+  /** The nodes of one row have centers in a band of this many median box heights, from 0.5 to 2. The default is 1. */
+  readonly band: number;
+  /** The place of the header in the gap before the row. The default is `near`. */
+  readonly side: ManifoldSide;
+  /** A tap stays on the manifold only when its way is this many times the direct line or less, from 1 to 3. The default is 1.5. */
+  readonly detour: number;
+  /** The plan of the edges that are not on a manifold. The default is `shared-ways`. */
+  readonly from: HighwayBase;
+}
+
+/** The default options of the strategy `manifolds`. */
+export const MANIFOLD_DEFAULTS: Readonly<ManifoldOptions> = Object.freeze({ kMin: 3, band: 1, side: "near", detour: 1.5, from: "shared-ways" });
+
+/** One end of a fan: an edge from the feed node to a far node. */
+interface Tap {
+  readonly edge: string;
+  readonly far: Node;
+  /** With `true`, the feed node is the source of the edge. */
+  readonly out: boolean;
+}
+
+/** A manifold that the strategy can make: the feed node, the axis of the header, its place across the axis and its taps. */
+interface Candidate {
+  readonly feed: Node;
+  /** With `x`, the header is horizontal. With `y`, the header is vertical. */
+  readonly axis: "x" | "y";
+  readonly at: number;
+  readonly taps: readonly Tap[];
+}
+
+/** This function gives the median of the values, or 0 when there is none. */
+function median(values: readonly number[]): number {
+  if (values.length === 0) return 0;
+  const s = [...values].sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)]!;
+}
+
+/** This function compares two texts in the order of their code units. */
+function byId(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * This function gives the manifolds that the strategy can make from one feed node, for one axis of the header.
+ * The far centers go in bands across the axis. A band with `kMin` taps or more, wholly on one side of the feed node, is a candidate.
+ */
+function candidatesOf(feed: Node, taps: readonly Tap[], axis: "x" | "y", band: number, o: Readonly<ManifoldOptions>, margin: number): Candidate[] {
+  const across = axis === "x" ? "y" : "x";
+  const size = axis === "x" ? "h" : "w";
+  const sorted = [...taps].sort((a, b) => center(a.far.box)[across] - center(b.far.box)[across] || byId(a.edge, b.edge));
+  const out: Candidate[] = [];
+  const lo = feed.box[across];
+  const hi = lo + feed.box[size];
+  // The share of the gap from the row to its header: a third with `near`, two thirds with `far`.
+  const share = o.side === "near" ? 1 / 3 : 2 / 3;
+  for (let i = 0; i < sorted.length; ) {
+    let j = i;
+    const first = center(sorted[i]!.far.box)[across];
+    while (j + 1 < sorted.length && center(sorted[j + 1]!.far.box)[across] - first <= band) j++;
+    const row = sorted.slice(i, j + 1);
+    i = j + 1;
+    if (row.length < o.kMin) continue;
+    const top = Math.min(...row.map((t) => t.far.box[across]));
+    const bottom = Math.max(...row.map((t) => t.far.box[across] + t.far.box[size]));
+    if (hi + 2 * margin <= top) out.push({ feed, axis, at: top - share * (top - hi), taps: row });
+    else if (bottom + 2 * margin <= lo) out.push({ feed, axis, at: bottom + share * (lo - bottom), taps: row });
+  }
+  return out;
+}
+
+/**
+ * This function gives the plan of the highway strategy `manifolds` (WILD-036, after the headers of pipes and of bus bars).
+ * A fan of `kMin` edges or more from one node to a row of nodes gets a straight header in the gap before the row.
+ * Each edge of the fan joins the header at the feed point, in line with the center of the node. It leaves the header at its tap, in line with the center of its far node.
+ * A tap whose way is more than `detour` times the direct line leaves the manifold. Each edge is on one manifold at most. The other edges keep the plan `from`.
+ */
+export function manifoldPlan(input: HighwayInput, options: Partial<ManifoldOptions> = {}): HighwayPlan {
+  const o = { ...MANIFOLD_DEFAULTS, ...options };
+  const graph = outerGraph(input.graph);
+  const nodes = nodeIndex(graph);
+  const margin = 5;
+  const bandOf = { x: o.band * median(graph.nodes.map((n) => n.box.h)), y: o.band * median(graph.nodes.map((n) => n.box.w)) };
+  const fans = new Map<string, Tap[]>();
+  const add = (id: string, tap: Tap): void => {
+    const list = fans.get(id);
+    if (list) list.push(tap);
+    else fans.set(id, [tap]);
+  };
+  for (const e of graph.edges) {
+    const s = nodes.get(e.source.node);
+    const t = nodes.get(e.target.node);
+    if (!s || !t || s === t) continue;
+    add(s.id, { edge: e.id, far: t, out: true });
+    add(t.id, { edge: e.id, far: s, out: false });
+  }
+  const all: Candidate[] = [];
+  for (const [id, taps] of fans) {
+    if (taps.length < o.kMin) continue;
+    const feed = nodes.get(id)!;
+    for (const axis of ["x", "y"] as const) all.push(...candidatesOf(feed, taps, axis, bandOf[axis], o, margin));
+  }
+  // The largest manifolds go first. A tie goes to the node id, then to the axis, so the plan does not depend on the order of the map.
+  all.sort((a, b) => b.taps.length - a.taps.length || byId(a.feed.id, b.feed.id) || byId(a.axis, b.axis) || a.at - b.at);
+  const used = new Set<string>();
+  const lines: SnapLine[] = [];
+  for (const c of all) {
+    const fc = center(c.feed.box);
+    const feedPoint: Point = c.axis === "x" ? { x: fc.x, y: c.at } : { x: c.at, y: fc.y };
+    const tapOf = (t: Tap): Point => {
+      const tc = center(t.far.box);
+      return c.axis === "x" ? { x: tc.x, y: c.at } : { x: c.at, y: tc.y };
+    };
+    const taps = c.taps.filter((t) => {
+      if (used.has(t.edge)) return false;
+      const tc = center(t.far.box);
+      return dist(fc, feedPoint) + dist(feedPoint, tapOf(t)) + dist(tapOf(t), tc) <= o.detour * dist(fc, tc);
+    });
+    if (taps.length < o.kMin) continue;
+    const along = [feedPoint, ...taps.map(tapOf)].map((p) => p[c.axis]);
+    const lo = Math.min(...along);
+    const hi = Math.max(...along);
+    const a: Point = c.axis === "x" ? { x: lo, y: c.at } : { x: c.at, y: lo };
+    const b: Point = c.axis === "x" ? { x: hi, y: c.at } : { x: c.at, y: hi };
+    for (const t of taps) used.add(t.edge);
+    lines.push({
+      key: `manifold:${c.feed.id}:${c.axis}`,
+      a,
+      b,
+      members: taps.map((t) => (t.out ? { edge: t.edge, from: feedPoint, to: tapOf(t), at: 0.5 } : { edge: t.edge, from: tapOf(t), to: feedPoint, at: 0.5 })),
+    });
+  }
+  const manifolds = snapPlan({ graph }, lines, { minSize: Math.max(2, o.kMin), direct: true });
+  const riding = new Set(manifolds.highways.flatMap((h) => h.members.map((m) => m.edge)));
+  const base = keepMembers(basePlan({ ...input, graph }, o.from), (_, m) => !riding.has(m.edge));
+  return tidyPlan({ highways: [...manifolds.highways, ...base.highways] });
+}

package/src/highways/slots/index.ts

@@ -0,0 +1,178 @@
+/**
+ * The highway strategy `slots` (RULE-047): a pull of each route toward the lane slots of the highway skeleton.
+ * An edge whose first route runs near a trunk of the plan joins that trunk when the pull is larger than its detour.
+ */
+import { checkProperties } from "../../bench/properties.ts";
+import { dist, polylineLength, type Point } from "../../geom.ts";
+import { outerGraph, type Graph } from "../../model.ts";
+import { byCollection } from "../../routers/trunks.ts";
+import { basePlan, firstRoutes, nearestPlace, tidyPlan, type HighwayBase } from "../base.ts";
+import { follow } from "../follow.ts";
+import { lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayPlan } from "../model.ts";
+
+/** The edges that can join a trunk: only the edges with the key of the trunk, or each edge. */
+export type SlotKeys = "same" | "any";
+
+/** The values of `SlotKeys`. */
+export const SLOT_KEYS: readonly SlotKeys[] = Object.freeze(["same", "any"]);
+
+/** The options of the highway strategy `slots` (RULE-047). */
+export interface SlotOptions {
+  /** The weight `k` of the pull, from 0.25 to 8. The default is 2. The name is not `k`, because `follow` reads `k` as an option of its ways. */
+  readonly pull: number;
+  /** The reach `r` of the pull, in units, from 8 to 64. A route point farther than this distance from a trunk gets no pull. The default is 24. */
+  readonly reach: number;
+  /** The distance between two lanes of a trunk, in units, from 2 to 8. The default is 4. */
+  readonly laneSpacing: number;
+  /** The largest stretch of a route after it joins a trunk: its new length over its first length, from 1.05 to 2. The default is 1.25. */
+  readonly maxStretch: number;
+  /** The edges that can join a trunk. The default is `same`. */
+  readonly keys: SlotKeys;
+  /** The plan that gives the trunks. The default is `shared-ways`. */
+  readonly from: HighwayBase;
+}
+
+/** The default options of the strategy `slots`. */
+export const SLOT_DEFAULTS: Readonly<SlotOptions> = Object.freeze({ pull: 2, reach: 24, laneSpacing: 4, maxStretch: 1.25, keys: "same", from: "shared-ways" });
+
+/** One sample of a route: a point and its length from the first point of the route. */
+interface Sample {
+  readonly p: Point;
+  readonly arc: number;
+}
+
+/** One possible join of an edge to a trunk: the trunk, the places on its spine, the pull and the detour. */
+export interface SlotJoin {
+  readonly highway: number;
+  readonly on: number;
+  readonly off: number;
+  /** The pull energy that the join removes: `k × Σ w(d) × (d - slot)² × step / r²`, in units of length. */
+  readonly pull: number;
+  /** The length that the join adds to the route, as an estimate. */
+  readonly detour: number;
+}
+
+/** This function gives points along a polyline, one at each `step` of length, and the last point. */
+function samplesOf(points: readonly Point[], step: number): Sample[] {
+  const out: Sample[] = [];
+  if (points.length === 0) return out;
+  out.push({ p: points[0]!, arc: 0 });
+  let walked = 0;
+  let next = step;
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1]!;
+    const b = points[i]!;
+    const len = dist(a, b);
+    while (len > 0 && next <= walked + len) {
+      const u = (next - walked) / len;
+      out.push({ p: { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u }, arc: next });
+      next += step;
+    }
+    walked += len;
+  }
+  if (walked > out[out.length - 1]!.arc + 1e-9) out.push({ p: points[points.length - 1]!, arc: walked });
+  return out;
+}
+
+/**
+ * This function gives the best join of one route to the trunk `h`, or `undefined`.
+ * The longest row of samples nearer than `reach` to the spine is the part of the route that the trunk pulls.
+ * The slot of the new lane is at `laneSpacing × (lanes + 1) / 2` from the spine. The weight is `w(d) = max(0, 1 - d / r)`.
+ */
+export function slotJoin(route: readonly Point[], h: Highway, index: number, o: Readonly<SlotOptions>): SlotJoin | undefined {
+  const step = Math.max(2, o.reach / 4);
+  const samples = samplesOf(route, step);
+  const offset = (o.laneSpacing * (h.lanes.length + 1)) / 2;
+  let best: { from: number; to: number } | undefined;
+  let start = -1;
+  const near = samples.map((s) => {
+    const at = nearestPlace(h.spine, s.p);
+    return { at, d: dist(s.p, pointAt(h.spine, at)) };
+  });
+  for (let i = 0; i <= samples.length; i++) {
+    const inside = i < samples.length && near[i]!.d < o.reach;
+    if (inside && start < 0) start = i;
+    if (!inside && start >= 0) {
+      if (!best || samples[i - 1]!.arc - samples[start]!.arc > samples[best.to]!.arc - samples[best.from]!.arc) best = { from: start, to: i - 1 };
+      start = -1;
+    }
+  }
+  if (!best || best.to <= best.from) return undefined;
+  const on = near[best.from]!.at;
+  const off = near[best.to]!.at;
+  const ride = lengthBetween(h.spine, Math.min(on, off), Math.max(on, off));
+  if (ride < 2 * o.reach || Math.abs(on - off) < 1e-9) return undefined;
+  let pull = 0;
+  for (let i = best.from; i <= best.to; i++) {
+    const d = near[i]!.d;
+    const w = Math.max(0, 1 - d / o.reach);
+    const gap = d - offset;
+    pull += w * gap * gap;
+  }
+  pull = (o.pull * pull * step) / (o.reach * o.reach);
+  const arc = samples[best.to]!.arc - samples[best.from]!.arc;
+  const detour = near[best.from]!.d + near[best.to]!.d + ride - arc;
+  return { highway: index, on, off, pull, detour };
+}
+
+/**
+ * This function gives the plan of the highway strategy `slots` (RULE-047, after the pull of force-directed edge bundling, Holten and van Wijk 2009).
+ * The trunks are the highways of the plan `from`. Each edge outside the plan gets a pull toward the slot of a new lane of a trunk near its first route.
+ * The energy of the pull is `E = k Σ w(d_i) ‖x_i - slot_i‖²` over the samples of the route, with `w(d) = max(0, 1 - d / r)`.
+ * The edge joins the trunk when the pull is larger than the length that the join adds, and the stretch stays under `maxStretch`.
+ * The edge takes the trunk with the largest gain, on the outer lane. An edge that does not fit stays off the trunks.
+ */
+export function slotPlan(input: HighwayInput, options: Partial<SlotOptions> = {}): HighwayPlan {
+  const o = { ...SLOT_DEFAULTS, ...options };
+  const graph = outerGraph(input.graph);
+  const first = basePlan({ ...input, graph }, o.from);
+  return slotsOf(graph, first, firstRoutes({ ...input, graph }), o);
+}
+
+/** This function adds the joins of `slotPlan` to the plan `first` of the graph. It reads all the options except `from`. A join that breaks a hard rule after `follow` leaves the plan. */
+export function slotsOf(graph: Graph, first: HighwayPlan, routes: ReadonlyMap<string, readonly Point[]>, options: Partial<SlotOptions> = {}): HighwayPlan {
+  const o = { ...SLOT_DEFAULTS, ...options };
+  if (first.highways.length === 0) return first;
+  const riders = new Set(first.highways.flatMap((h) => h.members.map((m) => m.edge)));
+  const added = first.highways.map(() => [] as { edge: string; on: number; off: number }[]);
+  const edges = [...graph.edges].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  for (const e of edges) {
+    if (riders.has(e.id)) continue;
+    const route = routes.get(e.id);
+    if (!route || route.length < 2) continue;
+    const length = polylineLength(route);
+    if (length <= 1e-9) continue;
+    const key = byCollection(e);
+    let best: SlotJoin | undefined;
+    first.highways.forEach((h, i) => {
+      if (o.keys === "same" && (key === undefined || h.key !== key)) return;
+      const j = slotJoin(route, h, i, o);
+      if (!j || j.pull <= j.detour || (length + Math.max(0, j.detour)) / length > o.maxStretch + 1e-9) return;
+      if (!best || j.pull - j.detour > best.pull - best.detour + 1e-9) best = j;
+    });
+    if (best) added[best.highway]!.push({ edge: e.id, on: best.on, off: best.off });
+  }
+  const build = (): HighwayPlan =>
+    tidyPlan({
+      highways: first.highways.map((h, i) => {
+        const more = added[i]!;
+        if (more.length === 0) return h;
+        return { ...h, lanes: [...h.lanes, ...more.map((m) => m.edge)], members: [...h.members, ...more.map((m) => memberAt(h.spine, m.edge, m.on, m.off, 0))] };
+      }),
+    });
+  // A join whose route after `follow` breaks a hard rule leaves the plan. A new break of a rider takes each join of its trunks off.
+  const before = new Set(checkProperties(graph, follow(graph, first), 1_000_000).flatMap((v) => (v.edge === undefined ? [] : [v.edge])));
+  for (let round = 0; round < 4; round++) {
+    if (added.every((list) => list.length === 0)) return first;
+    const plan = build();
+    const faulty = new Set(checkProperties(graph, follow(graph, plan), 1_000_000).flatMap((v) => (v.edge === undefined ? [] : [v.edge])));
+    const joined = new Set(added.flatMap((list) => list.map((m) => m.edge)));
+    const others = [...faulty].filter((e) => !joined.has(e) && !before.has(e));
+    if (![...faulty].some((e) => joined.has(e)) && others.length === 0) return plan;
+    first.highways.forEach((h, i) => {
+      const hit = others.some((e) => h.members.some((m) => m.edge === e));
+      added[i] = hit ? [] : added[i]!.filter((m) => !faulty.has(m.edge));
+    });
+  }
+  return first;
+}

package/src/index.ts

@@ -19,11 +19,17 @@ export * from "./room/lanes.ts";
 export * from "./room/levels/index.ts";
 export * from "./plugs/facing/index.ts";
 export * from "./plugs/spread/index.ts";
+export * from "./plugs/leaders/index.ts";
 export * from "./plugs/fix.ts";
 export * from "./levels/depths/index.ts";
 export * from "./whole/pipeline/index.ts";
 export * from "./levels/venation/index.ts";
+export * from "./levels/detail/index.ts";
 export * from "./whole/portfolio/index.ts";
+export * from "./whole/curriculum/index.ts";
+export * from "./whole/preferences/index.ts";
+export * from "./whole/fireflies/index.ts";
+export * from "./whole/tracing/index.ts";
 export * from "./bench/properties.ts";
 export * from "./bench/quality.ts";
 export * from "./bench/links.ts";

package/src/levels/detail/index.ts

@@ -0,0 +1,140 @@
+/**
+ * The level strategy `detail` (WILD-016 with EDA-038): the level of detail of the bundles of each zoom level.
+ * Two legs of level links that are closer on the screen than `pxMin` pixels become one stroke, with a width that grows with the count.
+ */
+import { segmentHitsBox, type Point } from "../../geom.ts";
+import type { Level, LevelItem, LevelLink } from "../../model.ts";
+import { itemSizes, PICK } from "../../pick.ts";
+import type { LevelInput } from "../../strategies/model.ts";
+import { depthLevels, type DepthLevelOptions } from "../depths/index.ts";
+
+/** The growth of the width of a stroke with the number of its edges. */
+export type WidthScale = "linear" | "sqrt" | "log";
+
+/** The values of `WidthScale`. */
+export const WIDTH_SCALES: readonly WidthScale[] = Object.freeze(["linear", "sqrt", "log"]);
+
+/** The options of the level strategy `detail`: the options of `depths`, and the limits of the collapse. */
+export interface DetailOptions extends DepthLevelOptions {
+  /** Two parallel legs closer than this number of pixels on the screen become one stroke, from 0.5 to 4. The default is 3. */
+  readonly pxMin: number;
+  /** A stroke holds this number of edges or more, from 2 to 5. The default is 2. */
+  readonly minCount: number;
+  /** The width of a stroke of one edge, in pixels, from 1 to 4. The default is 1.5. A renderer reads it with `detailWidth`. */
+  readonly w0: number;
+  /** The growth of the width of a stroke with its count. The default is `log`. */
+  readonly widthScale: WidthScale;
+}
+
+/** The default options of the level strategy `detail`. */
+export const DETAIL_DEFAULTS: Readonly<DetailOptions> = Object.freeze({ pxMin: 3, minCount: 2, w0: 1.5, widthScale: "log" });
+
+/**
+ * This function gives the width of a stroke of `count` edges, in pixels (WILD-016). With `log`, it is `w0 × (1 + log2(count))`.
+ * With `sqrt`, it is `w0 × sqrt(count)`. With `linear`, it is `w0 × count`.
+ */
+export function detailWidth(count: number, o: Pick<DetailOptions, "w0" | "widthScale"> = DETAIL_DEFAULTS): number {
+  const c = Math.max(1, count);
+  if (o.widthScale === "linear") return o.w0 * c;
+  if (o.widthScale === "sqrt") return o.w0 * Math.sqrt(c);
+  return o.w0 * (1 + Math.log2(c));
+}
+
+/** One inner leg of a level link, parallel to an axis. It has the index of the link and of its first point, its axis and its place across the axis. */
+interface Leg {
+  readonly link: number;
+  readonly at: number;
+  /** With `x`, the leg is horizontal. */
+  readonly axis: "x" | "y";
+  readonly across: number;
+  readonly lo: number;
+  readonly hi: number;
+  readonly count: number;
+}
+
+/** This function gives the inner legs of the links that are parallel to an axis. The first and the last leg of a link touch its items, so they stay. */
+function legsOf(links: readonly LevelLink[]): Leg[] {
+  const out: Leg[] = [];
+  links.forEach((l, link) => {
+    const p = l.points;
+    for (let at = 1; at + 2 < p.length; at++) {
+      const a = p[at]!;
+      const b = p[at + 1]!;
+      if (Math.abs(a.y - b.y) <= 1e-9 && Math.abs(a.x - b.x) > 1e-9) out.push({ link, at, axis: "x", across: a.y, lo: Math.min(a.x, b.x), hi: Math.max(a.x, b.x), count: l.count });
+      else if (Math.abs(a.x - b.x) <= 1e-9 && Math.abs(a.y - b.y) > 1e-9) out.push({ link, at, axis: "y", across: a.x, lo: Math.min(a.y, b.y), hi: Math.max(a.y, b.y), count: l.count });
+    }
+  });
+  return out;
+}
+
+/** This function takes out the repeated points and the points in the middle of a straight run. The first and the last point stay. */
+function tidy(p: readonly Point[]): Point[] {
+  const out: Point[] = [];
+  for (const q of p) {
+    const last = out[out.length - 1];
+    if (last && Math.abs(last.x - q.x) <= 1e-9 && Math.abs(last.y - q.y) <= 1e-9) continue;
+    if (out.length >= 2) {
+      const a = out[out.length - 2]!;
+      const b = out[out.length - 1]!;
+      const cross = (b.x - a.x) * (q.y - b.y) - (b.y - a.y) * (q.x - b.x);
+      const dot = (b.x - a.x) * (q.x - b.x) + (b.y - a.y) * (q.y - b.y);
+      if (Math.abs(cross) <= 1e-9 && dot > 0) out.pop();
+    }
+    out.push(q);
+  }
+  if (out.length < 2 && p.length >= 2) return [p[0]!, p[p.length - 1]!];
+  return out;
+}
+
+/**
+ * This function collapses the legs of the links of one level that are closer than `tol` (WILD-016, EDA-038).
+ * The legs of each axis go in clusters along the axis across it. The leg with the largest count of a cluster is its stroke, and each other leg moves onto it.
+ * A cluster needs two legs whose projections overlap, and a count of `minCount` or more. A move that puts a leg through the box of an item does not happen.
+ */
+export function collapseLinks(items: readonly LevelItem[], links: readonly LevelLink[], tol: number, minCount: number): LevelLink[] {
+  if (!(tol > 0)) return [...links];
+  const points = links.map((l) => [...l.points]);
+  const boxes = items.map((i) => i.box);
+  const clear = (a: Point, b: Point): boolean => boxes.every((box) => !segmentHitsBox(a, b, box, 1e-3));
+  for (const axis of ["x", "y"] as const) {
+    const legs = legsOf(links.map((l, i) => ({ ...l, points: points[i]! })))
+      .filter((g) => g.axis === axis)
+      .sort((a, b) => a.across - b.across || a.lo - b.lo || a.link - b.link || a.at - b.at);
+    const done = new Set<Leg>();
+    for (const anchor of [...legs].sort((a, b) => b.count - a.count || b.hi - b.lo - (a.hi - a.lo) || a.link - b.link || a.at - b.at)) {
+      if (done.has(anchor)) continue;
+      const near = legs.filter((g) => !done.has(g) && g !== anchor && g.link !== anchor.link && Math.abs(g.across - anchor.across) < tol && Math.min(g.hi, anchor.hi) - Math.max(g.lo, anchor.lo) > 1e-9);
+      if (near.length === 0 || near.reduce((s, g) => s + g.count, anchor.count) < minCount) continue;
+      done.add(anchor);
+      for (const g of near) {
+        done.add(g);
+        const p = points[g.link]!;
+        const a = p[g.at]!;
+        const b = p[g.at + 1]!;
+        // The leg moves only when its two points are still where the scan found them: an earlier move of the same link can change them.
+        if (axis === "x" ? a.y !== g.across || b.y !== g.across : a.x !== g.across || b.x !== g.across) continue;
+        const a2 = axis === "x" ? { x: a.x, y: anchor.across } : { x: anchor.across, y: a.y };
+        const b2 = axis === "x" ? { x: b.x, y: anchor.across } : { x: anchor.across, y: b.y };
+        if (!clear(p[g.at - 1]!, a2) || !clear(a2, b2) || !clear(b2, p[g.at + 2]!)) continue;
+        p[g.at] = a2;
+        p[g.at + 1] = b2;
+      }
+    }
+  }
+  return links.map((l, i) => (points[i]!.every((q, k) => q === l.points[k]) ? l : { ...l, points: tidy(points[i]!) }));
+}
+
+/**
+ * This function gives the zoom levels of the level strategy `detail` (WILD-016 with EDA-038). The levels and their items are the levels of `depths`.
+ * A level with groups first shows at the scale `itemAt / size`, with `size` its median item (`pickLevel`). At that scale, `pxMin` pixels are `pxMin × size / itemAt` units.
+ * The links of the level collapse their legs that are closer than that length (`collapseLinks`). The last level stays as in `depths`.
+ */
+export function detailLevels(input: LevelInput, options: Readonly<DetailOptions>): Level[] {
+  const levels = depthLevels(input, options);
+  const sizes = itemSizes(levels);
+  return levels.map((level, i) => {
+    if (i === levels.length - 1) return level;
+    const tol = (options.pxMin * sizes[i]!) / PICK.itemAt;
+    return { ...level, links: collapseLinks(level.items, level.links, tol, options.minCount) };
+  });
+}