@mark1russell7/highways 0.3.0 → 0.4.1

package/src/highways/follow.ts

@@ -0,0 +1,155 @@
+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 { placePlug } from "../plugs.ts";
+import { orderLanes, type RunOrder } from "../segments.ts";
+import { WayFinder, type WayOptions } from "../ways.ts";
+import { pointAt, type HighwayMember, type HighwayPlan } from "./model.ts";
+
+/** The options of `follow`. */
+export interface FollowOptions extends WayOptions {
+  /**
+   * These routes are the routes of the base router. Each edge outside the plan keeps its route from them.
+   * Without them, or for an edge without a route in them, `follow` routes the edge as the router `corners` does.
+   */
+  readonly routes?: Result;
+  /** The lane order of the shared runs. The default is `bundle`. */
+  readonly laneOrder?: RunOrder;
+}
+
+const SAME = 1e-6;
+
+const dedupe = (p: readonly Point[]): Point[] => p.filter((q, i) => i === 0 || dist(q, p[i - 1]!) > SAME);
+
+/** This function tells if a polyline holds the points of `part` in a row, in this order. */
+function holdsInOrder(p: readonly Point[], part: readonly Point[]): boolean {
+  for (let i = 0; i + part.length <= p.length; i++) {
+    let ok = true;
+    for (let j = 0; ok && j < part.length; j++) ok = dist(p[i + j]!, part[j]!) <= SAME;
+    if (ok) return true;
+  }
+  return false;
+}
+
+/** This function tells if a polyline holds the points of `part` in a row, in either direction. */
+const holds = (p: readonly Point[], part: readonly Point[]): boolean => holdsInOrder(p, part) || holdsInOrder(p, [...part].reverse());
+
+/**
+ * This function tells if a point of a spine can be the plug of an end. The point is on the box of the node.
+ * When the end has a fixed plug, the point is at that plug.
+ */
+function plugAt(node: Node, end: End, p: Point): boolean {
+  if (pointBoxDistance(p, node.box) > SAME) return false;
+  const fixed = fixedPortPoint(node, end);
+  return fixed === undefined || dist(fixed, p) <= SAME;
+}
+
+/** The stops of one spine: each point of the spine and each merge point and split point, by their place, in order. */
+type Stops = readonly (readonly [at: number, point: Point])[];
+
+/** This function gives the points of the stops from the place `on` to the place `off`. When `on` is larger than `off`, the points go backward. */
+function slice(stops: Stops, on: number, off: number): Point[] {
+  const lo = Math.min(on, off);
+  const hi = Math.max(on, off);
+  const out = stops.filter(([at]) => at >= lo && at <= hi).map(([, p]) => p);
+  return on <= off ? out : out.reverse();
+}
+
+/**
+ * This function routes the edges along a highway plan.
+ *
+ * An edge of a highway goes from its source plug to its merge point. Then it goes along the spine to its split point, and to its target plug.
+ * The ramps go around the boxes through the corner graph (`WayFinder.fromPlug` and `WayFinder.toPlug`).
+ * A spine point on the box of the node is the plug itself. When the end has a fixed plug, the point is at that plug.
+ *
+ * An edge on several highways takes them in the order of `seq`.
+ * A way through the corner graph goes from each split point to the next merge point.
+ * An edge outside the plan keeps its route from `options.routes`, or goes as in the router `corners`.
+ *
+ * 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 {
+  const byId = nodeIndex(graph);
+  const ways = new WayFinder(graph.nodes, options);
+  const base = new Map((options.routes?.routes ?? []).map((r) => [r.edge, r.points]));
+  const lines: Stops[] = plan.highways.map((h) => {
+    const stops = new Map<number, Point>(h.spine.map((p, i) => [i, p]));
+    for (const m of h.members) for (const at of [m.on, m.off]) if (!stops.has(at)) stops.set(at, pointAt(h.spine, at));
+    return [...stops].sort((a, b) => a[0] - b[0]);
+  });
+  const trips = new Map<string, { h: number; m: HighwayMember }[]>();
+  plan.highways.forEach((h, hi) => {
+    for (const m of h.members) {
+      const list = trips.get(m.edge);
+      if (list) list.push({ h: hi, m });
+      else trips.set(m.edge, [{ h: hi, m }]);
+    }
+  });
+  for (const list of trips.values()) list.sort((a, b) => a.m.seq - b.m.seq || a.h - b.h);
+
+  const routes: Route[] = [];
+  for (const e of graph.edges) {
+    const s = byId.get(e.source.node);
+    const t = byId.get(e.target.node);
+    if (!s || !t) continue;
+    const trip = trips.get(e.id);
+    if (!trip) {
+      const known = base.get(e.id);
+      if (known) {
+        routes.push({ edge: e.id, points: known });
+        continue;
+      }
+      const ps = placePlug(s, e.source, center(t.box));
+      const pt = placePlug(t, e.target, center(s.box));
+      routes.push({ edge: e.id, points: ways.between(ps, pt, new Set<Node>([s, t])) });
+      continue;
+    }
+    const out: Point[] = [];
+    let at: Point | undefined;
+    for (const { h, m } of trip) {
+      const piece = slice(lines[h]!, m.on, m.off);
+      const first = piece[0]!;
+      if (at === undefined) {
+        if (!plugAt(s, e.source, first)) {
+          const ps = placePlug(s, e.source, first);
+          out.push(...(ways.fromPlug(ps, first) ?? [ps.point, first]));
+        }
+      } else if (dist(at, first) > SAME) {
+        const way = ways.corners.path(at, first);
+        out.push(...(way ? ways.corners.pull(way) : [at, first]));
+      }
+      out.push(...piece);
+      at = piece[piece.length - 1]!;
+    }
+    if (at !== undefined && !plugAt(t, e.target, at)) {
+      const pt = placePlug(t, e.target, at);
+      out.push(...(ways.toPlug(at, pt) ?? [at, pt.point]));
+    }
+    routes.push({ edge: e.id, points: dedupe(out) });
+  }
+
+  // The runs: each stretch between two stops of a spine, with the same two edges or more on it, joined with the next stretch of the same edges.
+  const routeOf = new Map(routes.map((r) => [r.edge, r]));
+  const runs: SharedRun[] = [];
+  plan.highways.forEach((h, hi) => {
+    const stops = lines[hi]!;
+    const usersOf = (k: number): string[] =>
+      h.members
+        .filter((m) => routeOf.has(m.edge) && Math.min(m.on, m.off) <= stops[k]![0] && Math.max(m.on, m.off) >= stops[k + 1]![0])
+        .map((m) => m.edge)
+        .sort();
+    let k = 0;
+    while (k < stops.length - 1) {
+      const users = usersOf(k);
+      let end = k + 1;
+      while (end < stops.length - 1 && usersOf(end).join("\u0000") === users.join("\u0000")) end++;
+      const points = dedupe(stops.slice(k, end + 1).map(([, p]) => p));
+      k = end;
+      if (users.length < 2 || points.length < 2) continue;
+      const mine = users.map((id) => routeOf.get(id)!).filter((r) => holds(r.points, points));
+      if (mine.length < 2) continue;
+      runs.push({ id: `r${runs.length}`, key: h.key, points, edges: orderLanes(points, mine, options.laneOrder ?? "bundle") });
+    }
+  });
+  return runs.length > 0 ? { routes, runs } : { routes };
+}

package/src/highways/index.ts

@@ -0,0 +1,7 @@
+export { checkPlan, lengthBetween, memberAt, pointAt, type Highway, type HighwayInput, type HighwayMember, type HighwayPlan } from "./model.ts";
+export { follow, type FollowOptions } from "./follow.ts";
+export { planOfResult } from "./result.ts";
+export { highwayRouter, highwayRouterStrategy } from "./router.ts";
+export { keysPlan, type KeysOptions } from "./keys/index.ts";
+export { sharedWaysPlan, type SharedWaysOptions } from "./shared-ways/index.ts";
+export { BREAK_EVEN, CORRIDOR_DEFAULTS, corridorPlan, minHash, type CorridorOptions } from "./corridors/index.ts";

package/src/highways/keys/index.ts

@@ -0,0 +1,15 @@
+import { trunksRouter, type TrunksOptions } from "../../routers/trunks.ts";
+import { planOfResult } from "../result.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+
+/** The options of the highway strategy `keys`: the options of the router `trunks`, without the name and the limit of the benchmark. */
+export type KeysOptions = Omit<TrunksOptions, "name" | "maxNodes">;
+
+/**
+ * This function gives the highways that the router `trunks` decides. A rule gives each edge a key.
+ * The edges from one plug with one key share a trunk to a split point. The edges that go on together share a run past it.
+ * Each trunk and each run becomes one highway. The function does not change the router: it reads its bundles and its runs.
+ */
+export function keysPlan(input: HighwayInput, options: KeysOptions): HighwayPlan {
+  return planOfResult(trunksRouter({ ...options, name: "keys" }).route(input.graph));
+}

