@mark1russell7/highways 0.9.1 → 0.9.2

package/src/bench/screen/screen.ts

@@ -1,17 +1,20 @@
-import type { Graph, Result, Route } from "../../model.ts";
+import type { Graph, Level, Result, Route } from "../../model.ts";
 import { stableOrderStrategy } from "../../order/index.ts";
 import { repairStrategy } from "../../repair/index.ts";
 import { STRATEGIES } from "../../strategies/builtins.ts";
 import { asRouter, createRegistry, getStrategy, listStrategies, register, STEPS, type AnyStrategy, type Registry, type Strategy } from "../../strategies/model.ts";
-import { compareStep, highwayRouters, isRoutedStep, stepRouters, type CompareRow, type CompareStep, type RoutedStep, type StepComparison } from "../compare.ts";
+import { compareStep, highwayRouters, isRoutedStep, stepRouters, wholeBoard, type CompareRow, type CompareStep, type RoutedStep, type StepComparison } from "../compare.ts";
 import { bundledShare, bundleStretch, mergeAngle } from "../measures/bundles.ts";
 import { highwayEdits } from "../measures/highways.ts";
 import { laneArea, laneCrossings, laneFidelity, lanesThrough, occupiedArea, openLanes, orthogonality, routeSeparation, runProfile } from "../measures/lanes.ts";
-import { linkAgreement } from "../measures/levels.ts";
+import { farLevel, groupFill, itemOverlaps, silhouette } from "../measures/groups.ts";
+import { levelRatio, linkAgreement } from "../measures/levels.ts";
 import { orderFragility } from "../measures/order.ts";
 import { paretoFront, type Objective } from "../measures/pareto.ts";
 import { boardUnit } from "../measures/routes.ts";
+import { boxDisplacement, distanceDistortion, roomOrderFaults } from "../measures/room.ts";
 import { routeStability } from "../measures/stability.ts";
+import { routeSymmetry } from "../measures/symmetry.ts";
 import { quantile } from "../measures/stats.ts";
 import { checkLevels, checkProperties, TOLERANCE } from "../properties.ts";
 import { measureQuality } from "../quality.ts";
@@ -227,11 +230,30 @@ function screenRegistry(step: ScreenStep, strategies: readonly (Strategy<ScreenS
 /** This function tells if a step of the screen gives routes. The step `router` gives routes, and each step of `RoutedStep` gives routes as a router. */
 const givesRoutes = (step: ScreenStep): step is "router" | RoutedStep => step === "router" || isRoutedStep(step);
 
+/** This function gives the measures of the shape of the groups and of the levels: G4, G5, G7 and Z5. A value without its data is not in the result. */
+function groupShapeValues(graph: Graph, levels: readonly Level[]): Record<string, number> {
+  const values: Record<string, number> = {};
+  if (levels.length === 0) return values;
+  values["G5.overlaps"] = itemOverlaps(levels);
+  const far = farLevel(levels);
+  const fill = far && groupFill(graph, far);
+  if (fill !== undefined) values["G4.fill"] = fill;
+  const sil = far && silhouette(graph, far);
+  if (sil !== undefined) values["G7.silhouette"] = sil;
+  const ratio = levelRatio(levels);
+  if (ratio) {
+    values["Z5.max"] = ratio.max;
+    values["Z5.spread"] = ratio.spread;
+  }
+  return values;
+}
+
 /**
  * This function gives the values of a row of `compareStep`, with the measures of `measureQuality` for a router.
  * A router also gets the bundled share (B2), the merge angle (B6) and the bundle stretch (B3) against the routes `base` of `corners`.
  * It also gets the measures of MEAS3A: R12, R14, B5, B7, B8, B9, M1 and M4. The lane measures open each shared segment at `MEASURE_LANE_WIDTH`.
- * A result with zoom levels also gets the link agreement (Z9), for a router and for a grouping rule.
+ * A result with zoom levels also gets the link agreement (Z9) and `groupShapeValues`, for a router and for a grouping rule.
+ * A router also gets the symmetry of its routes (H3). A whole strategy also gets M2, M3 and M5 of the board of its output.
  */
 function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () => readonly Route[]): Record<string, number> {
   const values: Record<string, number> = { ...row.values };
@@ -265,10 +287,21 @@ function rowValues(step: ScreenStep, graph: Graph, row: CompareRow, base: () =>
     }
     values["M1.area"] = laneArea(graph, open);
     values["M4.laneThrough"] = lanesThrough(graph, open);
+    const h3 = routeSymmetry(graph, routes);
+    if (h3 !== undefined) values["H3.share"] = h3;
   }
   if ((givesRoutes(step) || step === "group") && row.result?.levels) {
-    const la = linkAgreement(graph, row.result.levels, row.result.routes, boardUnit(graph));
+    const levels = row.result.levels;
+    const la = linkAgreement(graph, levels, row.result.routes, boardUnit(graph));
     if (la !== undefined) values["Z9.mean"] = la;
+    Object.assign(values, groupShapeValues(graph, levels));
+  }
+  // The step `whole` can move the boxes with a room strategy. M2, M3 and M5 compare the board of the output with the input board.
+  if (step === "whole" && row.result) {
+    const board = wholeBoard(row.result) ?? graph;
+    values["M2.order"] = roomOrderFaults(graph.nodes, board.nodes);
+    values["M3.displacement"] = boxDisplacement(graph.nodes, board.nodes, boardUnit(graph));
+    values["M5.stress"] = distanceDistortion(graph.nodes, board.nodes);
   }
   return values;
 }
