@statelyai/layout 0.2.0 → 0.3.0

package/src/routing/search.ts

@@ -0,0 +1,276 @@
+import { crossesRect } from "../authoring/routing";
+import { distance } from "./path";
+import { inflate, union } from "./spatial";
+import type { RouteBounds, RoutePoint } from "./types";
+
+export interface SearchContext {
+  obstacles(bounds: RouteBounds): readonly RouteBounds[];
+  edgeCost?(a: RoutePoint, b: RoutePoint): number;
+  guides?(bounds: RouteBounds): readonly RouteBounds[];
+  readonly maxSearchNodes: number;
+  readonly bendPenalty: number;
+  visited: number;
+  budgetExceeded: boolean;
+}
+export const segmentBounds = (a: RoutePoint, b: RoutePoint): RouteBounds => ({
+  x: Math.min(a.x, b.x),
+  y: Math.min(a.y, b.y),
+  width: Math.abs(b.x - a.x),
+  height: Math.abs(b.y - a.y),
+});
+export function clear(a: RoutePoint, b: RoutePoint, context: SearchContext): boolean {
+  return !context.obstacles(segmentBounds(a, b)).some((r) => crossesRect(a, b, r));
+}
+export function simplify(points: readonly RoutePoint[]): RoutePoint[] {
+  const result: RoutePoint[] = [];
+  for (const p of points) {
+    if (result.length && distance(result.at(-1)!, p) < 1e-9) continue;
+    while (result.length > 1) {
+      const a = result.at(-2)!,
+        b = result.at(-1)!;
+      if (
+        Math.abs((b.x - a.x) * (p.y - b.y) - (b.y - a.y) * (p.x - b.x)) > 1e-8 ||
+        (b.x - a.x) * (p.x - b.x) + (b.y - a.y) * (p.y - b.y) < 0
+      )
+        break;
+      result.pop();
+    }
+    result.push(p);
+  }
+  return result;
+}
+class Queue<T> {
+  items: { value: T; priority: number }[] = [];
+  push(value: T, priority: number) {
+    const item = { value, priority };
+    let i = this.items.length;
+    this.items.push(item);
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (this.items[p]!.priority <= priority) break;
+      this.items[i] = this.items[p]!;
+      i = p;
+    }
+    this.items[i] = item;
+  }
+  pop(): T {
+    const first = this.items[0]!,
+      last = this.items.pop()!;
+    if (this.items.length) {
+      let i = 0;
+      while (i * 2 + 1 < this.items.length) {
+        let child = i * 2 + 1;
+        if (
+          child + 1 < this.items.length &&
+          this.items[child + 1]!.priority < this.items[child]!.priority
+        )
+          child++;
+        if (last.priority <= this.items[child]!.priority) break;
+        this.items[i] = this.items[child]!;
+        i = child;
+      }
+      this.items[i] = last;
+    }
+    return first.value;
+  }
+}
+/** Visibility graph + A*, with incoming direction in the state for bend costs. */
+export function findPath(
+  start: RoutePoint,
+  end: RoutePoint,
+  style: "orthogonal" | "polyline" | "octilinear",
+  context: SearchContext,
+  terminals: { incoming?: RoutePoint; outgoing?: RoutePoint } = {},
+): RoutePoint[] | undefined {
+  const turnCost = (a: RoutePoint | undefined, b: RoutePoint | undefined) => {
+    if (!a || !b || !Math.hypot(a.x, a.y) || !Math.hypot(b.x, b.y)) return 0;
+    const dot = a.x * b.x + a.y * b.y,
+      cross = a.x * b.y - a.y * b.x;
+    return dot < -1e-8 ? context.bendPenalty * 4 : Math.abs(cross) > 1e-8 ? context.bendPenalty : 0;
+  };
+  const delta = (a: RoutePoint, b: RoutePoint) => ({ x: b.x - a.x, y: b.y - a.y });
+  const attachmentCost = (points: RoutePoint[]) =>
+    turnCost(terminals.incoming, delta(points[0]!, points[1]!)) +
+    turnCost(delta(points.at(-2)!, points.at(-1)!), terminals.outgoing);
+  const aligned = start.x === end.x || start.y === end.y;
+  if (
+    (style === "polyline" ||
+      aligned ||
+      (style === "octilinear" && Math.abs(start.x - end.x) === Math.abs(start.y - end.y))) &&
+    clear(start, end, context) &&
+    attachmentCost([start, end]) === 0 &&
+    (context.edgeCost?.(start, end) ?? 0) === 0
+  )
+    return [start, end];
+  if (style === "orthogonal") {
+    const candidates = [
+      { x: start.x, y: end.y },
+      { x: end.x, y: start.y },
+    ]
+      .filter((bend) => clear(start, bend, context) && clear(bend, end, context))
+      .map((bend) => simplify([start, bend, end]));
+    candidates.sort((a, b) => attachmentCost(a) - attachmentCost(b));
+    if (
+      candidates.length &&
+      attachmentCost(candidates[0]!) === 0 &&
+      candidates[0]!
+        .slice(1)
+        .every((p, i) => (context.edgeCost?.(candidates[0]![i]!, p) ?? 0) === 0)
+    )
+      return candidates[0];
+  }
+  for (let attempt = 0; attempt < 5 && context.visited < context.maxSearchNodes; attempt++) {
+    const area = inflate(segmentBounds(start, end), 32 * 2 ** attempt);
+    const guides = context.guides?.(area) ?? [];
+    const obstacles = context.obstacles(guides.reduce(union, area));
+    const corners = [...obstacles, ...guides].flatMap((r) => [
+      { x: r.x, y: r.y },
+      { x: r.x + r.width, y: r.y },
+      { x: r.x, y: r.y + r.height },
+      { x: r.x + r.width, y: r.y + r.height },
+    ]);
+    let points: RoutePoint[], neighbors: (i: number) => number[];
+    if (style === "polyline") {
+      points = [start, end, ...corners];
+      neighbors = () => points.map((_, i) => i);
+    } else {
+      const xs = [
+        ...new Set([start.x, end.x, area.x, area.x + area.width, ...corners.map((p) => p.x)]),
+      ].sort((a, b) => a - b);
+      const ys = [
+        ...new Set([start.y, end.y, area.y, area.y + area.height, ...corners.map((p) => p.y)]),
+      ].sort((a, b) => a - b);
+      if (xs.length * ys.length > context.maxSearchNodes) {
+        context.budgetExceeded = true;
+        return undefined;
+      }
+      points = ys.flatMap((y) => xs.map((x) => ({ x, y })));
+      const width = xs.length;
+      if (style === "octilinear") {
+        // Add intersections between endpoint/corner diagonals and grid lines.
+        const extra: RoutePoint[] = [];
+        for (const p of [start, end, ...corners])
+          for (const x of xs)
+            for (const sign of [-1, 1]) {
+              const y = p.y + sign * (x - p.x);
+              if (y >= area.y && y <= area.y + area.height) extra.push({ x, y });
+            }
+        for (const p of [start, end, ...corners])
+          for (const y of ys)
+            for (const sign of [-1, 1]) {
+              const x = p.x + sign * (y - p.y);
+              if (x >= area.x && x <= area.x + area.width) extra.push({ x, y });
+            }
+        const unique = new Map(points.map((p) => [`${p.x}:${p.y}`, p]));
+        for (const p of extra) unique.set(`${p.x}:${p.y}`, p);
+        points = [...unique.values()];
+        if (points.length > context.maxSearchNodes) {
+          context.budgetExceeded = true;
+          return undefined;
+        }
+        const groups = new Map<string, number[]>();
+        const keys = (p: RoutePoint) => [
+          `x:${p.x}`,
+          `y:${p.y}`,
+          `a:${(p.x - p.y).toFixed(8)}`,
+          `b:${(p.x + p.y).toFixed(8)}`,
+        ];
+        points.forEach((p, i) => {
+          for (const key of keys(p)) {
+            const list = groups.get(key) ?? [];
+            list.push(i);
+            groups.set(key, list);
+          }
+        });
+        const adjacent = points.map(() => new Set<number>());
+        for (const ids of groups.values()) {
+          ids.sort((a, b) => points[a]!.x - points[b]!.x || points[a]!.y - points[b]!.y);
+          for (let i = 1; i < ids.length; i++) {
+            adjacent[ids[i - 1]!]!.add(ids[i]!);
+            adjacent[ids[i]!]!.add(ids[i - 1]!);
+          }
+        }
+        neighbors = (i) => [...adjacent[i]!];
+      } else
+        neighbors = (i) =>
+          [
+            i % width ? i - 1 : -1,
+            i % width < width - 1 ? i + 1 : -1,
+            i >= width ? i - width : -1,
+            i + width < points.length ? i + width : -1,
+          ].filter((v) => v >= 0);
+    }
+    if (points.length > context.maxSearchNodes) {
+      context.budgetExceeded = true;
+      return undefined;
+    }
+    const from = points.findIndex((p) => distance(p, start) < 1e-8),
+      to = points.findIndex((p) => distance(p, end) < 1e-8);
+    const queue = new Queue<{ index: number; previous: number; key: string; cost: number }>();
+    const costs = new Map<string, number>(),
+      parents = new Map<string, string>(),
+      vertices = new Map<string, number>(),
+      visibility = new Map<number, boolean>(),
+      edgeCosts = new Map<number, number>();
+    const visible = (a: number, b: number) => {
+      const key = a < b ? a * points.length + b : b * points.length + a;
+      let result = visibility.get(key);
+      if (result === undefined) {
+        result = clear(points[a]!, points[b]!, context);
+        visibility.set(key, result);
+      }
+      return result;
+    };
+    const first = `${from}:-1`;
+    costs.set(first, 0);
+    vertices.set(first, from);
+    queue.push({ index: from, previous: -1, key: first, cost: 0 }, distance(start, end));
+    while (queue.items.length && context.visited < context.maxSearchNodes) {
+      const current = queue.pop();
+      if (costs.get(current.key) !== current.cost) continue;
+      context.visited++;
+      if (current.index === to) {
+        const result: RoutePoint[] = [];
+        let key: string | undefined = current.key;
+        while (key !== undefined) {
+          result.push(points[vertices.get(key)!]!);
+          key = parents.get(key);
+        }
+        return simplify(result.reverse());
+      }
+      const a = points[current.index]!;
+      for (const next of neighbors(current.index)) {
+        if (next === current.index || next === current.previous) continue;
+        const b = points[next]!;
+        if (!visible(current.index, next)) continue;
+        const before =
+          current.previous < 0 ? terminals.incoming : delta(points[current.previous]!, a);
+        const step = delta(a, b);
+        const bend =
+          turnCost(before, step) + (next === to ? turnCost(step, terminals.outgoing) : 0);
+        const pair = Math.min(current.index, next) * points.length + Math.max(current.index, next);
+        let edgeCost = edgeCosts.get(pair);
+        if (edgeCost === undefined) {
+          edgeCost = context.edgeCost?.(a, b) ?? 0;
+          edgeCosts.set(pair, edgeCost);
+        }
+        const cost = current.cost + distance(a, b) + bend + edgeCost;
+        const key = `${next}:${current.index}`;
+        if (cost >= (costs.get(key) ?? Infinity)) continue;
+        costs.set(key, cost);
+        parents.set(key, current.key);
+        vertices.set(key, next);
+        queue.push({ index: next, previous: current.index, key, cost }, cost + distance(b, end));
+      }
+    }
+  }
+  if (context.visited >= context.maxSearchNodes) context.budgetExceeded = true;
+  return undefined;
+}
+export function pointsBounds(points: readonly RoutePoint[]): RouteBounds {
+  return points.slice(1).reduce<RouteBounds>((r, p) => union(r, { ...p, width: 0, height: 0 }), {
+    ...points[0]!,
+    width: 0,
+    height: 0,
+  });
+}