package/src/highways/model.ts

@@ -0,0 +1,111 @@
+import { dist, type Point } from "../geom.ts";
+import type { Graph, Result } from "../model.ts";
+
+/** The input of a highway strategy: the boxes and the edges, and optionally the first routes of a router. */
+export interface HighwayInput {
+  readonly graph: Graph;
+  /**
+   * These routes are the first routes, from a router. A strategy that reads first routes makes them itself when this value is absent.
+   * The strategy `corridors` makes the ways of the corner graph, as the router `corners` finds them.
+   */
+  readonly routes?: Result;
+}
+
+/**
+ * One edge of a highway. The edge joins the spine at the merge point and leaves it at the split point.
+ * A place on the spine is the index of a point of the spine plus the share of the next leg. Point `i` of the spine is at `i`.
+ * When `on` is larger than `off`, the edge goes along the spine from its last point to its first point.
+ */
+export interface HighwayMember {
+  readonly edge: string;
+  /** The place of the merge point on the spine. */
+  readonly on: number;
+  /** The place of the split point on the spine. */
+  readonly off: number;
+  /** The point where the edge joins the spine. */
+  readonly merge: Point;
+  /** The point where the edge leaves the spine. */
+  readonly split: Point;
+  /**
+   * The place of this highway in the trip of the edge, from 0. An edge can go along several highways, one after the other.
+   * `follow` takes the highways of an edge in the order of this value.
+   */
+  readonly seq: number;
+}
+
+/** A highway: a shared way that a bundle of edges follows, from their merge points to their split points. */
+export interface Highway {
+  readonly id: string;
+  /** The key of the highway, for example the key of the grouping rule or the index of a cluster. */
+  readonly key: string;
+  /** The spine: the polyline that the edges follow, in free space. */
+  readonly spine: readonly Point[];
+  /** The edges in lane order. Lane 0 is on the left of the spine, from its first point to its last point. The y axis points down. */
+  readonly lanes: readonly string[];
+  /** The edges with their merge points and their split points, in the order of `lanes`. */
+  readonly members: readonly HighwayMember[];
+}
+
+/** The output of a highway strategy: the highways, as data. `follow` routes the edges along them. */
+export interface HighwayPlan {
+  readonly highways: readonly Highway[];
+}
+
+/** This function gives the point at a place on a polyline. A place outside the polyline gives its nearest end. */
+export function pointAt(line: readonly Point[], at: number): Point {
+  if (line.length === 0) throw new Error("The polyline has no point.");
+  if (at <= 0) return line[0]!;
+  if (at >= line.length - 1) return line[line.length - 1]!;
+  const i = Math.floor(at);
+  const u = at - i;
+  const a = line[i]!;
+  if (u === 0) return a;
+  const b = line[i + 1]!;
+  return { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u };
+}
+
+/** This function gives the length of a polyline from the place `from` to the place `to`, with `from` not larger than `to`. */
+export function lengthBetween(line: readonly Point[], from: number, to: number): number {
+  if (to <= from) return 0;
+  let sum = 0;
+  let prev = pointAt(line, from);
+  for (let i = Math.floor(from) + 1; i < to; i++) {
+    const p = line[i]!;
+    sum += dist(prev, p);
+    prev = p;
+  }
+  return sum + dist(prev, pointAt(line, to));
+}
+
+/** This function gives a member of a highway with its merge point and its split point at the places `on` and `off` of the spine. */
+export function memberAt(spine: readonly Point[], edge: string, on: number, off: number, seq = 0): HighwayMember {
+  return { edge, on, off, merge: pointAt(spine, on), split: pointAt(spine, off), seq };
+}
+
+/**
+ * This function lists the problems of a plan against its graph. A good plan gives an empty list.
+ * Each highway has a spine of two points or more, and two members or more. Each member is an edge of the graph, with `on` and `off` on the spine and apart.
+ * An edge is a member of a highway one time at most.
+ */
+export function checkPlan(graph: Graph, plan: HighwayPlan): string[] {
+  const edges = new Set(graph.edges.map((e) => e.id));
+  const out: string[] = [];
+  const ids = new Set<string>();
+  for (const h of plan.highways) {
+    if (ids.has(h.id)) out.push(`Two highways have the id "${h.id}".`);
+    ids.add(h.id);
+    const last = h.spine.length - 1;
+    if (h.spine.length < 2) out.push(`The highway "${h.id}" has a spine with fewer than two points.`);
+    if (h.members.length < 2) out.push(`The highway "${h.id}" has fewer than two members.`);
+    const seen = new Set<string>();
+    for (const m of h.members) {
+      if (!edges.has(m.edge)) out.push(`The highway "${h.id}" has the member "${m.edge}", which is not an edge of the graph.`);
+      if (seen.has(m.edge)) out.push(`The highway "${h.id}" has the member "${m.edge}" two times.`);
+      seen.add(m.edge);
+      if (!(m.on >= 0 && m.on <= last && m.off >= 0 && m.off <= last)) out.push(`The member "${m.edge}" of the highway "${h.id}" has a place off the spine.`);
+      if (m.on === m.off) out.push(`The member "${m.edge}" of the highway "${h.id}" joins and leaves the spine at one place.`);
+    }
+    if (h.lanes.length !== h.members.length || h.lanes.some((e) => !seen.has(e))) out.push(`The lanes of the highway "${h.id}" are not its members.`);
+  }
+  return out;
+}

