@mark1russell7/highways 0.3.0 → 0.4.0

package/build/index.d.ts

@@ -1038,6 +1038,64 @@ interface LevelLinkOptions extends WayOptions {
    */
   readonly throughCost?: number;
 }
+/** The input of a highway strategy: the boxes and the edges, and optionally the first routes of a router. */
+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.
+ */
+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. */
+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. */
+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 declare function pointAt(line: readonly Point[], at: number): Point;
+/** This function gives the length of a polyline from the place `from` to the place `to`, with `from` not larger than `to`. */
+export declare function lengthBetween(line: readonly Point[], from: number, to: number): number;
+/** 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 declare function memberAt(spine: readonly Point[], edge: string, on: number, off: number, seq?: number): HighwayMember;
+/**
+ * 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 declare function checkPlan(graph: Graph, plan: HighwayPlan): string[];
 /**
  * The options of the room for the bends of the bundles (HWC-D). With them, `roomDemand` also opens the gaps where a bundle bends.
  * The values agree with the options of `highwayCurves` that draw the bundles.
@@ -1296,6 +1354,25 @@ export interface CurveInput {
   readonly endNormal?: Point;
   /** The boxes that the curve must not go through, from `curveSpace`. */
   readonly space?: CurveSpace;
+  /**
+   * The lane of the polyline on its board, for a strategy that bends the lanes of a bundle as one. Then `points` is the route of `laneRoutes` with the index `index`.
+   * The other strategies do not read it.
+   */
+  readonly lane?: {
+    readonly board: LaneBoard;
+    readonly index: number;
+  };
+}
+/** The lanes of the bundles of one board: the input of `laneRoutes` and `highwayCurves`. */
+export interface LaneBoard {
+  /** The shared segments and the paths of the routes, from `segmentsOf`. */
+  readonly graph: SegmentGraph;
+  /** The keys of the open segments, from `runKey`. Each edge of an open segment gets its own lane. */
+  readonly open: ReadonlySet<string>;
+  /** The distance between two lanes of an open segment. */
+  readonly width: number;
+  /** The largest width of an open segment, from its outer lane to its outer lane. The default is `Infinity`. */
+  readonly maxWidth?: number;
 }
 /** The input of a room strategy: the boxes of a board and the links between them. */
 export interface RoomInput {
@@ -1312,6 +1389,7 @@ export interface RoomInput {
  *
  * - `group`: a graph in, the tree of sections out. The router `sections` makes its hubs and its zoom levels from this tree.
  * - `router`: a graph in, the routes (and the `levels`, `bundles` and `runs`) out.
+ * - `highway`: a graph and optionally its first routes in, a highway plan out. `follow` routes the edges along the plan.
  * - `curve`: a polyline in, the segments of a curve out.
  * - `room`: the boxes and links of a board in, the gaps of the board with their need out.
  */
@@ -1324,6 +1402,10 @@ export interface StepTypes {
     readonly input: Graph;
     readonly output: Result;
   };
+  readonly highway: {
+    readonly input: HighwayInput;
+    readonly output: HighwayPlan;
+  };
   readonly curve: {
     readonly input: CurveInput;
     readonly output: CurveSegment[];
@@ -1384,10 +1466,11 @@ export declare function defineStrategy<S extends Step, O extends object>(definit
 /**
  * A registry: the strategies of each step, in order. A registry is data. No import changes it.
  * A consumer makes its own registry with `createRegistry`, and adds a strategy with `register`.
- * The list `group` is optional in the type, so a registry from version 0.1.5 stays a registry. `createRegistry` always gives it.
+ * The lists `group` and `highway` are optional in the type, so a registry from version 0.1.5 or 0.3.0 stays a registry. `createRegistry` always gives them.
  */
-export type Registry = { readonly [S in Exclude<Step, "group">]: readonly Strategy<S>[]; } & {
+export type Registry = { readonly [S in Exclude<Step, "group" | "highway">]: readonly Strategy<S>[]; } & {
   readonly group?: readonly Strategy<"group">[];
+  readonly highway?: readonly Strategy<"highway">[];
 };
 /** This function makes a registry from a list of strategies. It keeps their order. Two strategies with one step and one name are an error. */
 export declare function createRegistry(strategies: readonly AnyStrategy[]): Registry;
@@ -2615,6 +2698,11 @@ export interface CurveRunOptions {
   readonly normals: ReadonlySet<string>;
   /** The options of each curve strategy, by its name. A strategy without an entry gets its defaults. */
   readonly curveOptions?: Readonly<Record<string, object>>;
+  /**
+   * With this board, each curve draws the lanes of `laneRoutes` in place of the routes of the result, and each input has its `lane`.
+   * So the curve `highway` bends the lanes of a bundle as one. Without it, each curve draws the routes of the result.
+   */
+  readonly lanes?: LaneBoard;
 }
 /** One curve strategy on the routes of one result: the row of the suite and the drawn curves. */
 export interface CurveRun {
@@ -2645,8 +2733,8 @@ export declare function groupRun(graph: Graph, strategy: Strategy<"group">, opti
   readonly seed: number;
 }): GroupRun;
 /**
- * This function gives the options of a grouping rule on a fixture. The rule `keys` gets a key from the data of the edges:
- * the collection of the first edge into the node. A node without such an edge is a group alone.
+ * This function gives the options of a grouping rule on a fixture. The rule `keys` gets the string `data.group` of the node.
+ * A node without it gets a key from the data of the edges: the collection of the first edge into the node. A node without such an edge is a group alone.
  */
 export declare function fixtureGroupOptions(strategy: string, graph: Graph): object;
 /**
@@ -2659,7 +2747,7 @@ export declare function runSuite(options?: SuiteOptions): {
 };
 /**
  * This function puts the rows of the suite in the order of one run. It sorts them by fixture family, then by seed.
- * In one seed, the routers come first, and the curves come after the router of the curves. The grouping rules and the room come last.
+ * In one seed, the routers come first, and the curves come after the router of the curves. Then the highway strategies come, and the grouping rules and the room come last.
  * A name that is not in its list goes after the names of the list.
  * The workflow `Bench` uses it to join the reports of its parts.
  */
@@ -2703,6 +2791,58 @@ export declare function formatRules(rules: readonly RuleCount[]): string;
  * It gives one row for each fixture family of a step. The extra routes of the stability measures have their own column.
  */
 export declare function formatMeasureTime(rows: readonly SuiteRow[], step?: Step): string;
+/**
+ * The options of the highway strategy `corridors` (HWY-031 of the note on highways).
+ * The options `margin` and `k` set the corner graph of the first ways, when the input has no first routes.
+ */
+interface CorridorOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** Two edges join when their common links are this share of the shorter way, or longer. The default is 0.3. */
+  readonly rho: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+  /** The number of hash functions of the MinHash signature of a way. The default is 64. */
+  readonly hashes: number;
+  /** The number of bands of the signature. Two ways with one equal band are a candidate pair. The default is 32. */
+  readonly bands: number;
+  /** Two link ends nearer than this grid size are one point. With 0, the default, only equal points are one point. */
+  readonly near: number;
+  /** The gap between two lanes. Two edges join only when their common links are longer than the break-even overlap for this gap. The default is 4. */
+  readonly lane: number;
+}
+/** The default options of the strategy `corridors`. */
+export declare const CORRIDOR_DEFAULTS: Readonly<Required<Omit<CorridorOptions, "margin" | "k">>>;
+/**
+ * The break-even overlap of two parallel edges for each unit of the lane gap, with the cost exponent 0.5 of the note.
+ * A shared stretch shorter than this times the gap adds ink.
+ */
+export declare const BREAK_EVEN: number;
+/** This function gives the MinHash signature of a set of keys with `count` hash functions. */
+export declare function minHash(keys: Iterable<string>, count: number): number[];
+/**
+ * This function gives the highways of corridor signatures (HWY-031). Each edge gets a first way: the route of `input.routes`, or its way through the corner graph.
+ * The signature of a way is the set of its links. Two edges join when their common links are at least `rho` times the shorter way, and longer than the break-even overlap.
+ * MinHash with `hashes` hash functions in `bands` bands finds the candidate pairs fast. Union-find gives the clusters.
+ *
+ * In each cluster, the spine is the longest common run of links of the way with the most shared length. Each edge on the spine joins it at its first common link and leaves it at its last one.
+ * The edges of the cluster that are not on the spine make the next highway, while `minSize` of them remain.
+ */
+export declare function corridorPlan(input: HighwayInput, o: Readonly<CorridorOptions>): HighwayPlan;
+/** The options of the highway strategy `keys`: the options of the router `trunks`, without the name and the limit of the benchmark. */
+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 declare function keysPlan(input: HighwayInput, options: KeysOptions): HighwayPlan;
+/** The options of the highway strategy `shared-ways`: the options of the router `shared`, without the name and the limit of the benchmark. */
+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 declare function sharedWaysPlan(input: HighwayInput, options: SharedWaysOptions): HighwayPlan;
 /** The options of a router strategy: the options of its router, without the name and the limit of the benchmark. */
 export type RouterPreset<O> = Omit<O, "name" | "maxNodes">;
 /** The built-in router strategies, in the order of the benchmark. They route as the routers of `ROUTERS`. */
@@ -2727,7 +2867,10 @@ export interface TensionOptions {
   /** The tension of the spline, from 0 (the spline) to 1 (the polyline). The default is 0. */
   readonly tension: number;
 }
-/** The options of the curve strategy `highway`. */
+/**
+ * The options of the curve strategy `highway`. The options `minRadius`, `jog` and `jogPieces` change only the lanes of a bundle.
+ * So they change the curve only when the input has a `lane` on a board with open segments.
+ */
 export interface HighwayStrategyOptions {
   /** The radius of the center line of a bundle at a bend, and of each lone corner. The default is 12. */
   readonly radius: number;
@@ -2756,7 +2899,7 @@ export interface ClothoidStrategyOptions {
 }
 /**
  * The built-in curve strategies. The first six are in the order of `CURVE_TYPES`, and each one gives the same segments as `curveOf` with its type.
- * The strategy `highway` gives the curve of `arc` for one polyline. `highwayCurves` bends the lanes of a bundle as one.
+ * The strategy `highway` gives the curve of `arc` for one polyline. For a polyline with a `lane`, it bends the lanes of each bundle as one with `highwayCurves`.
  */
 export declare const curveStrategies: {
   readonly straight: Strategy<"curve", object>;
@@ -2784,12 +2927,24 @@ export declare const groupStrategies: {
   readonly kd: Strategy<"group", Required<KdOptions>>;
   readonly cut: Strategy<"group", Required<CutOptions>>;
 };
+/**
+ * The built-in highway strategies: the decisions of the routers `trunks` and `shared` as plans, and corridor signatures (HWY-031).
+ * `follow` routes the edges along a plan, and `highwayRouter` gives a router that does both.
+ */
+export declare const highwayStrategies: {
+  readonly keys: Strategy<"highway", KeysOptions>;
+  readonly "shared-ways": Strategy<"highway", SharedWaysOptions>;
+  readonly corridors: Strategy<"highway", CorridorOptions>;
+};
 /** The built-in strategies of each step, in order. A consumer adds its own: `createRegistry([...BUILT_IN_STRATEGIES, mine])`. */
 export declare const BUILT_IN_STRATEGIES: readonly AnyStrategy[];
 /** The registry of the built-in strategies. The benchmark and the site take their lists from it. */
 export declare const STRATEGIES: Registry;
-/** The steps that `compareStep` compares. The step `room` takes a packed board, not a graph, so it is not in the list. */
-export type CompareStep = Exclude<Step, "room">;
+/**
+ * The steps that `compareStep` compares. The step `room` takes a packed board, not a graph, so it is not in the list.
+ * The step `highway` gives a plan, not routes. The screen routes each plan with `follow` and compares it as a router.
+ */
+export type CompareStep = Exclude<Step, "room" | "highway">;
 /** The steps that `compareStep` compares, in the order of the pipeline. */
 export declare const COMPARE_STEPS: readonly CompareStep[];
 /** The options of `compareStep`. */
@@ -2800,6 +2955,14 @@ export interface CompareOptions {
   readonly options?: Readonly<Record<string, object>>;
   /** The router whose routes the step `curve` draws. The default is `corners`, as in `runSuite`. */
   readonly curveRouter?: string;
+  /**
+   * With this value, the step `curve` opens each shared segment of the routes of `curveRouter`, and each curve draws the lanes of `laneRoutes`.
+   * So the curve `highway` bends the lanes of a bundle as one. Without it, each curve draws the routes. A router without shared segments gives the routes in both cases.
+   */
+  readonly lanes?: {
+    readonly width: number;
+    readonly maxWidth?: number;
+  };
   /** The seed of the small change of the graph for the stability measures (Z10 and G9). The default is 1. */
   readonly seed?: number;
   /** The route stability (Z10) routes a changed graph again, so the function measures it only up to this number of nodes. The default is 1000. */
@@ -2815,7 +2978,10 @@ export interface CompareRow {
   readonly violations: number;
   /** The time of the step, in milliseconds. For the step `router`, it is the median of two routes. */
   readonly ms: number;
-  /** The measures, by the keys of `runSuite`, and `ms`. The step `router` adds `ink`, and the step `curve` adds `C5.peak`. */
+  /**
+   * The measures, by the keys of `runSuite`, and `ms`. The step `router` adds `ink`, and the step `curve` adds `C5.peak`.
+   * A router with zoom levels also gets `Z3.through` and `Z3.length`, the measures of its level links.
+   */
   readonly values: Readonly<Record<string, number>>;
   /** The reason when the strategy did not run, for example a graph over its `maxNodes`. */
   readonly skipped?: string;
@@ -2842,11 +3008,531 @@ export interface StepComparison {
 }
 /**
  * This function runs each strategy of one step on one graph and measures it with the measures of `runSuite`. Then it gives the Pareto front.
- * The step `router` routes the graph with each router. The step `curve` draws the routes of `curveRouter` with each curve.
+ * The step `router` routes the graph with each router. The step `curve` draws the routes of `curveRouter` with each curve, or their lanes with the option `lanes`.
  * The step `group` routes the graph with `sections` on the tree of each grouping rule.
  *
  * The same graph and the same options give the same measures. Only the times change.
  */
 export declare function compareStep(step: CompareStep, graph: Graph, options?: CompareOptions): StepComparison;
-export type { ArcOptions, ClothoidOptions, CornersOptions, CurveSpace, CutObjective, CutOptions, HighwayOptions, JogStyle, KdAxis, KdLine, KdOptions, KeyOptions, LaneCurve, NodeKey, RoomBends, RoundedOptions, SectionsOptions, SharedOptions, SmoothOptions, SplineOptions, TrunksOptions };
+/** This function gives the bytes of a string in UTF-8. */
+export declare function utf8(text: string): Uint8Array;
+/** This function gives the SHA-256 digest of a string, as 64 lowercase hex characters. It encodes the string in UTF-8. */
+export declare function sha256Hex(text: string): string;
+/**
+ * This function writes a value as canonical JSON: the keys of each object in sorted order, and no whitespace.
+ * It drops a key whose value is `undefined`, as `JSON.stringify` does.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * This function gives the hash of a JSON document: the first 16 hex characters of the SHA-256 of its canonical JSON.
+ * The document does not include its own field `hash`. The function removes that field before it calculates the hash.
+ */
+export declare function documentHash(value: object): string;
+/** This function gives the 32-bit FNV-1a hash of the UTF-8 bytes of a text, as an unsigned integer. */
+export declare function fnv1a32(text: string): number;
+/** This function gives the seed of one step of a generator: `fnv1a32("<seed>:<step>")`. */
+export declare function stepSeed(seed: number, step: string): number;
+/** This function gives the generator `mulberry32` for a seed. Each call gives the next number from 0 to below 1. */
+export declare function mulberry32(seed: number): () => number;
+/** This function rounds a number to 3 decimals, as the files of a corpus keep it. The value `-0` becomes `0`. */
+export declare function round3(value: number): number;
+/** The side of a port in an input file. The router calls the same sides `north`, `east`, `south` and `west`. */
+export type LayoutSide = "top" | "right" | "bottom" | "left";
+/** A port of a box in an input file. */
+export interface LayoutPort {
+  readonly id: string;
+  /** The side of the box. Without it and without `x` and `y`, the router picks the side. */
+  readonly side?: LayoutSide;
+  /** The fixed place of the port, from the top-left corner of the box. The router does not move a port with `x` and `y`. */
+  readonly x?: number;
+  readonly y?: number;
+}
+/** A point of a region: `[x, y]`. The y axis points down. */
+export type RegionPoint = readonly [number, number];
+/**
+ * An area of the plane. The y axis points down. A ring of a polygon closes itself: its last point joins its first point.
+ * A hole of a polygon does not touch the outer ring. The router reads only the bounding box of a region.
+ */
+export type Region = {
+  readonly kind: "rect";
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+} | {
+  readonly kind: "polygon";
+  readonly points: readonly RegionPoint[];
+  readonly holes?: readonly (readonly RegionPoint[])[];
+} | {
+  readonly kind: "circle";
+  readonly cx: number;
+  readonly cy: number;
+  readonly r: number;
+} | {
+  readonly kind: "ellipse";
+  readonly cx: number;
+  readonly cy: number;
+  readonly rx: number;
+  readonly ry: number;
+};
+/** An area that the boxes and the routes must not use. The router uses the bounding box of its region as a box without edges. */
+export interface LayoutObstacle {
+  readonly id: string;
+  readonly region: Region;
+  /** The cost to move the obstacle. Only the packer reads it. */
+  readonly move?: {
+    readonly cost: number;
+  };
+}
+/** A box of an input file. */
+export interface LayoutBox {
+  readonly id: string;
+  readonly w: number;
+  readonly h: number;
+  /** The position of the top-left corner. The packer writes it. The router reads it. */
+  readonly x?: number;
+  readonly y?: number;
+  /** The id of the box that holds this box. */
+  readonly parent?: string;
+  /** The group of the box. */
+  readonly group?: string;
+  /** This value is `true` when the box is an obstacle: the packer keeps its `x` and `y`. The router ignores it. */
+  readonly locked?: true;
+  /** The reading order that the caller wants. The router ignores it. */
+  readonly rank?: number;
+  readonly ports?: readonly LayoutPort[];
+  /** The shape of the box, relative to the top-left corner of the box. The router ignores it and uses `w` and `h` as the bounding box. */
+  readonly shape?: Region;
+  /** The free data of the node. The grouping rule `keys` reads `data.group`. */
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+/** An edge of an input file. `sourcePort` and `targetPort` name a port of the box at that end. */
+export interface LayoutEdge {
+  readonly id: string;
+  readonly source: string;
+  readonly target: string;
+  readonly sourcePort?: string;
+  readonly targetPort?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+/** The change of a variant against its base input. */
+export type LayoutChange = "add" | "remove" | "resize" | "reorder" | "packed";
+/** The origin of an input: `made-up`, `published:<set>` or `known-best:<construction>`. */
+export type LayoutSource = "made-up" | `published:${string}` | `known-best:${string}`;
+/** The generator of an input. The same name, version, parameters and seed give the same file, byte for byte. */
+export interface LayoutGenerator {
+  readonly name: string;
+  readonly version: number;
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly seed: number;
+}
+/**
+ * The cell of an input in the taxonomy of the corpus, with one value for each dimension.
+ * The packer reads the first six dimensions. The router reads the last four.
+ */
+export interface LayoutCell {
+  readonly containerSize?: "fixed" | "freeWidth" | "freeAspect";
+  readonly containerShape?: "rect" | "convex" | "polygon" | "circle" | "ellipse" | "holes";
+  readonly obstacles?: "none" | "center" | "scattered" | "wall" | "corridors" | "touching" | "edge";
+  readonly sizes?: "identical" | "uniform" | "heavyTail" | "bimodal" | "extremeAspect" | "nearIdentical";
+  readonly count?: "1" | "10" | "100" | "1k" | "10k";
+  readonly mode?: "offline" | "online" | "incremental";
+  readonly edgeDensity?: "sparse" | "medium" | "dense";
+  readonly edgeShape?: "random" | "clustered" | "hubChain" | "longRange" | "tree" | "bundled";
+  readonly groups?: "none" | "flat" | "nested";
+  readonly ports?: "free" | "sides" | "fixed";
+}
+/** The outer rectangle of a packing. The router ignores it. */
+export interface LayoutContainer {
+  readonly w?: number;
+  readonly h?: number;
+  /** `none`: the packer picks the size. `width`: the width stays. `height`: the height stays. `size`: the width and the height stay. */
+  readonly fixed: "none" | "width" | "height" | "size";
+  /** The ratio `w / h` that the packer aims for. */
+  readonly aspect?: number;
+  /** The shape of the container. */
+  readonly shape?: Region;
+}
+/** The identity of an input in a set: the set, the family, the seed, and the base of a variant. */
+export interface LayoutInputHead {
+  /** The id: `<set>/<family>/s<seed>`. */
+  readonly id: string;
+  readonly set: string;
+  readonly family: string;
+  readonly seed: number;
+  /** The id of the base input of a variant. The stability measures compare the run on the variant with the run on its base. */
+  readonly base?: string;
+  readonly change?: LayoutChange;
+  /** The place of the input in a change sequence. */
+  readonly step?: number;
+  /** The generator of the input. The default is `null`: a hand-made input. */
+  readonly generator?: LayoutGenerator | null;
+  /** The origin of the input. The default is `made-up`. */
+  readonly source?: LayoutSource;
+  readonly cell?: LayoutCell;
+}
+/**
+ * An input file of the form `layout-input/1`. The packer and the router read the same files.
+ * The file `docs/LAYOUT-RECORDS.md` gives the form. The repository `packing` keeps a twin of that document.
+ */
+export interface LayoutInput extends LayoutInputHead {
+  readonly schema: "layout-input/1";
+  /** The origin of the input. The data of this repository is made-up, because the repository is public. */
+  readonly source: LayoutSource;
+  /** The generator of the input, or `null` for a hand-made input. */
+  readonly generator: LayoutGenerator | null;
+  /** The first 16 hex characters of the SHA-256 of the canonical file without this field. `documentHash` calculates it. */
+  readonly hash: string;
+  readonly container?: LayoutContainer;
+  /** The space between two boxes. The router ignores it. */
+  readonly gap?: number;
+  /** The areas that the boxes and the routes must not use. */
+  readonly obstacles?: readonly LayoutObstacle[];
+  readonly boxes: readonly LayoutBox[];
+  readonly edges: readonly LayoutEdge[];
+}
+/** One run of one strategy on one input and one seed: a line of the form `layout-record/1`. */
+export interface LayoutRecord {
+  readonly schema: "layout-record/1";
+  /** `pack`, `route` or `joint`. The screen of this package writes `route`. */
+  readonly stage: "pack" | "route" | "joint";
+  readonly step: string;
+  readonly strategy: string;
+  /** The options of the run: the defaults of the strategy with the options of the caller. A function is the text `function:<name>`. */
+  readonly options: Readonly<Record<string, unknown>>;
+  /** The corpus version, for example `screen-v1`. */
+  readonly corpus: string;
+  /** The id of the input. */
+  readonly input: string;
+  /** The `hash` of the input file. */
+  readonly inputHash: string;
+  readonly set: string;
+  readonly seed: number;
+  readonly nodes: number;
+  readonly edges: number;
+  /** The measures, by the names of `MEASURES`. A measure without a finite value is not in the record. */
+  readonly measures: Readonly<Record<string, number>>;
+  /** The count of the breaks of each hard rule. A good run has 0 for each rule. */
+  readonly hard: Readonly<Record<string, number>>;
+  /** The tolerance of each hard rule of the run, for example `{ through: 0.5 }`. */
+  readonly tolerance?: Readonly<Record<string, number>>;
+  /** This value is `true` when two runs on the same input give the same output. */
+  readonly deterministic: boolean;
+  /** The id of the prediction of this run, from the predictions file. */
+  readonly prediction?: string;
+  /** The time of the run, in milliseconds. Only the times of CI compare. */
+  readonly ms: number;
+  /** The commit of the code that made the record. */
+  readonly commit?: string;
+  /** The reason when the strategy did not run, for example an input over its `maxNodes`. Then the record has no measures. */
+  readonly skipped?: string;
+}
+/** The comparison of a prediction. Without it, `<=` applies to a measure where lower is better, and `>=` to the other measures. */
+export type PredictionOp = "<" | "<=" | "=" | ">=" | ">";
+/** A prediction about a run: one line of a predictions file. A commit adds the file before the run starts. */
+export interface LayoutPrediction {
+  readonly schema?: "layout-prediction/1";
+  readonly id: string;
+  readonly strategy: string;
+  readonly set: string;
+  /** The id of one input. Without it, the prediction is about the median of the measure over the set. */
+  readonly input?: string;
+  /** The name of the measure, from `MEASURES`. */
+  readonly measure: string;
+  readonly expected: number;
+  readonly op?: PredictionOp;
+  readonly reason: string;
+}
+/**
+ * This function writes a graph as an input file of the form `layout-input/1`, with its hash.
+ * A fixed plug gets `x`, `y` and the side that holds it. `inputGraph` reads the file back.
+ */
+export declare function graphInput(graph: Graph, head: LayoutInputHead): LayoutInput;
+/**
+ * This function gives the bounding box of a region: the smallest box that holds it.
+ */
+export declare function regionBounds(region: Region): {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+};
+/**
+ * This function reads the graph of the router from an input file. The router reads the positions, the ports, the edges and the data.
+ * Each obstacle becomes a node without edges, with the bounding box of its region, after the boxes.
+ * The router ignores the other fields of the packer: `container`, `gap`, `locked`, `rank`, the `shape` of a box and the `move` of an obstacle.
+ * A box without `x` and `y` is an error.
+ */
+export declare function inputGraph(input: LayoutInput): Graph;
+/**
+ * This function writes an input file as text: the keys in sorted order, and one box or one edge on each line.
+ * `JSON.parse` of the text gives the input again.
+ */
+export declare function formatInput(input: LayoutInput): string;
+/** This function writes records as JSON Lines: one record on each line. */
+export declare function recordLines(records: readonly LayoutRecord[]): string;
+/** This function reads JSON Lines. It ignores an empty line. */
+export declare function parseLines<T>(text: string): T[];
+/**
+ * This function gives a copy of a value that JSON keeps.
+ * A function becomes the text `function:<name>`, and a number that is not finite becomes its text.
+ */
+export declare function jsonSafe(value: unknown): unknown;
+/**
+ * One measure of a record. `key` is the key of the measure in the values of `runSuite` and `compareStep`.
+ * `name` is the name of the measure in a record of the form `layout-record/1`.
+ */
+export interface MeasureInfo {
+  /** The key in the values of `runSuite` and `compareStep`, for example `R5.median`. */
+  readonly key: string;
+  /** The id of the measure in `docs/research/MEASURES.md` (MEAS0), for example `R5`. */
+  readonly id: string;
+  /** The name in a record: lowercase, with a dot after the stage, for example `route.detour.median`. */
+  readonly name: string;
+  readonly unit: string;
+  readonly better: "lower" | "higher";
+  /**
+   * This value is `true` when the positions of the boxes alone can move the value, with the same router.
+   * Then two values compare only on the same input. The value is `false` when the measure scores the routes or the curves for a fixed placement.
+   */
+  readonly placementDependent: boolean;
+}
+/**
+ * The measures of the records of the stage `route`, with the placement dependence of each one.
+ * A joint harness that moves the boxes and routes the edges reads `placementDependent`.
+ * It compares a measure with the value `true` only between runs on the same input.
+ */
+export declare const MEASURES: readonly MeasureInfo[];
+/** This function gives the measure of a key of `runSuite` or `compareStep`, or `undefined` for a key that is not in `MEASURES`. */
+export declare function measureByKey(key: string): MeasureInfo | undefined;
+/** This function gives the measure of a name of a record, or `undefined` for a name that is not in `MEASURES`. */
+export declare function measureByName(name: string): MeasureInfo | undefined;
+/** This function gives the name of a key in a record. A key that is not in `MEASURES` gets the name `route.other.<key>`. */
+export declare function measureName(key: string): string;
+/** This function gives the objectives of a Pareto front by the names of a record, from objectives by the keys of `runSuite`. */
+export declare function namedObjectives(objectives: readonly Objective[]): Objective[];
+/** A family of boards of a screen set. The member `k` of the family has the seed `k`. */
+export interface ScreenFamily {
+  readonly name: string;
+  /** The known hard case that the family shows, in a few words. */
+  readonly shows: string;
+  /** The number of members. */
+  readonly seeds: number;
+  /** This function makes the member `k`. The same `k` always gives the same graph. */
+  readonly make: (k: number) => Graph;
+  /** This function gives the generator of the member `k`: its name, version, parameters and seed. */
+  readonly generator: (k: number) => LayoutGenerator;
+  /** The cell of each member in the taxonomy of the corpus. */
+  readonly cell: LayoutCell;
+}
+/** A screen set: a fixed list of small boards with an id. A new board or a changed board gets a new id. */
+export interface ScreenSet {
+  /** The id of the set, for example `screen-v1`. The records name it in `set` and `corpus`. */
+  readonly id: string;
+  readonly families: readonly ScreenFamily[];
+}
+/**
+ * The screen set `screen-v1`: 14 boards of made-up data from 10 to 150 nodes. Each family shows a known hard case.
+ * The seed 0 of each family is the fixture or the case board of the benchmark. The seed `k` of a fixture family is `familySeed(spec, k)`, as in `runSuite`.
+ * The generators wrap the fixtures and the case boards without a change to their output.
+ * This set does not change. The tests compare it with the files in `corpus/screen-v1`.
+ */
+export declare const SCREEN_V1: ScreenSet;
+/** The screen sets by id. */
+export declare const SCREEN_SETS: Readonly<Record<string, ScreenSet>>;
+/** This function gives the id of the member `seed` of a family of a set: `<set>/<family>/s<seed>`. */
+export declare function inputId(set: string, family: string, seed: number): string;
+/** This function gives the input files of a screen set, in the order of its families and seeds. Each file has its hash. */
+export declare function screenInputs(set?: ScreenSet): LayoutInput[];
+/** A spec of a manifest: one generator with its version and parameters, and the seeds that the corpus uses. */
+export interface CorpusSpec {
+  readonly generator: string;
+  readonly version: number;
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly seeds: readonly number[];
+}
+/** The manifest `corpus.json` of a corpus, of the form `layout-corpus/1`. */
+export interface LayoutCorpus {
+  readonly schema: "layout-corpus/1";
+  readonly corpus: string;
+  readonly specs: readonly CorpusSpec[];
+  readonly inputs: readonly {
+    readonly id: string;
+    readonly hash: string;
+    readonly cell: LayoutCell;
+  }[];
+}
+/** This function gives the manifest of a list of inputs. The inputs of one generator, version and parameters share one spec. */
+export declare function corpusManifest(corpus: string, inputs: readonly LayoutInput[]): LayoutCorpus;
+/**
+ * The steps of the screen: the steps of `compareStep` and the step `highway`.
+ * The screen of the step `highway` routes the plan of each strategy with `follow`, and measures the routes as the routes of a router.
+ */
+export type ScreenStep = CompareStep | "highway";
+/** The steps of the screen, in the order of the pipeline. */
+export declare const SCREEN_STEPS: readonly ScreenStep[];
+/** The routers that the screen of the step `highway` also runs by default. They are the baselines of the note on highways. */
+export declare const HIGHWAY_BASE_ROUTERS: readonly string[];
+/** The hard rules of each step of the screen, in the order of the records. A good run has 0 for each rule. */
+export declare const SCREEN_RULES: Readonly<Record<ScreenStep, readonly string[]>>;
+/** The options of `screen`. */
+export interface ScreenOptions {
+  /** The screen set. The default is `SCREEN_V1`. */
+  readonly set?: ScreenSet;
+  /** The input files. The default is the files of `set`. */
+  readonly inputs?: readonly LayoutInput[];
+  /** The families of the inputs that the screen runs. The default is each family. */
+  readonly families?: readonly string[];
+  /**
+   * With `true`, the screen also runs each built-in strategy of the step, and the front compares the new strategies with them.
+   * With `false`, it runs only the strategies of the call. The default is `true`.
+   */
+  readonly baseline?: boolean;
+  /** The options of each strategy, by its name. A strategy without an entry gets its defaults. */
+  readonly options?: Readonly<Record<string, object>>;
+  /** The router whose routes the step `curve` draws. The default is `corners`. */
+  readonly curveRouter?: string;
+  /**
+   * The routers that the screen of the step `highway` also runs. Their records have the step `router`.
+   * The default is `HIGHWAY_BASE_ROUTERS`. The other steps do not read it.
+   */
+  readonly baseRouters?: readonly string[];
+  /** The seed of the small change of the stability measures. The default is 1. */
+  readonly seed?: number;
+  /** The commit of the code, for the records. */
+  readonly commit?: string;
+  /** The predictions of the run. Each record names the first prediction with its strategy, its set and its input. */
+  readonly predictions?: readonly LayoutPrediction[];
+  /** This function gets one line of progress for each input. */
+  readonly log?: (line: string) => void;
+}
+/** The summary of one strategy over the inputs of a screen. */
+export interface ScreenStrategySummary {
+  readonly strategy: string;
+  /** This value is `true` for a strategy of the call, and `false` for a built-in strategy of the baseline. */
+  readonly candidate: boolean;
+  /** The number of inputs where the strategy ran. */
+  readonly runs: number;
+  /** The number of inputs that the strategy skipped. */
+  readonly skipped: number;
+  /** This value is `true` when each run gave the same output two times. */
+  readonly deterministic: boolean;
+  /** The sum of the breaks of each hard rule over the runs. */
+  readonly hard: Readonly<Record<string, number>>;
+  /** The sum of `hard`. */
+  readonly hardTotal: number;
+  /**
+   * The breaks over the floor of each input. The floor is the counts of the built-in strategy with the fewest breaks on that input.
+   * Each built-in breaks a rule on some boards, for example on a board where the boxes touch. Without built-ins, the floor is 0.
+   */
+  readonly hardOverFloor: number;
+  /** The median of each measure over the runs, by the names of a record. */
+  readonly medians: Readonly<Record<string, number>>;
+  /** The median time of a run, in milliseconds. */
+  readonly ms: number;
+  /** The number of inputs where the strategy is on the Pareto front of its input. */
+  readonly onFront: number;
+}
+/** A prediction with the measured value. */
+export interface PredictionCheck extends LayoutPrediction {
+  readonly op: PredictionOp;
+  /** The measured value: the value of the record of the input, or the median over the set. It is absent when no record has the measure. */
+  readonly measured?: number;
+  /** This value is `true` when the measured value meets the prediction. It is absent when there is no measured value. */
+  readonly met?: boolean;
+}
+/** The summary of a screen. */
+export interface ScreenSummary {
+  readonly set: string;
+  readonly step: ScreenStep;
+  /** The number of inputs. */
+  readonly inputs: number;
+  /** The axes of the Pareto front, by the names of a record. */
+  readonly objectives: readonly Objective[];
+  /** One summary for each strategy, in the order of the registry. */
+  readonly strategies: readonly ScreenStrategySummary[];
+  /** The strategies on the Pareto front of the medians over the set. */
+  readonly front: readonly string[];
+  /** The strategies with a break over the floor, without a run or with two different outputs of one input. They do not enter the front. */
+  readonly excluded: readonly string[];
+  readonly predictions: readonly PredictionCheck[];
+}
+/** The result of `screen`: one record for each strategy and input, and the summary. */
+export interface ScreenReport {
+  readonly records: readonly LayoutRecord[];
+  readonly summary: ScreenSummary;
+}
+/**
+ * This function screens strategies of one step on the inputs of a screen set. It is the cheap test of a new idea before a full build.
+ * Each strategy runs on each input with `compareStep`, and each run gives one record of the form `layout-record/1`.
+ * A strategy can be a name of the registry or a strategy object, for example from a prototype file. The registry does not change.
+ *
+ * The step `router` routes each input two times for the rule "same twice". The steps `group` and `curve` run each input two times for the same rule.
+ *
+ * The step `highway` makes the plan of each strategy and routes it with `follow`, two times. It also runs the routers of `baseRouters`.
+ * An input with a `base` in the inputs also gets the measures `route.stability.base.*`: the routes on the variant against the routes on its base.
+ * The same inputs and the same options give the same records. Only the times change.
+ */
+export declare function screen(step: ScreenStep, strategies?: readonly (Strategy<ScreenStep> | string)[], options?: ScreenOptions): ScreenReport;
+/** This function writes the summary of a screen as Markdown: one row for each strategy, the front and the predictions. */
+export declare function formatScreen(summary: ScreenSummary): string;
+/** This function gives a whole number from `lo` to `hi`, both included, from a generator of random numbers. */
+export declare function randomInt(r: () => number, lo: number, hi: number): number;
+/** The parameters of the generator `rect-scattered`. */
+export interface RectScatteredParams {
+  /** The number of boxes. */
+  readonly count: number;
+}
+/**
+ * This function makes the input of the shared generator `rect-scattered`, version 1: a fixed rectangle container, scattered obstacles and boxes without positions.
+ * The repository `packing` makes the same file, byte for byte. A test in each repository pins the hashes of the seeds 1, 2 and 3.
+ * The steps are `container`, `obstacles` and `boxes`. Each step has its own generator from `stepSeed`.
+ */
+export declare function rectScattered(seed: number, params: RectScatteredParams, set?: string): LayoutInput;
+/** The options of `follow`. */
+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;
+}
+/**
+ * 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 declare function follow(graph: Graph, plan: HighwayPlan, options?: FollowOptions): Result;
+/**
+ * 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 declare function planOfResult(result: Result): HighwayPlan;
+/**
+ * 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 declare function highwayRouter<O extends object>(strategy: Strategy<"highway", O>, options?: Partial<O>, followOptions?: FollowOptions): Router;
+/**
+ * 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 declare function highwayRouterStrategy<O extends object>(strategy: Strategy<"highway", O>): Strategy<"router", O>;
+export type { ArcOptions, ClothoidOptions, CornersOptions, CorridorOptions, CurveSpace, CutObjective, CutOptions, FollowOptions, Highway, HighwayInput, HighwayMember, HighwayOptions, HighwayPlan, JogStyle, KdAxis, KdLine, KdOptions, KeyOptions, KeysOptions, LaneCurve, NodeKey, RoomBends, RoundedOptions, SectionsOptions, SharedOptions, SharedWaysOptions, SmoothOptions, SplineOptions, TrunksOptions };
 //# sourceMappingURL=index.d.ts.map