package/src/routing/spatial.ts

@@ -0,0 +1,78 @@
+import { PersistentMap } from "./persistent";
+import type { RouteBounds } from "./types";
+export const intersects = (a: RouteBounds, b: RouteBounds): boolean =>
+  a.x <= b.x + b.width && a.x + a.width >= b.x && a.y <= b.y + b.height && a.y + a.height >= b.y;
+export const inflate = (r: RouteBounds, amount: number): RouteBounds => ({
+  x: r.x - amount,
+  y: r.y - amount,
+  width: r.width + amount * 2,
+  height: r.height + amount * 2,
+});
+export function union(a: RouteBounds, b: RouteBounds): RouteBounds {
+  const x = Math.min(a.x, b.x),
+    y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y,
+  };
+}
+function cells(r: RouteBounds): string[] | undefined {
+  const x1 = Math.floor(r.x / 128),
+    x2 = Math.floor((r.x + r.width) / 128),
+    y1 = Math.floor(r.y / 128),
+    y2 = Math.floor((r.y + r.height) / 128);
+  if ((x2 - x1 + 1) * (y2 - y1 + 1) > 4096) return undefined;
+  const result: string[] = [];
+  for (let x = 0; x <= x2 - x1; x++)
+    for (let y = 0; y <= y2 - y1; y++) result.push(`${x1 + x}:${y1 + y}`);
+  return result;
+}
+/** Persistent uniform-grid broad phase; oversized rectangles live in an overflow index. */
+export class SpatialIndex {
+  constructor(
+    readonly bounds = new PersistentMap<RouteBounds>(),
+    private readonly buckets = new PersistentMap<PersistentMap<true>>(),
+    private readonly overflow = new PersistentMap<true>(),
+  ) {
+    Object.freeze(this);
+  }
+  set(id: string, rect?: RouteBounds): SpatialIndex {
+    let { bounds, buckets, overflow } = this;
+    const previous = bounds.get(id);
+    if (previous) {
+      const keys = cells(previous);
+      if (!keys) overflow = overflow.delete(id);
+      else
+        for (const key of keys) {
+          const bucket = buckets.get(key)!.delete(id);
+          buckets = bucket.size ? buckets.set(key, bucket) : buckets.delete(key);
+        }
+      bounds = bounds.delete(id);
+    }
+    if (rect) {
+      const keys = cells(rect);
+      if (!keys) overflow = overflow.set(id, true);
+      else
+        for (const key of keys)
+          buckets = buckets.set(key, (buckets.get(key) ?? new PersistentMap<true>()).set(id, true));
+      bounds = bounds.set(id, rect);
+    }
+    return new SpatialIndex(bounds, buckets, overflow);
+  }
+  query(rect: RouteBounds): string[] {
+    const keys = cells(rect),
+      found = new Set<string>();
+    if (!keys) {
+      for (const [id, bounds] of this.bounds) if (intersects(rect, bounds)) found.add(id);
+    } else {
+      for (const key of keys)
+        for (const id of this.buckets.get(key)?.keys() ?? [])
+          if (intersects(rect, this.bounds.get(id)!)) found.add(id);
+      for (const id of this.overflow.keys())
+        if (intersects(rect, this.bounds.get(id)!)) found.add(id);
+    }
+    return [...found].sort();
+  }
+}