package/src/highways/result.ts

@@ -0,0 +1,34 @@
+import type { Result } from "../model.ts";
+import { segmentsOf } from "../segments.ts";
+import { memberAt, type Highway, type HighwayMember, type HighwayPlan } from "./model.ts";
+
+/**
+ * This function gives the highways of a result of a router: one highway for each shared run and for each trunk of a bundle.
+ * The spine is the points of the run or of the trunk. Each edge of the run is a member, from one end of the spine to the other end, in the way of its route.
+ * The member `seq` is the place of the shared stretch in the route of the edge. The lanes keep the lane order of the router.
+ *
+ * Thus `follow` routes each edge along the shared stretches of the router. A route that does not hold its run is not a member.
+ */
+export function planOfResult(result: Result): HighwayPlan {
+  const graph = segmentsOf(result);
+  const keys = new Map<string, string>([...(result.runs ?? []).map((r) => [r.id, r.key] as const), ...(result.bundles ?? []).map((b) => [b.id, b.key] as const)]);
+  const shared = graph.segments.filter((s) => s.count > 1);
+  const ids = new Set(shared.map((s) => s.id));
+  const place = new Map<string, { seq: number; reverse: boolean }>();
+  for (const path of graph.paths) {
+    let seq = 0;
+    for (const ref of path.segments) if (ids.has(ref.segment)) place.set(`${ref.segment}\u0000${path.edge}`, { seq: seq++, reverse: ref.reverse });
+  }
+  const highways: Highway[] = [];
+  for (const s of shared) {
+    const last = s.points.length - 1;
+    const members: HighwayMember[] = [];
+    for (const edge of s.edges) {
+      const at = place.get(`${s.id}\u0000${edge}`);
+      if (at) members.push(at.reverse ? memberAt(s.points, edge, last, 0, at.seq) : memberAt(s.points, edge, 0, last, at.seq));
+    }
+    if (members.length < 2) continue;
+    highways.push({ id: `h${highways.length}`, key: keys.get(s.id) ?? s.id, spine: s.points, lanes: members.map((m) => m.edge), members });
+  }
+  return { highways };
+}