@@ -426,6 +459,8 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
       const values = rowValues(step, graph, row, cornersBase);
       // Z2 is the count of the hard rule `link-ends`, as a measure. The steps `router`, `highway` and `group` check the rule.
       if (hard["link-ends"] !== undefined) values["Z2.linkEnds"] = hard["link-ends"];
+      // Z1 is the count of the hard rule `counts-sum`, as a measure, the same way.
+      if (hard["counts-sum"] !== undefined) values["Z1.countsSum"] = hard["counts-sum"];
       if (optima && withOptima.has(input.id) && row.result) Object.assign(values, gapValues(input, graph, row.result, cornersBase(), gapBase(), optima));
       if (shuffles > 0 && row.result) {
         const router = asRouter(strategy as Strategy<"router">, own[row.strategy]);

package/src/bench/suite.ts

@@ -15,7 +15,7 @@ import { asRouter, listStrategies, STEPS, type LaneBoard, type Registry, type St
 import { measureLevelFaults, sumFaults } from "./links.ts";
 import { checkLevels } from "./properties.ts";
 import { ambiguity, inkSaved } from "./measures/bundles.ts";
-import { bendingEnergy, curveFaults, g1Defect, g2Defect } from "./measures/curves.ts";
+import { bendingEnergy, curvatureVariation, curveDeviation, curveFaults, g1Defect, g2Defect } from "./measures/curves.ts";
 import { balance, cutShare, farLevel, groupStability, levelGrouping, modularity, treeCost } from "./measures/groups.ts";
 import { nestingFaults, orderStability, positionStability } from "./measures/levels.ts";
 import { paretoFront, type Objective } from "./measures/pareto.ts";
@@ -328,7 +328,7 @@ export interface CurveRun {
   readonly edges: readonly string[];
 }
 
-/** This function draws the routes of a result with each curve strategy and measures the curves (C1, C2, C3, C6 and the curve rules). */
+/** This function draws the routes of a result with each curve strategy and measures the curves (C1, C2, C3, C4, C6, C8 and the curve rules). */
 export function curveRuns(graph: Graph, result: Result, curves: readonly Strategy<"curve">[], options: CurveRunOptions): CurveRun[] {
   const byId = nodeIndex(graph);
   const edges = new Map(graph.edges.map((e) => [e.id, e]));
@@ -363,6 +363,8 @@ export function curveRuns(graph: Graph, result: Result, curves: readonly Strateg
     const g1: number[] = [];
     const g2: number[] = [];
     const energy: number[] = [];
+    const variation: number[] = [];
+    const deviation: number[] = [];
     const rules = { "curve-clear": 0, "curve-ends": 0, "curve-g1": 0, "curve-simple": 0 };
     let length = 0;
     drawn.forEach((segments, i) => {
@@ -371,6 +373,8 @@ export function curveRuns(graph: Graph, result: Result, curves: readonly Strateg
       g1.push(g1Defect(segments));
       g2.push(g2Defect(segments, u));
       energy.push(bendingEnergy(s, 0.25));
+      variation.push(curvatureVariation(s, 0.25));
+      deviation.push(curveDeviation(s, r.points, u / 4) / u);
       length += polylineLength(s);
       const normals = options.normals.has(curve.name);
       const f = curveFaults({
@@ -394,6 +398,10 @@ export function curveRuns(graph: Graph, result: Result, curves: readonly Strateg
       "C2.max": g2.reduce((m, x) => Math.max(m, x), 0),
       "C3.median": quantile(energy, 0.5) || 0,
       "C3.q95": quantile(energy, 0.95) || 0,
+      "C4.median": quantile(variation, 0.5) || 0,
+      "C4.q95": quantile(variation, 0.95) || 0,
+      "C8.median": quantile(deviation, 0.5) || 0,
+      "C8.max": deviation.reduce((m, x) => Math.max(m, x), 0),
       "C6.length": ink > 0 ? length / ink : 1,
       ...rules,
     };

package/src/highways/follow.ts

@@ -1,5 +1,5 @@
 import { center, dist, pointBoxDistance, type Point } from "../geom.ts";
-import { fixedPortPoint, nodeIndex, resolvePorts, type End, type Graph, type Node, type Result, type Route, type SharedRun } from "../model.ts";
+import { fixedPortPoint, nodeIndex, outerGraph, 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";
@@ -69,7 +69,7 @@ function slice(stops: Stops, on: number, off: number): Point[] {
  * The same graph, plan and options give the same result.
  */
 export function follow(input: Graph, plan: HighwayPlan, options: FollowOptions = {}): Result {
-  const graph = resolvePorts(input);
+  const graph = outerGraph(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/model.ts

@@ -30,6 +30,12 @@ export interface Node {
   readonly ports?: readonly Port[];
   /** This data is free for the grouping rules of the nodes. The rule `keys` reads the string `data.group` by default. */
   readonly data?: Readonly<Record<string, unknown>>;
+  /**
+   * This id names the frame node that holds the node. A frame is a node that another node names as its parent.
+   * An edge from a plug of a frame to a node in the frame is an inner edge (`splitFrames`). The router `corners` routes it inside the frame.
+   * A parent that names no node, or a cycle of parents, makes each router throw a `RangeError`.
+   */
+  readonly parent?: string;
 }
 
 /** One end of an edge: a node, and optionally one plug of that node. */
@@ -56,6 +62,8 @@ export interface Graph {
 export interface Route {
   readonly edge: string;
   readonly points: readonly Point[];
+  /** This id names the frame of an inner route: the route stays inside the box of that node. An outer route has no frame. */
+  readonly frame?: string;
 }
 
 /**
@@ -194,3 +202,62 @@ export function fixedPortPoint(node: Node, end: End): Point | undefined {
   if (at === undefined) return undefined;
   return { x: node.box.x + at.x, y: node.box.y + at.y };
 }
+
+/**
+ * An inner edge: an edge from a plug of a frame to a node in that frame, at any depth.
+ * `plug` tells which end of the edge is the plug of the frame.
+ */
+export interface InnerEdge {
+  readonly edge: Edge;
+  readonly frame: string;
+  readonly plug: "source" | "target";
+}
+
+/** This function throws a `RangeError` when the parent of a node names no node, or when the parents of a node make a cycle. */
+export function checkParents(graph: Graph, byId: ReadonlyMap<string, Node> = nodeIndex(graph)): void {
+  const done = new Set<string>();
+  for (const n of graph.nodes) {
+    const seen = new Set<string>();
+    for (let m: Node | undefined = n; m?.parent !== undefined && !done.has(m.id); ) {
+      seen.add(m.id);
+      const p = byId.get(m.parent);
+      if (!p) throw new RangeError(`The parent "${m.parent}" of the node "${m.id}" names no node of the graph.`);
+      if (seen.has(p.id)) throw new RangeError(`The parents of the node "${n.id}" make a cycle through the node "${p.id}".`);
+      m = p;
+    }
+    for (const id of seen) done.add(id);
+  }
+}
+
+/** This function tells if the node `frame` holds the node `id`, at any depth. A node does not hold itself. */
+function holds(byId: ReadonlyMap<string, Node>, frame: string, id: string): boolean {
+  for (let p = byId.get(id)?.parent; p !== undefined; p = byId.get(p)?.parent) if (p === frame) return true;
+  return false;
+}
+
+/**
+ * This function checks the parents of a graph (`checkParents`), and takes its inner edges out.
+ * An inner edge of the frame F has a plug of F (`End.port`) at one end. F holds the node at the other end.
+ * The graph that it gives keeps each node and the other edges. A graph without `parent` comes back as the same object, with no inner edge.
+ */
+export function splitFrames(graph: Graph): { readonly graph: Graph; readonly inner: readonly InnerEdge[] } {
+  if (!graph.nodes.some((n) => n.parent !== undefined)) return { graph, inner: [] };
+  const byId = nodeIndex(graph);
+  checkParents(graph, byId);
+  const inner: InnerEdge[] = [];
+  const edges = graph.edges.filter((e) => {
+    if (e.source.port !== undefined && holds(byId, e.source.node, e.target.node)) inner.push({ edge: e, frame: e.source.node, plug: "source" });
+    else if (e.target.port !== undefined && holds(byId, e.target.node, e.source.node)) inner.push({ edge: e, frame: e.target.node, plug: "target" });
+    else return true;
+    return false;
+  });
+  return { graph: inner.length === 0 ? graph : { ...graph, edges }, inner };
+}
+
+/**
+ * This function gives the graph of a router without frames. It has the plugs of `resolvePorts`, and no inner edges (`splitFrames`).
+ * Each router except `corners` uses it at the start of `route`. So an inner edge gets no route from such a router.
+ */
+export function outerGraph(graph: Graph): Graph {
+  return splitFrames(resolvePorts(graph)).graph;
+}

package/src/routers/corners.ts

@@ -1,16 +1,17 @@
 import { center, type Point } from "../geom.ts";
-import { nodeIndex, fixedPortPoint, resolvePorts, type Edge, type Graph, type Node, type Result, type Route, type Router } from "../model.ts";
+import { nodeIndex, fixedPortPoint, resolvePorts, splitFrames, type Edge, type Graph, type Node, type Result, type Route, type Router } from "../model.ts";
 import { placePlug, type Plug } from "../plugs.ts";
 import { justifyPlugs } from "../plugs/justify.ts";
 import { sidePlugs } from "../plugs/side.ts";
 import type { PlugPair, Strategy } from "../strategies/model.ts";
-import { WayFinder, type WayOptions } from "../ways.ts";
+import { WayFinder } from "../ways.ts";
+import { frameRoutes, type FrameOptions } from "./frames.ts";
 
 /** The ways to place a free plug of the corner router. */
 export type PlugPlace = "facing" | "side";
 
 /** The options of the corner router. */
-export interface CornersOptions extends WayOptions {
+export interface CornersOptions extends FrameOptions {
   /** The name in the benchmark. */
   readonly name: string;
   /** The benchmark skips a fixture with more nodes. */
@@ -38,15 +39,21 @@ export interface CornersOptions extends WayOptions {
  * This function makes a router that goes around the nodes.
  * Each edge leaves its plug along the normal of the side. It goes a shortest way (A*) through a sparse visibility graph
  * of the box corners, without the needless corners. It enters the target plug along its normal.
+ * An inner edge (`splitFrames`) gets an inner route in the bounds of its frame (`frameRoutes`), after the outer routes.
  */
 export function cornersRouter(options: CornersOptions): Router {
   const router: Router = {
     name: options.name,
     route(input: Graph): Result {
-      const graph = resolvePorts(input);
+      const { graph, inner } = splitFrames(resolvePorts(input));
       const byId = nodeIndex(graph);
       const ways = new WayFinder(graph.nodes, options);
       const routes: Route[] = [];
+      // The inner routes come after the outer routes.
+      const done = (): Result => {
+        if (inner.length > 0) routes.push(...frameRoutes(graph, inner, options));
+        return { routes };
+      };
       if (!options.plug && (options.plugs ?? "facing") === "facing" && !((options.plugGap ?? 0) > 0)) {
         for (const e of graph.edges) {
           const s = byId.get(e.source.node);
@@ -56,7 +63,7 @@ export function cornersRouter(options: CornersOptions): Router {
           const pt = placePlug(t, e.target, center(s.box));
           routes.push({ edge: e.id, points: ways.between(ps, pt, new Set<Node>([s, t])) });
         }
-        return { routes };
+        return done();
       }
       // First the plugs of each edge, then the gaps of the plugs of each side, then the ways between the plugs.
       const ends: [Edge, Node, Node, Plug, Plug][] = [];
@@ -75,7 +82,7 @@ export function cornersRouter(options: CornersOptions): Router {
       }
       if ((options.plugGap ?? 0) > 0) spacePlugs(ends, options.plugGap!);
       for (const [e, s, t, ps, pt] of ends) routes.push({ edge: e.id, points: ways.between(ps, pt, new Set<Node>([s, t])) });
-      return { routes };
+      return done();
     },
   };
   return options.maxNodes === undefined ? router : { ...router, maxNodes: options.maxNodes };

package/src/routers/frames.ts

@@ -0,0 +1,136 @@
+import { center, dist, type Box, type Point } from "../geom.ts";
+import { nodeIndex, type Graph, type InnerEdge, type Node, type Route } from "../model.ts";
+import { placePlug, type Plug } from "../plugs.ts";
+import { WayFinder, type WayOptions } from "../ways.ts";
+
+/**
+ * The rule for a node box that is not fully inside the box of its frame.
+ * With `throw`, the router throws a `RangeError`. With `skip`, the node is not an obstacle, and its inner edges get no route.
+ * With `clamp`, the router cuts the box to the bounds of the frame.
+ */
+export type Outside = "throw" | "skip" | "clamp";
+
+/** The options of the inner routes: the options of the way finder, the rule `outside` and the inset `frameInset`. */
+export interface FrameOptions extends WayOptions {
+  /** The rule for a node box outside the box of its frame. The default is `throw`. */
+  readonly outside?: Outside;
+  /** The distance from the walls of a frame to the bounds of its inner routes. The default is the margin of the router. */
+  readonly frameInset?: number;
+}
+
+/** The inside of one frame for the inner edges to one depth: the bounds, the way finder and the obstacles by id. */
+interface Room {
+  readonly ways: WayFinder;
+  readonly nodes: ReadonlyMap<string, Node>;
+}
+
+/** The tiny gap between the bounds and the band of a wall, so that a way along the bounds stays clear of the wall. */
+const EPS = 1e-6;
+
+/**
+ * This function gives the inner routes of the inner edges (`splitFrames`). Each route stays in the bounds of its frame:
+ * the box of the frame, smaller by `frameInset`. It goes around the other nodes of the frame.
+ * It leaves the plug of the frame into the frame, along the normal of the wall. Each route has the id of its frame in `frame`.
+ */
+export function frameRoutes(graph: Graph, inner: readonly InnerEdge[], options: FrameOptions): Route[] {
+  const byId = nodeIndex(graph);
+  const children = new Map<string, Node[]>();
+  for (const n of graph.nodes) {
+    if (n.parent === undefined) continue;
+    const list = children.get(n.parent);
+    if (list) list.push(n);
+    else children.set(n.parent, [n]);
+  }
+  const margin = options.margin ?? 5;
+  const inset = options.frameInset ?? margin;
+  const rooms = new Map<string, Room>();
+  const routes: Route[] = [];
+  for (const { edge, frame, plug } of inner) {
+    const f = byId.get(frame)!;
+    const [own, far] = plug === "source" ? [edge.source, edge.target] : [edge.target, edge.source];
+    // The nodes between the frame and the far end: each of them holds the far end, so it is not an obstacle.
+    const chain: string[] = [];
+    for (let p = byId.get(far.node)!.parent!; p !== frame; p = byId.get(p)!.parent!) chain.push(p);
+    const key = JSON.stringify([frame, ...chain]);
+    let room = rooms.get(key);
+    if (!room) rooms.set(key, (room = makeRoom(f, chain, children, byId, inset, options)));
+    const end = room.nodes.get(far.node);
+    if (!end) continue;
+    const fp = placePlug(f, own, center(end.box));
+    const inward = { x: -fp.normal.x, y: -fp.normal.y };
+    // The way starts on the bounds, straight in from the plug of the wall.
+    const start: Plug = { point: { x: fp.point.x + inward.x * inset, y: fp.point.y + inward.y * inset }, normal: inward };
+    const ep = placePlug(end, far, fp.point);
+    const ends = new Set<Node>([end]);
+    const points =
+      plug === "source" ? stub(fp.point, room.ways.between(start, ep, ends)) : stub(fp.point, room.ways.between(ep, start, ends).reverse()).reverse();
+    routes.push({ edge: edge.id, points, frame });
+  }
+  return routes;
+}
+
+/** This function puts the plug of the wall before a way that starts on the bounds. A first point on the line of the stub goes. */
+function stub(plug: Point, way: Point[]): Point[] {
+  const [a, b] = way;
+  if (!a || dist(a, plug) === 0) return way;
+  if (b && Math.abs((a.x - plug.x) * (b.y - plug.y) - (a.y - plug.y) * (b.x - plug.x)) < 1e-9 && (a.x - plug.x) * (b.x - a.x) + (a.y - plug.y) * (b.y - a.y) > 0)
+    return [plug, ...way.slice(1)];
+  return [plug, ...way];
+}
+
+/**
+ * This function makes the room of a frame for the far ends below the nodes of `chain` (the nearest first).
+ * The obstacles are the children of the frame and of each node of the chain, except the nodes of the chain.
+ * Four walls close the bounds, so that no way leaves them.
+ */
+function makeRoom(f: Node, chain: readonly string[], children: ReadonlyMap<string, readonly Node[]>, byId: ReadonlyMap<string, Node>, inset: number, options: FrameOptions): Room {
+  const margin = options.margin ?? 5;
+  const bounds = shrink(f.box, inset);
+  const skip = new Set(chain);
+  const nodes = new Map<string, Node>();
+  for (const holder of [f.id, ...chain]) {
+    for (const n of children.get(holder) ?? []) {
+      if (skip.has(n.id)) continue;
+      const box = byId.get(holder)!.box;
+      if (inside(n.box, box)) {
+        nodes.set(n.id, n);
+        continue;
+      }
+      const rule = options.outside ?? "throw";
+      if (rule === "throw")
+        throw new RangeError(`The box of the node "${n.id}" is not inside the box of its frame "${holder}". The option outside can skip or clamp it.`);
+      if (rule === "skip") continue;
+      const cut = cutBox(n.box, bounds);
+      if (cut) nodes.set(n.id, { ...n, box: cut, ...(n.ports ? { ports: n.ports.map((p) => (p.at ? { ...p, at: { x: p.at.x + n.box.x - cut.x, y: p.at.y + n.box.y - cut.y } } : p)) } : {}) });
+    }
+  }
+  // The band of each wall starts half a margin outside the bounds, so that a way keeps in the bounds.
+  const w = shrink(bounds, -(margin / 2 + EPS));
+  const t = 2 * margin + 1;
+  const walls: Node[] = [
+    { x: w.x - t, y: w.y - t, w: w.w + 2 * t, h: t },
+    { x: w.x - t, y: w.y + w.h, w: w.w + 2 * t, h: t },
+    { x: w.x - t, y: w.y, w: t, h: w.h },
+    { x: w.x + w.w, y: w.y, w: t, h: w.h },
+  ].map((box, i) => ({ id: `\u0000wall${i}`, box }));
+  return { ways: new WayFinder([...nodes.values(), ...walls], options), nodes };
+}
+
+/** This function gives the box, smaller by `d` on each side. A negative `d` makes it larger. */
+function shrink(b: Box, d: number): Box {
+  return { x: b.x + d, y: b.y + d, w: Math.max(0, b.w - 2 * d), h: Math.max(0, b.h - 2 * d) };
+}
+
+/** This function tells if the box `a` is inside the box `b`. */
+function inside(a: Box, b: Box): boolean {
+  return a.x >= b.x && a.y >= b.y && a.x + a.w <= b.x + b.w && a.y + a.h <= b.y + b.h;
+}
+
+/** This function gives the part of the box `a` inside the box `b`, or `undefined` when they have no common area. */
+function cutBox(a: Box, b: Box): Box | undefined {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const w = Math.min(a.x + a.w, b.x + b.w) - x;
+  const h = Math.min(a.y + a.h, b.y + b.h) - y;
+  return w > 0 && h > 0 ? { x, y, w, h } : undefined;
+}

package/src/routers/index.ts

@@ -9,6 +9,7 @@ import { byCollection, trunksRouter } from "./trunks.ts";
 export { boxExit, straightRouter } from "./straight.ts";
 export { plugsRouter } from "./plugs.ts";
 export { cornersRouter, type CornersOptions } from "./corners.ts";
+export { frameRoutes, type FrameOptions, type Outside } from "./frames.ts";
 export { sharedRouter, type ShareCost, type SharedNegotiation, type SharedOptions, type ShareMerge, type ShareOrder } from "./shared.ts";
 export { ATTRACTION_DEFAULTS, ATTRACTION_SCHEMA, attractionRouter, attractionStrategy, type AttractionOptions } from "./attraction/index.ts";
 export { sectionsRouter, type SectionsOptions } from "./sections.ts";

package/src/routers/plugs.ts

@@ -1,6 +1,6 @@
 import { inflectionCurve } from "../curves.ts";
 import { center } from "../geom.ts";
-import { nodeIndex, resolvePorts, type Graph, type Result, type Route, type Router } from "../model.ts";
+import { nodeIndex, outerGraph, type Graph, type Result, type Route, type Router } from "../model.ts";
 import { placePlug } from "../plugs.ts";
 
 /**
@@ -10,7 +10,7 @@ import { placePlug } from "../plugs.ts";
 export const plugsRouter: Router = {
   name: "plugs",
   route(input: Graph): Result {
-    const graph = resolvePorts(input);
+    const graph = outerGraph(input);
     const byId = nodeIndex(graph);
     const routes: Route[] = [];
     for (const e of graph.edges) {

package/src/routers/sections.ts

@@ -2,7 +2,7 @@ import { BACKTRACK_MIN, goesOutAndBack } from "../bench/links.ts";
 import { center, dist, pointSegmentDistance, polylineLength, type Point } from "../geom.ts";
 import { LEVEL_LINK_DEFAULTS, type LevelLinkOptions } from "../levels.ts";
 import { depthLevels, type DepthLevelOptions } from "../levels/depths/index.ts";
-import { nodeIndex, resolvePorts, type Graph, type Level, type Node, type Result, type Route, type Router, type SharedRun } from "../model.ts";
+import { nodeIndex, outerGraph, type Graph, type Level, type Node, type Result, type Route, type Router, type SharedRun } from "../model.ts";
 import { placePlug } from "../plugs.ts";
 import { allSections, buildSections, checkSections, SECTION_DEFAULTS, type Section, type SectionOptions } from "../sections.ts";
 import { orderLanes, type RunOrder } from "../segments.ts";
@@ -92,7 +92,7 @@ export function sectionsRouter(options: SectionsOptions): Router {
   const router: Router = {
     name: options.name,
     route(input: Graph): Result {
-      const graph = resolvePorts(input);
+      const graph = outerGraph(input);
       const stretch = options.stretch ?? SECTIONS_DEFAULTS.stretch;
       const stretchPad = options.stretchPad ?? SECTIONS_DEFAULTS.stretchPad;
       const hubSlack = options.hubSlack ?? SECTIONS_DEFAULTS.hubSlack;

package/src/routers/shared.ts

@@ -1,5 +1,5 @@
 import { center, dist, type Point } from "../geom.ts";
-import { nodeIndex, resolvePorts, type Edge, type Graph, type GroupRule, type Result, type Route, type Router, type SharedRun } from "../model.ts";
+import { nodeIndex, outerGraph, type Edge, type Graph, type GroupRule, type Result, type Route, type Router, type SharedRun } from "../model.ts";
 import { channelWidth } from "../channels.ts";
 import { orderRun } from "../lane-order.ts";
 import { stretchLaneOrders, type LaneStretchOrder } from "../lane-orders/stretch/index.ts";
@@ -149,7 +149,7 @@ export function sharedRouter(options: SharedOptions, negotiation?: SharedNegotia
   const router: Router = {
     name: options.name,
     route(input: Graph): Result {
-      const graph = resolvePorts(input);
+      const graph = outerGraph(input);
       const byId = nodeIndex(graph);
       const ways = new WayFinder(graph.nodes, options);
       const corners = ways.corners;

package/src/routers/straight.ts

@@ -1,5 +1,5 @@
 import { center, type Box, type Point } from "../geom.ts";
-import { fixedPortPoint, nodeIndex, resolvePorts, type Graph, type Result, type Route, type Router } from "../model.ts";
+import { fixedPortPoint, nodeIndex, outerGraph, type Graph, type Result, type Route, type Router } from "../model.ts";
 
 /** This function gives the point where the ray from the center of the box to `toward` leaves the box. */
 export function boxExit(box: Box, toward: Point): Point {
@@ -20,7 +20,7 @@ export function boxExit(box: Box, toward: Point): Point {
 export const straightRouter: Router = {
   name: "straight",
   route(input: Graph): Result {
-    const graph = resolvePorts(input);
+    const graph = outerGraph(input);
     const byId = nodeIndex(graph);
     const routes: Route[] = [];
     for (const e of graph.edges) {

package/src/routers/trunks.ts

@@ -1,5 +1,5 @@
 import { center, dist, type Point } from "../geom.ts";
-import { nodeIndex, resolvePorts, type Bundle, type Edge, type Graph, type GroupRule, type Node, type Result, type Route, type Router, type SharedRun } from "../model.ts";
+import { nodeIndex, outerGraph, type Bundle, type Edge, type Graph, type GroupRule, type Node, type Result, type Route, type Router, type SharedRun } from "../model.ts";
 import { placePlug, type Plug } from "../plugs.ts";
 import { orderLanes, type RunOrder } from "../segments.ts";
 import { WayFinder, type WayOptions } from "../ways.ts";
@@ -210,7 +210,7 @@ export function trunksRouter(options: TrunksOptions): Router {
   const router: Router = {
     name: options.name,
     route(input: Graph): Result {
-      const graph = resolvePorts(input);
+      const graph = outerGraph(input);
       const byId = nodeIndex(graph);
       const ways = new WayFinder(graph.nodes, options);
       const points = new Map<string, readonly Point[]>();

package/src/strategies/schemas.ts

@@ -125,6 +125,19 @@ export const CORNERS_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = {
   },
   plug: { type: "strategy", step: "plugs", describe: "The plug rule: a strategy of the step `plugs`. Without it, the option `plugs` places the plugs." },
   plugOptions: { type: "object", describe: "The options of the strategy `plug`." },
+  outside: {
+    type: "enum",
+    values: ["throw", "skip", "clamp"],
+    default: "throw",
+    describe: "The rule for a box outside the box of its frame: throw a `RangeError`, skip the box and its inner edges, or cut the box to the bounds.",
+  },
+  frameInset: {
+    type: "number",
+    min: 0,
+    max: 20,
+    step: 1,
+    describe: "The distance from the walls of a frame to the bounds of its inner routes. Without a value, the inset is the margin.",
+  },
 };
 
 /** The declarations of the options of the router `trunks`. */