package/src/routing/types.ts

@@ -0,0 +1,146 @@
+import type { EntityRect, Graph, GraphDiff, Point } from "@statelyai/graph";
+
+export type RoutePoint = Readonly<Point>;
+export type RouteSegment =
+  | { readonly kind: "line"; readonly to: RoutePoint }
+  | { readonly kind: "quadratic"; readonly control: RoutePoint; readonly to: RoutePoint }
+  | {
+      readonly kind: "cubic";
+      readonly control1: RoutePoint;
+      readonly control2: RoutePoint;
+      readonly to: RoutePoint;
+    }
+  | {
+      readonly kind: "arc";
+      readonly rx: number;
+      readonly ry: number;
+      readonly rotation: number;
+      readonly largeArc: boolean;
+      readonly sweep: boolean;
+      readonly to: RoutePoint;
+    };
+export interface RoutePath {
+  readonly start: RoutePoint;
+  readonly segments: readonly RouteSegment[];
+}
+export type RouteEndpoint =
+  | { readonly kind: "node"; readonly nodeId: string; readonly port?: string }
+  | { readonly kind: "label"; readonly edgeId: string }
+  | { readonly kind: "junction"; readonly id: string };
+export interface RouteSection {
+  readonly id: string;
+  readonly from: RouteEndpoint;
+  readonly to: RouteEndpoint;
+  readonly path: RoutePath;
+  /** Same ID denotes a shared trunk; render it once. */
+  readonly sharedId?: string;
+}
+export type RoutingDiagnosticCode =
+  | "MISSING_GEOMETRY"
+  | "MISSING_PORT"
+  | "ROUTE_CONFLICT"
+  | "ROUTE_BLOCKED"
+  | "SEARCH_BUDGET"
+  | "CONSTRAINT_VIOLATION";
+export interface RoutingDiagnostic {
+  readonly code: RoutingDiagnosticCode;
+  readonly edgeId: string;
+  readonly message: string;
+}
+export interface Route {
+  readonly edgeId: string;
+  readonly sections: readonly RouteSection[];
+  readonly status: "routed" | "fallback";
+  readonly diagnostics: readonly RoutingDiagnostic[];
+}
+export type RoutePatch =
+  | { readonly op: "set"; readonly edgeId: string; readonly route: Route }
+  | { readonly op: "delete"; readonly edgeId: string };
+export type RouteStyle =
+  | "straight"
+  | "bezier"
+  | "orthogonal"
+  | "polyline"
+  | "octilinear"
+  | "curved"
+  | "organic"
+  | "parallel"
+  | "self-loop"
+  | "fan"
+  | "bus"
+  | "bundle";
+export type RouteSide = "left" | "right" | "top" | "bottom";
+export interface RouteAttachment {
+  /** Node-local attachment rectangle, independent of its outer obstacle bounds. */
+  readonly bounds: RouteBounds;
+  readonly facing?: "inward" | "outward";
+}
+export interface EdgeRoutingSettings {
+  readonly sourceAttachment?: RouteAttachment;
+  readonly targetAttachment?: RouteAttachment;
+  readonly sourceSide?: RouteSide;
+  readonly targetSide?: RouteSide;
+  readonly waypoints?: readonly RoutePoint[];
+  /** Explicit shared routing group. Native binary edges describe branches of a net. */
+  readonly group?: string;
+}
+export interface RoutingSettings {
+  /** Native compound geometry is parent-relative; adapters may supply resolved world geometry. */
+  readonly coordinateSpace?: "parent" | "world";
+  readonly clearance?: number;
+  readonly radius?: number;
+  readonly edgeSpacing?: number;
+  readonly bendPenalty?: number;
+  /** Soft cost per crossing; finite costs keep detours proportionate. Default 80. */
+  readonly crossingPenalty?: number;
+  /** Cost per unit of parallel overlap within edgeSpacing. Default 8. */
+  readonly overlapPenalty?: number;
+  readonly maxSearchNodes?: number;
+  readonly organicIterations?: number;
+  readonly edges?: Readonly<Record<string, EdgeRoutingSettings>>;
+}
+export interface RoutingMetrics {
+  readonly routedEdges: number;
+  readonly reusedEdges: number;
+  readonly affectedEdges: number;
+  readonly searchNodes: number;
+  readonly obstacleCandidates: number;
+}
+/** Immutable value. Retain it per canvas; the private state uses structural sharing. */
+export interface RoutingSnapshot {
+  readonly strategy: string;
+  readonly revision: number;
+  readonly routes: ReadonlyMap<string, Route>;
+  readonly metrics: RoutingMetrics;
+}
+export interface RoutingUpdate {
+  readonly snapshot: RoutingSnapshot;
+  readonly patches: readonly RoutePatch[];
+  /** Compare identity before accepting an asynchronous result. */
+  readonly base: RoutingSnapshot;
+}
+export type RoutingGraph = Graph<unknown, unknown, unknown, unknown>;
+export interface RoutingStrategy {
+  readonly id: string;
+  route(
+    graph: RoutingGraph,
+    settings?: RoutingSettings,
+  ): RoutingSnapshot | Promise<RoutingSnapshot>;
+  update(
+    graph: RoutingGraph,
+    previous: RoutingSnapshot,
+    diff: GraphDiff<unknown, unknown>,
+    settings?: RoutingSettings,
+  ): RoutingUpdate | Promise<RoutingUpdate>;
+}
+export interface NativeRoutingStrategy extends RoutingStrategy {
+  readonly id: RouteStyle;
+  route(graph: RoutingGraph, settings?: RoutingSettings): RoutingSnapshot;
+  update(
+    graph: RoutingGraph,
+    previous: RoutingSnapshot,
+    diff: GraphDiff<unknown, unknown>,
+    settings?: RoutingSettings,
+  ): RoutingUpdate;
+}
+export type RouteBounds = Readonly<EntityRect>;