package/src/highways/router.ts

@@ -0,0 +1,40 @@
+import type { Graph, Result, Router } from "../model.ts";
+import { defineStrategy, type Strategy } from "../strategies/model.ts";
+import type { WayOptions } from "../ways.ts";
+import { follow, type FollowOptions } from "./follow.ts";
+
+/** This function gives the options of the way finder in the options of a strategy: `margin` and `k`, when they are present. */
+function wayOptionsOf(options: object): WayOptions {
+  const o = options as { margin?: unknown; k?: unknown };
+  return { ...(typeof o.margin === "number" ? { margin: o.margin } : {}), ...(typeof o.k === "number" ? { k: o.k } : {}) };
+}
+
+/**
+ * This function gives a router that runs a highway strategy and then `follow`. The strategy gets the graph without first routes.
+ * The way finder of `follow` takes `margin` and `k` from the options of the strategy, and then from `followOptions`.
+ * The router keeps the name and the `maxNodes` of the strategy.
+ */
+export function highwayRouter<O extends object>(strategy: Strategy<"highway", O>, options?: Partial<O>, followOptions: FollowOptions = {}): Router {
+  return {
+    name: strategy.name,
+    ...(strategy.maxNodes === undefined ? {} : { maxNodes: strategy.maxNodes }),
+    route: (graph: Graph): Result => follow(graph, strategy.run({ graph }, options), { ...followOptions, ...wayOptionsOf({ ...strategy.defaults, ...options }) }),
+  };
+}
+
+/**
+ * This function gives a router strategy that runs a highway strategy and then `follow`.
+ * The router strategy has the name, the options and the schema of the highway strategy.
+ * The benchmark and the screen race such a router with the other routers.
+ */
+export function highwayRouterStrategy<O extends object>(strategy: Strategy<"highway", O>): Strategy<"router", O> {
+  return defineStrategy<"router", O>({
+    step: "router",
+    name: strategy.name,
+    describe: strategy.describe,
+    defaults: strategy.defaults as O,
+    ...(strategy.schema === undefined ? {} : { schema: strategy.schema }),
+    ...(strategy.maxNodes === undefined ? {} : { maxNodes: strategy.maxNodes }),
+    run: (graph: Graph, options: Readonly<O>): Result => follow(graph, strategy.run({ graph }, options), wayOptionsOf(options)),
+  });
+}

