@mark1russell7/highways 0.5.0 → 0.5.1

package/src/bench/screen/hash.ts

@@ -1,14 +1,10 @@
-// The core runs in any host, so this file has its own SHA-256. It needs no API of Node or of the browser.
+// The hash, the canonical JSON and the seeded random numbers of the screen. `sha256Hex`, `canonicalJson` and `RECORD_EPS` come from
+// `@mark1russell7/layout-contract` (PORTFOLIO-FIT). The other functions have no equal in the contract, so they stay here.
+import { canonicalJson, sha256Hex } from "@mark1russell7/layout-contract";
 
-const K: readonly number[] = [
-  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
-  0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
-  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
-  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
-  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
-];
+export { canonicalJson, RECORD_EPS, sha256Hex } from "@mark1russell7/layout-contract";
 
-/** This function gives the bytes of a string in UTF-8. */
+/** This function gives the bytes of a string in UTF-8. The contract does not export its own `utf8`, so the core keeps this function. */
 export function utf8(text: string): Uint8Array {
   const out: number[] = [];
   for (const ch of text) {
@@ -21,75 +17,10 @@ export function utf8(text: string): Uint8Array {
   return Uint8Array.from(out);
 }
 
-/** This function gives the SHA-256 digest of a string, as 64 lowercase hex characters. It encodes the string in UTF-8. */
-export function sha256Hex(text: string): string {
-  const bytes = utf8(text);
-  const bits = bytes.length * 8;
-  const total = Math.ceil((bytes.length + 9) / 64) * 64;
-  const data = new Uint8Array(total);
-  data.set(bytes);
-  data[bytes.length] = 0x80;
-  const view = new DataView(data.buffer);
-  view.setUint32(total - 8, Math.floor(bits / 0x100000000));
-  view.setUint32(total - 4, bits >>> 0);
-  const h = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
-  const w = new Uint32Array(64);
-  const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
-  for (let off = 0; off < total; off += 64) {
-    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + 4 * i);
-    for (let i = 16; i < 64; i++) {
-      const a = w[i - 15]!;
-      const b = w[i - 2]!;
-      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
-      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
-      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
-    }
-    let [a, b, c, d, e, f, g, k] = h as [number, number, number, number, number, number, number, number];
-    for (let i = 0; i < 64; i++) {
-      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
-      const ch = (e & f) ^ (~e & g);
-      const t1 = (k + s1 + ch + K[i]! + w[i]!) >>> 0;
-      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
-      const maj = (a & b) ^ (a & c) ^ (b & c);
-      const t2 = (s0 + maj) >>> 0;
-      k = g;
-      g = f;
-      f = e;
-      e = (d + t1) >>> 0;
-      d = c;
-      c = b;
-      b = a;
-      a = (t1 + t2) >>> 0;
-    }
-    h[0] = (h[0]! + a) >>> 0;
-    h[1] = (h[1]! + b) >>> 0;
-    h[2] = (h[2]! + c) >>> 0;
-    h[3] = (h[3]! + d) >>> 0;
-    h[4] = (h[4]! + e) >>> 0;
-    h[5] = (h[5]! + f) >>> 0;
-    h[6] = (h[6]! + g) >>> 0;
-    h[7] = (h[7]! + k) >>> 0;
-  }
-  return h.map((x) => x.toString(16).padStart(8, "0")).join("");
-}
-
-/**
- * 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 function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
-  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`;
-  const o = value as Record<string, unknown>;
-  const keys = Object.keys(o)
-    .filter((k) => o[k] !== undefined)
-    .sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
-}
-
 /**
  * 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.
+ * The `documentHash` of the contract puts each number on a grid first, so it is not equal to this function. The hashes of the corpus files use this function.
  */
 export function documentHash(value: object): string {
   const { hash: _hash, ...rest } = value as { hash?: unknown };
@@ -122,7 +53,7 @@ export 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`. */
+/** This function rounds a number to 3 decimals (a step of `RECORD_EPS`), as the files of a corpus keep it. The value `-0` becomes `0`. */
 export function round3(value: number): number {
   const r = Math.round(value * 1000) / 1000;
   return r === 0 ? 0 : r;

package/src/bench/screen/index.ts

@@ -1,6 +1,12 @@
 export * from "./hash.ts";
 export * from "./forms.ts";
 export * from "./measures.ts";
+export * from "./compare.ts";
 export * from "./set.ts";
 export * from "./screen.ts";
 export * from "./generators.ts";
+export * from "./exact-set.ts";
+export * from "./gap.ts";
+export * from "./activation.ts";
+export * from "./exercise.ts";
+export * from "./portfolio-pick.ts";

package/src/bench/screen/measures.ts

@@ -1,4 +1,5 @@
 import type { Objective } from "../measures/pareto.ts";
+import type { CompareSpec, MinEffect } from "./compare.ts";
 
 /**
  * One measure of a record. `key` is the key of the measure in the values of `runSuite` and `compareStep`.
@@ -18,8 +19,55 @@ export interface MeasureInfo {
    * 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 smallest change that counts as better or worse in `compareMeasure` (WIN-RES). `MIN_EFFECTS` gives it by the unit, with its reason.
+   * A measure without this field has the threshold `RECORD_EPS`.
+   */
+  readonly minEffect?: MinEffect;
 }
 
+/** One rule of `MIN_EFFECTS`: the units, the minimum effect of a measure with one of these units, and the reason. */
+export interface MinEffectRule {
+  readonly units: readonly string[];
+  /** The minimum effect. The value `undefined` gives the threshold `RECORD_EPS`. */
+  readonly minEffect: MinEffect | undefined;
+  readonly reason: string;
+}
+
+/**
+ * The minimum effect of each measure of `MEASURES`, by the unit of the measure (WIN-RES).
+ * Each unit of `MEASURES` is in one rule. The test of the module checks it.
+ */
+export const MIN_EFFECTS: readonly MinEffectRule[] = Object.freeze([
+  {
+    units: ["0 to 1", "-1 to 1", "-0.5 to 1", "share of the gap", "0 or 1"],
+    minEffect: undefined,
+    reason: "A share or a flag of 0 or 1 has the precision of a written file. Thus the threshold is `RECORD_EPS`.",
+  },
+  {
+    units: ["ratio", "IQR over the median", "no unit", "half turns for each route", "curvature times the unit of the board"],
+    minEffect: undefined,
+    reason: "A stretch or another value without a unit has the precision of a written file. Thus the threshold is `RECORD_EPS`.",
+  },
+  {
+    units: ["count", "count for each edge", "count for each route"],
+    minEffect: 0,
+    reason: "A count or a mean of counts changes in steps. The threshold is `RECORD_EPS`, so a change of 1 counts.",
+  },
+  {
+    units: ["units", "units of the board"],
+    minEffect: { rel: 0.01 },
+    reason: "A length in pixels moves with each small move of a point. A change of 1% or less is not visible.",
+  },
+  {
+    units: ["degrees"],
+    minEffect: { rel: 0.01 },
+    reason: "An angle is a continuous value of the geometry, as a length. A change of 1% or less is not visible.",
+  },
+]);
+
+const MIN_EFFECT_BY_UNIT: ReadonlyMap<string, MinEffectRule> = new Map(MIN_EFFECTS.flatMap((r) => r.units.map((u) => [u, r] as const)));
+
 /** The text of a row of `MEASURES`: the key, the id, the name, the unit, the better side and the placement dependence. */
 type Row = readonly [key: string, id: string, name: string, unit: string, better: "lower" | "higher", placement: boolean];
 
@@ -57,6 +105,16 @@ const ROWS: readonly Row[] = [
   ["B3.median", "B3", "route.bundle.stretch.median", "ratio", "lower", false],
   ["B3.q95", "B3", "route.bundle.stretch.q95", "ratio", "lower", false],
   ["B6.max", "B6", "route.bundle.merge-angle.max", "degrees", "lower", false],
+  // MEAS2, on the inputs of `exact-v1`: the largest B3, the largest stretch of the exact model, and the gap closed (B10) to the exact optimum at the smallest cap at or above that stretch.
+  ["B3.max", "B3", "route.bundle.stretch.max", "ratio", "lower", false],
+  ["gap.stretch", "B3", "route.bundle.stretch.model.max", "ratio", "lower", false],
+  ["gap.mixed", "B10", "route.bundle.gap-closed.mixed", "0 or 1", "lower", false],
+  ["gap", "B10", "route.bundle.gap-closed", "share of the gap", "higher", false],
+  ["gap.cap", "B10", "route.bundle.gap-closed.cap", "ratio", "lower", false],
+  ["gap.collection", "B10", "route.bundle.gap-closed.collection", "share of the gap", "higher", false],
+  ["gap.cap.collection", "B10", "route.bundle.gap-closed.cap.collection", "ratio", "lower", false],
+  ["gap.all", "B10", "route.bundle.gap-closed.all", "share of the gap", "higher", false],
+  ["gap.cap.all", "B10", "route.bundle.gap-closed.cap.all", "ratio", "lower", false],
   // MEAS3A, for the steps `router` and `highway`. B5, B8 and B9 read the runs and the trunks of the result. B8 is good or bad only in context, as B2.
   ["B5.crossings", "B5", "route.bundle.lane-crossings", "count", "lower", false],
   ["B7.ratio", "B7", "route.bundle.occupied-area", "ratio", "lower", false],
@@ -123,7 +181,19 @@ const ROWS: readonly Row[] = [
  * 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 const MEASURES: readonly MeasureInfo[] = Object.freeze(ROWS.map(([key, id, name, unit, better, placementDependent]) => Object.freeze({ key, id, name, unit, better, placementDependent })));
+export const MEASURES: readonly MeasureInfo[] = Object.freeze(
+  ROWS.map(([key, id, name, unit, better, placementDependent]) => {
+    const rule = MIN_EFFECT_BY_UNIT.get(unit);
+    if (!rule) throw new Error(`MEASURES: the unit "${unit}" of ${key} has no rule in MIN_EFFECTS`);
+    const info: MeasureInfo = { key, id, name, unit, better, placementDependent };
+    return Object.freeze(rule.minEffect === undefined ? info : { ...info, minEffect: rule.minEffect });
+  }),
+);
+
+/** This function gives the spec of a compare of a measure: its better side and its minimum effect. */
+export function compareSpec(info: MeasureInfo): CompareSpec {
+  return info.minEffect === undefined ? { direction: info.better } : { direction: info.better, minEffect: info.minEffect };
+}
 
 const BY_KEY: ReadonlyMap<string, MeasureInfo> = new Map(MEASURES.map((m) => [m.key, m]));
 const BY_NAME: ReadonlyMap<string, MeasureInfo> = new Map(MEASURES.map((m) => [m.name, m]));

package/src/bench/screen/portfolio-pick.ts

@@ -0,0 +1,20 @@
+// The portfolio combinator (PORTFOLIO-API): `portfolio`, `selectBest` and `pickMoves` come from `@mark1russell7/layout-contract` 0.2.6 (PORTFOLIO-FIT).
+// The rules of the pick, the time limit and the trace are in `docs/PORTFOLIO.md` of the contract.
+export {
+  pickMoves,
+  portfolio,
+  selectBest,
+  type Member,
+  type MemberStatus,
+  type MemberTrace,
+  type PickSpec,
+  type Portfolio,
+  type PortfolioKey,
+  type PortfolioLevel,
+  type PortfolioOptions,
+  type PortfolioPick,
+  type PortfolioTrace,
+  type SelectCandidate,
+  type SelectLevel,
+  type Selection,
+} from "@mark1russell7/layout-contract";

package/src/bench/screen/screen.ts

@@ -19,6 +19,10 @@ import { measureQuality } from "../quality.ts";
 import { sameData } from "../run.ts";
 import { FRONT_OBJECTIVES } from "../suite.ts";
 import { inputGraph, jsonSafe, type LayoutInput, type LayoutPrediction, type LayoutRecord, type PredictionOp } from "./forms.ts";
+import { curvesHash, resultHash, type MoveCounter } from "./exercise.ts";
+import { outputHash } from "./activation.ts";
+import { RECORD_EPS } from "./hash.ts";
+import { formatGap, gapBaselines, gapValues, optimumKey, summarizeGap, type ExactOptimum, type GapRule, type GapSummary } from "./gap.ts";
 import { measureByName, measureName, namedObjectives } from "./measures.ts";
 import { SCREEN_V1, screenInputs, type ScreenSet } from "./set.ts";
 
@@ -98,6 +102,16 @@ export interface ScreenOptions {
   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[];
+  /**
+   * The exact optima of the inputs, from the file of the optima of a set (MEAS2). The steps `router` and `highway` read them.
+   * Each run on an input with optima gets the largest B3 and the gap closed of each rule (B10). The summary then gets the gap table.
+   */
+  readonly optima?: readonly ExactOptimum[];
+  /**
+   * This function gives the own move counts of a strategy on an input (ACTIVATION), for example `{ "move.powerEdge": 3 }`.
+   * Each record of a strategy with counts gets them as the trace measures of its step. The default is no counts.
+   */
+  readonly moves?: MoveCounter;
   /** This function gets one line of progress for each input. */
   readonly log?: (line: string) => void;
 }
@@ -154,6 +168,8 @@ export interface ScreenSummary {
   /** 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 gap closed of each strategy and rule, when the screen has optima. */
+  readonly gap?: readonly GapSummary[];
 }
 
 /** The result of `screen`: one record for each strategy and input, and the summary. */
@@ -272,6 +288,27 @@ function rowRules(step: ScreenStep, graph: Graph, row: CompareRow, again: Compar
   return { hard: { ...countRules(rules, []), "same-twice": deterministic ? 0 : 1 }, deterministic };
 }
 
+/**
+ * This function gives the output hash of a row of `compareStep` (ACTIVATION), or `undefined` for a row without output.
+ * A router hashes its result with `resultHash`. The step `group` hashes its tree and its result, and the step `curve` hashes its curves.
+ */
+function rowHash(row: CompareRow): string | undefined {
+  try {
+    return rowHashOf(row);
+  } catch (e) {
+    // An output with NaN or an infinite number has no hash. The record then has no `outputHash`, and the script `screen` names it.
+    if (!(e instanceof RangeError)) throw e;
+    return undefined;
+  }
+}
+
+/** This function gives the output hash of a row. It throws a `RangeError` for an output with a number that is not finite. */
+function rowHashOf(row: CompareRow): string | undefined {
+  if (row.step === "curve") return row.curves && row.edges ? curvesHash(row.edges, row.curves) : undefined;
+  if (row.step === "group") return row.result || row.tree ? outputHash({ tree: row.tree, result: row.result }, { grid: RECORD_EPS }) : undefined;
+  return row.result ? resultHash(row.result) : undefined;
+}
+
 /** This function adds the router `<name>+<w>` for each router of the registry and each wrapper `w`. It gives the new registry and the new names. */
 function wrapRouters(registry: Registry, wraps: readonly ScreenWrap[]): { registry: Registry; added: string[] } {
   const routers = listStrategies(registry, "router");
@@ -339,6 +376,8 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
   const comparisons: StepComparison[] = [];
   const kept = new Map<string, { graph: Graph; results: Map<string, Result> }>();
   const variants: { record: (typeof records)[number]; base: string; result: Result }[] = [];
+  const optima = givesRoutes(step) && options.optima ? new Map(options.optima.map((o) => [optimumKey(o.input, o.rule, o.cap), o])) : undefined;
+  const withOptima = new Set(options.optima?.map((o) => o.input));
 
   for (const input of inputs) {
     const graph = inputGraph(input);
@@ -352,6 +391,9 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
     let cornersRoutes: readonly Route[] | undefined;
     const cornersBase = (): readonly Route[] =>
       (cornersRoutes ??= (cmp.rows.find((r) => r.strategy === "corners" && r.result)?.result ?? asRouter(getStrategy(STRATEGIES, "router", "corners")).route(graph)).routes);
+    // The B1 of the baseline of each rule of the gap closed, for an input with optima.
+    let baselines: Record<GapRule, number> | undefined;
+    const gapBase = (): Record<GapRule, number> => (baselines ??= gapBaselines(graph));
     cmp.rows.forEach((row, i) => {
       const strategy = byName.get(row.strategy)!;
       const head = {
@@ -378,6 +420,7 @@ 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"];
+      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]);
         const f = orderFragility(graph, (g) => router.route(g), { orders: shuffles, seed, base: row.result });
@@ -388,7 +431,10 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
         const z = highwayEdits(graph, plan, own[row.strategy], edits, seed);
         Object.assign(values, { "Z10.edits.mean": z.mean, "Z10.edits.moved": z.moved, "Z10.churn": z.churn, "Z10.ids": z.ids });
       }
-      const record = { ...head, measures: named(values), hard, tolerance: { through: TOLERANCE }, deterministic, ms: row.ms, ...tail };
+      const output = rowHash(row);
+      const counts = row.result ? options.moves?.(row.strategy, graph) : undefined;
+      const facts = { ...(output === undefined ? {} : { outputHash: output }), ...(counts === undefined ? {} : { trace: [{ id: head.step, measures: { ...counts } }] }) };
+      const record = { ...head, measures: named(values), hard, tolerance: { through: TOLERANCE }, deterministic, ms: row.ms, ...tail, ...facts };
       records.push(record);
       if (givesRoutes(step) && input.base !== undefined && row.result) variants.push({ record, base: input.base, result: row.result });
     });
@@ -403,7 +449,8 @@ export function screen(step: ScreenStep, strategies: readonly (Strategy<ScreenSt
     Object.assign(v.record.measures, named({ "Z10.base.mean": s.mean, "Z10.base.max": s.max, "Z10.base.moved": s.moved }));
   }
 
-  return { records, summary: summarizeScreen(records, comparisons, { set: set.id, step, candidates, ...(options.predictions ? { predictions: options.predictions } : {}) }) };
+  const summary = summarizeScreen(records, comparisons, { set: set.id, step, candidates, ...(options.predictions ? { predictions: options.predictions } : {}) });
+  return { records, summary: optima ? { ...summary, gap: summarizeGap(records) } : summary };
 }
 
 /** This function gives the summary of the records of a screen. */
@@ -492,5 +539,6 @@ export function formatScreen(summary: ScreenSummary): string {
     for (const p of summary.predictions)
       lines.push(`| ${p.id} | ${p.strategy} | ${p.input ?? "median"} | ${p.measure} | ${p.op} ${fmt(p.expected)} | ${fmt(p.measured)} | ${p.met === undefined ? "-" : p.met ? "yes" : "no"} | ${p.reason} |`);
   }
+  if (summary.gap) lines.push(formatGap(summary.gap).trimEnd());
   return lines.join("\n") + "\n";
 }

package/src/bench/screen/set.ts

@@ -2,6 +2,7 @@ import { hubChainBoard, manyGroupsBoard, packedGridBoard } from "../../cases.ts"
 import { FIXTURES, makeFixture, type FixtureSpec } from "../../fixtures.ts";
 import type { Graph } from "../../model.ts";
 import { familySeed } from "../suite.ts";
+import { EXACT_V1, EXACT_V1_BOUNDS } from "./exact-set.ts";
 import { graphInput, type LayoutCell, type LayoutGenerator, type LayoutInput } from "./forms.ts";
 
 /** A family of boards of a screen set. The member `k` of the family has the seed `k`. */
@@ -85,8 +86,8 @@ export const SCREEN_V1: ScreenSet = {
   ],
 };
 
-/** The screen sets by id. */
-export const SCREEN_SETS: Readonly<Record<string, ScreenSet>> = { [SCREEN_V1.id]: SCREEN_V1 };
+/** The screen sets by id: `screen-v1`, the small boards with a known optimum `exact-v1` (MEAS2), and the larger boards with bounds `exact-v1-bounds` (EXACT-BOUNDS). */
+export const SCREEN_SETS: Readonly<Record<string, ScreenSet>> = { [SCREEN_V1.id]: SCREEN_V1, [EXACT_V1.id]: EXACT_V1, [EXACT_V1_BOUNDS.id]: EXACT_V1_BOUNDS };
 
 /** This function gives the id of the member `seed` of a family of a set: `<set>/<family>/s<seed>`. */
 export function inputId(set: string, family: string, seed: number): string {

package/src/highways/areas/index.ts

@@ -0,0 +1,160 @@
+import { boardUnit } from "../../bench/measures/routes.ts";
+import { dist, type Point } from "../../geom.ts";
+import { WayFinder, type WayOptions } from "../../ways.ts";
+import type { DensitySource } from "../kdeeb/index.ts";
+import type { HighwayInput, HighwayPlan } from "../model.ts";
+import { bigGroups, firstLines, nearestOnLine, shapeSkeleton, skeletonGroups, type ShapeSkeleton, type SkeletonGroups } from "../sbeb/index.ts";
+import { snapPlan, type SnapLine, type SnapMember } from "../snap.ts";
+
+/** The rule of the half width of an area: the spread of the edges of the group, or the number of its lanes. */
+export type AreaWidth = "spread" | "count";
+
+/** The values of `AreaWidth`. */
+export const AREA_WIDTHS: readonly AreaWidth[] = Object.freeze(["spread", "count"]);
+
+/** The options of the highway strategy `areas` (HWY-010 of the notes). */
+export interface AreaOptions extends Pick<WayOptions, "margin" | "k"> {
+  /** The clusterer of the groups. The default is `quickbundles`. */
+  readonly group: SkeletonGroups;
+  /** The lines of the edges that make the shape: their straight lines, or their first routes. The default is `lines`. */
+  readonly source: DensitySource;
+  /** The radius of the shape of a group, as a multiple of `boardUnit`. The default is 1.5. */
+  readonly radius: number;
+  /** The rule of the half width of the area. The default is `spread`. */
+  readonly width: AreaWidth;
+  /** The width of one lane for the rule `count`, in units of the board. The default is 4. */
+  readonly laneWidth: number;
+  /** The side of a cell of the image of the shape, in units of the board. The default is 4. */
+  readonly cell: number;
+  /** A highway has this number of edges or more. The default is 2. */
+  readonly minSize: number;
+}
+
+/** The default options of the strategy `areas`. */
+export const AREA_DEFAULTS: Readonly<Required<Omit<AreaOptions, "margin" | "k">>> = Object.freeze({
+  group: "quickbundles",
+  source: "lines",
+  radius: 1.5,
+  width: "spread",
+  laneWidth: 4,
+  cell: 4,
+  minSize: 2,
+});
+
+/**
+ * This function gives the longest path of the largest part of a skeleton, as the middles of its cells. The neighbours of a cell are its 8 neighbours.
+ * The function finds the cell farthest from a first cell, then the cell farthest from that cell. A skeleton without cells gives an empty list.
+ */
+export function skeletonPath(s: ShapeSkeleton): Point[] {
+  const { grid: g, skeleton } = s;
+  const n = g.w * g.h;
+  const part = new Int32Array(n).fill(-1);
+  const sizes: number[] = [];
+  const neighbours = (i: number): number[] => {
+    const x = i % g.w;
+    const y = (i - x) / g.w;
+    const out: number[] = [];
+    for (let dy = -1; dy <= 1; dy++)
+      for (let dx = -1; dx <= 1; dx++) {
+        if (dx === 0 && dy === 0) continue;
+        const u = x + dx;
+        const v = y + dy;
+        if (u >= 0 && v >= 0 && u < g.w && v < g.h && skeleton[v * g.w + u]) out.push(v * g.w + u);
+      }
+    return out;
+  };
+  for (let i = 0; i < n; i++) {
+    if (!skeleton[i] || part[i]! >= 0) continue;
+    const id = sizes.length;
+    let size = 0;
+    const stack = [i];
+    part[i] = id;
+    while (stack.length > 0) {
+      const c = stack.pop()!;
+      size++;
+      for (const j of neighbours(c))
+        if (part[j]! < 0) {
+          part[j] = id;
+          stack.push(j);
+        }
+    }
+    sizes.push(size);
+  }
+  if (sizes.length === 0) return [];
+  const big = sizes.indexOf(Math.max(...sizes));
+  const bfs = (from: number): { far: number; prev: Int32Array } => {
+    const prev = new Int32Array(n).fill(-2);
+    prev[from] = -1;
+    const queue = [from];
+    let far = from;
+    for (let q = 0; q < queue.length; q++) {
+      const c = queue[q]!;
+      far = c;
+      for (const j of neighbours(c))
+        if (prev[j] === -2) {
+          prev[j] = c;
+          queue.push(j);
+        }
+    }
+    return { far, prev };
+  };
+  let first = -1;
+  for (let i = 0; i < n && first < 0; i++) if (part[i] === big) first = i;
+  const a = bfs(first).far;
+  const { far: b, prev } = bfs(a);
+  const path: Point[] = [];
+  for (let c = b; c >= 0; c = prev[c]!) {
+    const x = c % g.w;
+    const y = (c - x) / g.w;
+    path.push({ x: g.x0 + (x + 0.5) * g.cell, y: g.y0 + (y + 0.5) * g.cell });
+  }
+  return path;
+}
+
+/** This function gives the value at the share `q` of the sorted list, with a linear mix between two values. An empty list gives 0. */
+function quantileOf(values: readonly number[], q: number): number {
+  if (values.length === 0) return 0;
+  const s = [...values].sort((a, b) => a - b);
+  const at = Math.max(0, Math.min(s.length - 1, q * (s.length - 1)));
+  const i = Math.floor(at);
+  const u = at - i;
+  return i + 1 < s.length ? s[i]! * (1 - u) + s[i + 1]! * u : s[i]!;
+}
+
+/**
+ * This function gives the highways of the image-based edge bundles (HWY-010, Telea and Ersoy 2010). Each group of edges is one area with one spine.
+ * The spine goes through the corner graph between the two ends of the longest path of the skeleton of the shape of the group.
+ * The area is the skeleton path with a half width. With `spread`, the half width is the 90th percentile of the distances of the points to the path.
+ * With `count`, it is the number of lanes times half of `laneWidth`. The half width is at least the margin.
+ * An edge joins the spine where its line first goes into the area. It leaves the spine where its line last comes out of the area.
+ */
+export function areaPlan(input: HighwayInput, o: Readonly<AreaOptions>): HighwayPlan {
+  const way: WayOptions = { ...(o.margin === undefined ? {} : { margin: o.margin }), ...(o.k === undefined ? {} : { k: o.k }) };
+  const finder = new WayFinder(input.graph.nodes, way);
+  const radius = Math.max(1e-3, o.radius * boardUnit(input.graph));
+  const lines = firstLines(input, finder, o.source, Math.max(4, 2 * o.cell));
+  const snapLines: SnapLine[] = [];
+  for (const g of bigGroups(skeletonGroups(input, o.group), o.minSize)) {
+    const own = g.edges.filter((m) => lines.has(m.edge));
+    if (own.length < Math.max(2, o.minSize)) continue;
+    const path = skeletonPath(shapeSkeleton(own.map((m) => lines.get(m.edge)!), finder, radius, o.cell));
+    if (path.length < 2 || dist(path[0]!, path[path.length - 1]!) <= finder.margin) continue;
+    const spread = own.flatMap((m) => lines.get(m.edge)!.map((p) => dist(p, nearestOnLine(path, p))));
+    const half = Math.max(finder.margin, o.width === "count" ? (own.length * o.laneWidth) / 2 : quantileOf(spread, 0.9));
+    const members: SnapMember[] = [];
+    for (const m of own) {
+      const l = lines.get(m.edge)!;
+      let first = -1;
+      let last = -1;
+      l.forEach((p, i) => {
+        if (dist(p, nearestOnLine(path, p)) > half) return;
+        if (first < 0) first = i;
+        last = i;
+      });
+      if (first < 0 || last <= first) continue;
+      members.push({ edge: m.edge, from: l[first]!, to: l[last]!, at: first / Math.max(1, l.length - 1) });
+    }
+    snapLines.push({ key: g.key, a: path[0]!, b: path[path.length - 1]!, members });
+  }
+  return snapPlan(input, snapLines, { ...way, minSize: o.minSize });
+}