package/src/highways/shared-ways/index.ts

@@ -0,0 +1,15 @@
+import { sharedRouter, type SharedOptions } from "../../routers/shared.ts";
+import { planOfResult } from "../result.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+
+/** The options of the highway strategy `shared-ways`: the options of the router `shared`, without the name and the limit of the benchmark. */
+export type SharedWaysOptions = Omit<SharedOptions, "name" | "maxNodes">;
+
+/**
+ * This function gives the highways that the router `shared` decides. The edges of one key go one by one through the corner graph.
+ * A link that the key uses already costs less, so the ways of a key come together. Each stretch that two edges or more share becomes one highway.
+ * The function does not change the router: it reads its runs.
+ */
+export function sharedWaysPlan(input: HighwayInput, options: SharedWaysOptions): HighwayPlan {
+  return planOfResult(sharedRouter({ ...options, name: "shared-ways" }).route(input.graph));
+}

package/src/index.ts

@@ -27,3 +27,7 @@ export * from "./bench/measures/index.ts";
 export * from "./bench/suite.ts";
 export * from "./strategies/index.ts";
 export * from "./bench/compare.ts";
+export * from "./bench/screen/index.ts";
+export * from "./highways/index.ts";
+export * from "./order/index.ts";
+export * from "./repair/index.ts";

package/src/order/index.ts

@@ -0,0 +1,65 @@
+import { fnv1a32 } from "../bench/screen/hash.ts";
+import { rng } from "../fixtures.ts";
+import type { Edge, Graph, Result, Router } from "../model.ts";
+import { defineStrategy, type Strategy } from "../strategies/model.ts";
+
+/** This function compares two edges by the hash of their ids, and then by their ids. Thus the order of two edges does not depend on the input. */
+function byHash(a: { readonly h: number; readonly e: Edge }, b: { readonly h: number; readonly e: Edge }): number {
+  if (a.h !== b.h) return a.h - b.h;
+  return a.e.id < b.e.id ? -1 : a.e.id > b.e.id ? 1 : 0;
+}
+
+/**
+ * This function gives the graph with its edges in the stable order of WILD-053: by the FNV-1a hash of the id, then by the id.
+ * The nodes and the edges do not change. Two orders of the same edges give the same graph.
+ * The hash spreads the edges, so the stable order does not favor the edges of one node or one collection.
+ */
+export function stableOrder(graph: Graph): Graph {
+  const edges = graph.edges.map((e) => ({ h: fnv1a32(e.id), e })).sort(byHash).map((x) => x.e);
+  return { ...graph, edges };
+}
+
+/** This function gives the graph with its edges in a random order of the seed. The same graph and seed always give the same order. */
+export function shuffleEdges(graph: Graph, seed: number): Graph {
+  const edges = [...graph.edges];
+  const r = rng(seed);
+  for (let i = edges.length - 1; i > 0; i--) {
+    const j = Math.floor(r() * (i + 1));
+    [edges[i], edges[j]] = [edges[j]!, edges[i]!];
+  }
+  return { ...graph, edges };
+}
+
+/**
+ * This function routes the graph in the stable order of `stableOrder`, with the function `route`.
+ * The routes come back in the order of the input edges, so the caller sees no change of order.
+ * The bundles, the runs and the levels come from the stable order. Thus each order of the input gives the same data.
+ */
+export function routeInStableOrder(graph: Graph, route: (graph: Graph) => Result): Result {
+  const result = route(stableOrder(graph));
+  const index = new Map(graph.edges.map((e, i) => [e.id, i] as const));
+  const at = (edge: string): number => index.get(edge) ?? Number.MAX_SAFE_INTEGER;
+  const routes = [...result.routes].sort((a, b) => at(a.edge) - at(b.edge));
+  return { ...result, routes };
+}
+
+/** This function gives a router that routes each graph in the stable order of WILD-053. It keeps the name and the `maxNodes` of the router. */
+export function withStableOrder(router: Router): Router {
+  return { ...router, route: (graph: Graph): Result => routeInStableOrder(graph, (g) => router.route(g)) };
+}
+
+/**
+ * This function gives a router strategy that runs `strategy` in the stable order of WILD-053. The output does not depend on the order of the input edges.
+ * The new strategy has the name `<name>+stable`, and the options and the schema of `strategy`. The strategy `strategy` does not change.
+ */
+export function stableOrderStrategy<O extends object>(strategy: Strategy<"router", O>): Strategy<"router", O> {
+  return defineStrategy<"router", O>({
+    step: "router",
+    name: `${strategy.name}+stable`,
+    describe: `${strategy.describe} The edges go in a stable order: by a hash of their ids.`,
+    defaults: { ...strategy.defaults } as O,
+    ...(strategy.schema === undefined ? {} : { schema: strategy.schema }),
+    ...(strategy.maxNodes === undefined ? {} : { maxNodes: strategy.maxNodes }),
+    run: (graph: Graph, options: Readonly<O>): Result => routeInStableOrder(graph, (g) => strategy.run(g, options)),
+  });
+}

package/src/plugs/justify.ts

@@ -0,0 +1,48 @@
+/**
+ * Plug justification (WILD-002, with NAT-031): the plugs of one side keep their order and a minimum gap.
+ * They move the least distance from their ideal places.
+ */
+
+/**
+ * This function places `ideal.length` points on the segment from `lo` to `hi` of one side.
+ * The points keep the order of their ideal places. Two neighbours are at least `gap` apart, or the side divided evenly when it is too short.
+ * The sum of the squares of the moves is the least. The answer is exact: a fit by pool adjacent violators.
+ *
+ * The function `tie` orders two points with the same ideal place. The result is in the order of `ideal`.
+ */
+export function justifyPlugs(ideal: readonly number[], lo: number, hi: number, gap: number, tie?: (i: number) => number): number[] {
+  const k = ideal.length;
+  if (k === 0) return [];
+  const order = ideal.map((_, i) => i).sort((a, b) => ideal[a]! - ideal[b]! || (tie ? tie(a) - tie(b) : 0) || a - b);
+  const s = k > 1 ? Math.max(0, Math.min(gap, (hi - lo) / (k - 1))) : 0;
+  // With y_i = x_i - i·s, the gap becomes the rule y_i <= y_(i+1): an isotonic fit of a_i - i·s.
+  const y = isotonic(order.map((j, i) => ideal[j]! - i * s));
+  const top = Math.max(lo, hi - (k - 1) * s);
+  const out = new Array<number>(k);
+  order.forEach((j, i) => {
+    out[j] = Math.max(lo, Math.min(top, y[i]!)) + i * s;
+  });
+  return out;
+}
+
+/** This function gives the non-decreasing sequence nearest to `v` in the sum of squares (pool adjacent violators). */
+export function isotonic(v: readonly number[]): number[] {
+  const mean: number[] = [];
+  const size: number[] = [];
+  for (const x of v) {
+    mean.push(x);
+    size.push(1);
+    while (mean.length > 1 && mean[mean.length - 2]! > mean[mean.length - 1]!) {
+      const m = mean.pop()!;
+      const n = size.pop()!;
+      const i = mean.length - 1;
+      mean[i] = (mean[i]! * size[i]! + m * n) / (size[i]! + n);
+      size[i]! += n;
+    }
+  }
+  const out: number[] = [];
+  mean.forEach((m, i) => {
+    for (let j = 0; j < size[i]!; j++) out.push(m);
+  });
+  return out;
+}

package/src/plugs/side.ts

@@ -0,0 +1,138 @@
+/**
+ * Free plugs on a side (WILD-001): the search of a route starts from the whole free side, not from one point of it.
+ * Thus the first leg goes straight out to the first corner of the way, and the plug is the foot of that leg.
+ */
+import { center, dist, type Box, type Point } from "../geom.ts";
+import { fixedPortPoint, type End, type Node, type Side } from "../model.ts";
+import { placePlug, pointOnSide, SIDE_NORMAL, sideToward, type Plug } from "../plugs.ts";
+import type { Terminal } from "../visibility.ts";
+import type { WayFinder } from "../ways.ts";
+
+/** The options of `sidePlugs`. */
+export interface SidePlugOptions {
+  /** The cost of a slant first leg: the length of the leg grows by `bend` × its angle to the normal, in radians. The default is 1. */
+  readonly bend?: number;
+  /** The distance from a plug to a corner of its box. The default is 6, as in `pointOnSide`. */
+  readonly inset?: number;
+  /** The largest number of places that the search tries on each side. The default is 16. */
+  readonly most?: number;
+}
+
+/** A free side of one end: its node, its side and its range on the axis along the side. It also has the plug that faces the other end. */
+interface FreeSide {
+  readonly node: Node;
+  readonly side: Side;
+  readonly normal: Point;
+  /** The axis along the side. */
+  readonly along: "x" | "y";
+  /** The place of the side on the other axis. */
+  readonly at: number;
+  readonly lo: number;
+  readonly hi: number;
+  readonly facing: Plug;
+}
+
+/** A place that the search tries: the plug, and the free point where the search starts from it, with its cost. */
+interface Start extends Terminal {
+  readonly plug: Plug;
+}
+
+/** This function gives the free side of an end, or `undefined` when the plug of the end is fixed. */
+function freeSide(node: Node, end: End, toward: Point, inset: number): FreeSide | undefined {
+  if (fixedPortPoint(node, end)) return undefined;
+  const port = end.port === undefined ? undefined : node.ports?.find((p) => p.id === end.port);
+  const side = port?.side ?? sideToward(node.box, toward);
+  const b: Box = node.box;
+  const along = side === "east" || side === "west" ? "y" : "x";
+  const start = along === "y" ? b.y : b.x;
+  const len = along === "y" ? b.h : b.w;
+  const m = Math.min(inset, len / 4);
+  const at = side === "east" ? b.x + b.w : side === "west" ? b.x : side === "south" ? b.y + b.h : b.y;
+  const point = pointOnSide(b, side, toward, inset);
+  return { node, side, normal: SIDE_NORMAL[side], along, at, lo: start + m, hi: start + len - m, facing: { point, normal: SIDE_NORMAL[side] } };
+}
+
+/** This function gives the point of the side at `v` on the axis along the side. */
+function footAt(f: FreeSide, v: number): Point {
+  return f.along === "y" ? { x: f.at, y: v } : { x: v, y: f.at };
+}
+
+/**
+ * This function gives the places that the search tries on one free side. A place is the out point of a plug on the side.
+ * A place is also a corner in front of the side. The plug of a corner is the foot of the leg to it.
+ */
+function startsOf(ways: WayFinder, f: FreeSide, others: readonly number[], bend: number, most: number): Start[] {
+  const margin = ways.margin;
+  const pad = margin / 2;
+  const own = new Set<Node>([f.node]);
+  const starts: Start[] = [];
+  const out = (p: Point): Point => ({ x: p.x + f.normal.x * margin, y: p.y + f.normal.y * margin });
+  const plugAt = (v: number): Plug => ({ point: footAt(f, v), normal: f.normal });
+  // The plug that faces the other end is always a place of the search, so the search is never worse than the default.
+  starts.push({ plug: f.facing, point: out(f.facing.point), cost: margin });
+  const mid = (f.lo + f.hi) / 2;
+  for (const v of [f.lo, mid, f.hi, ...others]) {
+    if (v < f.lo - 1e-9 || v > f.hi + 1e-9) continue;
+    const p = out(footAt(f, v));
+    if (!ways.obstacles.inside(p, 0, f.node)) starts.push({ plug: plugAt(v), point: p, cost: margin });
+  }
+  // The corners in front of the side that its out points see.
+  const seen = new Set<number>();
+  for (const v of [f.lo, mid, f.hi, f.facing.point[f.along]]) for (const c of ways.corners.nearestVisible(out(footAt(f, v)), 16)) seen.add(c);
+  for (const c of seen) {
+    const q = ways.corners.points[c]!;
+    const across = f.along === "y" ? "x" : "y";
+    const depth = (q[across] - f.at) * f.normal[across];
+    if (depth < margin - 1e-9) continue;
+    const v = Math.max(f.lo, Math.min(f.hi, q[f.along]));
+    const foot = footAt(f, v);
+    const angle = Math.atan2(Math.abs(q[f.along] - v), depth);
+    if (angle > Math.PI / 4 + 1e-9) continue;
+    if (!ways.obstacles.clear(foot, q, pad, own)) continue;
+    starts.push({ plug: plugAt(v), point: q, cost: dist(foot, q) * (1 + bend * angle) });
+  }
+  // One place for each foot: the cheapest. The places nearest to the facing plug come first.
+  const best = new Map<number, Start>();
+  for (const s of starts) {
+    const key = Math.round(s.plug.point[f.along] * 2);
+    const old = best.get(key);
+    if (!old || s.cost < old.cost) best.set(key, s);
+  }
+  const facing = f.facing.point[f.along];
+  const list = [...best.values()].sort((a, b) => Math.abs(a.plug.point[f.along] - facing) - Math.abs(b.plug.point[f.along] - facing));
+  return list.slice(0, Math.max(1, most));
+}
+
+/**
+ * This function places the two plugs of an edge with a free side. A fixed plug stays at its point.
+ * The search (A*) starts from each place of the free side of the source. It ends at each place of the free side of the target.
+ * The plugs are the places of the shortest way. Without a way, the plugs face the other end, as `placePlug` places them.
+ */
+export function sidePlugs(ways: WayFinder, s: Node, es: End, t: Node, et: End, options: SidePlugOptions = {}): [Plug, Plug] {
+  const inset = options.inset ?? 6;
+  const ps = placePlug(s, es, center(t.box));
+  const pt = placePlug(t, et, center(s.box));
+  if (s === t) return [ps, pt];
+  const fs = freeSide(s, es, center(t.box), inset);
+  const ft = freeSide(t, et, center(s.box), inset);
+  if (!fs && !ft) return [ps, pt];
+  const bend = options.bend ?? 1;
+  const most = options.most ?? 16;
+  const fixed = (p: Plug): Start[] => [{ plug: p, point: ways.out(p), cost: ways.margin }];
+  // Two sides that face each other on one axis share the places of a straight line.
+  const facingPair = fs && ft && fs.along === ft.along && fs.normal.x === -ft.normal.x && fs.normal.y === -ft.normal.y;
+  const shared = (a: FreeSide | undefined, b: FreeSide | undefined, p: Plug): number[] => {
+    if (!a) return [];
+    if (facingPair && b) {
+      const lo = Math.max(a.lo, b.lo);
+      const hi = Math.min(a.hi, b.hi);
+      return lo <= hi ? [lo, (lo + hi) / 2, hi] : [];
+    }
+    return [p.point[a.along]];
+  };
+  const from = fs ? startsOf(ways, fs, shared(fs, ft, pt), bend, most) : fixed(ps);
+  const to = ft ? startsOf(ways, ft, shared(ft, fs, ps), bend, most) : fixed(pt);
+  const way = ways.corners.pathAmong(from, to);
+  if (!way) return [ps, pt];
+  return [from[way.from]!.plug, to[way.to]!.plug];
+}