@knowvah/dot-engine 0.1.0

package/src/cdt/splay-core.ts

@@ -0,0 +1,301 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Internal splay-tree node type and top-down splay algorithm.
+ *
+ * Ported faithfully from lib/cdt/dttree.c (Kiem-Phong Vo, 5/25/96)
+ * and lib/cdt/dthdr.h.
+ *
+ * PARTITION NAMING INVERSION (preserved from C source):
+ *   The dummy `link` node uses inverted field names:
+ *     link.right  → head of the LEFT  partition (keys < target)
+ *     link.left   → head of the RIGHT partition (keys > target)
+ *   `l` is the tail pointer into link.right (LEFT partition).
+ *   `r` is the tail pointer into link.left  (RIGHT partition).
+ *   llink(l, x): l = l.right = x   — extends LEFT  partition
+ *   rlink(r, x): r = r.left  = x   — extends RIGHT partition
+ *
+ * @see lib/cdt/dttree.c
+ * @see lib/cdt/dthdr.h
+ */
+
+import type { Comparator, KeyOf } from "./types.js";
+
+/** Internal tree node — analogous to Dtlink_t in the C source. */
+export interface SplayNode<T> {
+  left: SplayNode<T> | null; // hl._left
+  right: SplayNode<T> | null;
+  obj: T;
+}
+
+// ─── Rotation helpers (mirrors of dthdr.h macros) ────────────────────────────
+// rrotate(x, y): x.left = y.right; y.right = x
+// lrotate(x, y): x.right = y.left; y.left = x
+
+export function rrotate<T>(x: SplayNode<T>, y: SplayNode<T>): void {
+  x.left = y.right;
+  y.right = x;
+}
+
+export function lrotate<T>(x: SplayNode<T>, y: SplayNode<T>): void {
+  x.right = y.left;
+  y.left = x;
+}
+
+/**
+ * Splay minimum of `subtree` to its root via repeated RROTATE.
+ * Returns the new root (which has no left child).
+ * Mirrors the DT_FIRST loop and the DT_NEXT subtree-min logic.
+ * @see lib/cdt/dttree.c:dttree DT_FIRST / DT_NEXT
+ */
+export function splayMin<T>(subtree: SplayNode<T>): SplayNode<T> {
+  let root = subtree;
+  let t: SplayNode<T> | null;
+  while ((t = root.left) !== null) {
+    rrotate(root, t); // root.left = t.right; t.right = root
+    root = t;
+  }
+  return root;
+}
+
+/**
+ * Splay maximum of `subtree` to its root via repeated LROTATE.
+ * Returns the new root (which has no right child).
+ * Mirrors the DT_LAST loop and the DT_PREV subtree-max logic.
+ * @see lib/cdt/dttree.c:dttree DT_LAST / DT_PREV
+ */
+export function splayMax<T>(subtree: SplayNode<T>): SplayNode<T> {
+  let root = subtree;
+  let t: SplayNode<T> | null;
+  while ((t = root.right) !== null) {
+    lrotate(root, t); // root.right = t.left; t.left = root
+    root = t;
+  }
+  return root;
+}
+
+/**
+ * Insert `node` as new root by splitting `oldRoot` at the given comparison
+ * result `cmp` (compare(newKey, oldRoot.key)).
+ * `cmp` must be non-zero (caller already checked for duplicate).
+ * Returns the new root.
+ * @see lib/cdt/dttree.c:dttree DT_INSERT (not-found branch)
+ */
+export function splaySplitInsert<T>(
+  node: SplayNode<T>,
+  oldRoot: SplayNode<T>,
+  cmp: number,
+): SplayNode<T> {
+  if (cmp < 0) {
+    // new key < old root: old root becomes right child
+    node.left  = oldRoot.left;
+    node.right = oldRoot;
+    oldRoot.left = null;
+  } else {
+    // new key > old root: old root becomes left child
+    node.right = oldRoot.right;
+    node.left  = oldRoot;
+    oldRoot.right = null;
+  }
+  return node;
+}
+
+/**
+ * Integrated top-down splay + insert, faithfully mirroring CDT's
+ * `dttree.c` DT_INSERT for a Dtobag (duplicate keys allowed).
+ *
+ * This differs from `splay()` + a separate splice: CDT inserts the new node
+ * *while the tree is still partitioned* into the LEFT (keys < target) and
+ * RIGHT (keys > target) spine-trees, pushing the found equal-key node onto
+ * the head of the RIGHT partition before the new node becomes root. Splaying
+ * to reassemble a normal BST first and only then splicing produces a
+ * different equal-key sub-order — which is load-bearing for the xlabel R-tree
+ * (its Hilbert-bag drain order, and therefore the tree it builds, depends on
+ * the exact duplicate ordering; see label/xlabels.ts).
+ *
+ * The do-search loop is identical to `splay()`; only the terminal insert
+ * differs. Returns the new root (always `node`).
+ *
+ * @see lib/cdt/dttree.c:dttree DT_INSERT (do_search + DT_OBAG found/has_root)
+ */
+export function bagInsert<T, K>(
+  root: SplayNode<T>,
+  node: SplayNode<T>,
+  keyOf: KeyOf<T, K>,
+  compare: Comparator<K>,
+): SplayNode<T> {
+  const key = keyOf(node.obj);
+  // Dummy: link.right = LEFT partition head, link.left = RIGHT partition head.
+  const link: SplayNode<T> = { left: null, right: null, obj: undefined as unknown as T };
+  let l: SplayNode<T> = link; // LEFT tail  (llink: l.right = x; l = x)
+  let r: SplayNode<T> = link; // RIGHT tail (rlink: r.left  = x; r = x)
+  let cur: SplayNode<T> | null = root;
+
+  outer: while (cur !== null) {
+    const cmp = compare(key, keyOf(cur.obj));
+    if (cmp === 0) break;
+    else if (cmp < 0) {
+      const t: SplayNode<T> | null = cur.left;
+      if (t !== null) {
+        const cmp2 = compare(key, keyOf(t.obj));
+        if (cmp2 < 0) { rrotate(cur, t); r.left = t; r = t; cur = t.left; }
+        else if (cmp2 === 0) { r.left = cur; r = cur; cur = t; break outer; }
+        else { l.right = t; l = t; r.left = cur; r = cur; cur = t.right; }
+        if (cur === null) break;
+      } else { r.left = cur; r = cur; cur = null; break; }
+    } else {
+      const t: SplayNode<T> | null = cur.right;
+      if (t !== null) {
+        const cmp2 = compare(key, keyOf(t.obj));
+        if (cmp2 > 0) { lrotate(cur, t); l.right = t; l = t; cur = t.right; }
+        else if (cmp2 === 0) { l.right = cur; l = cur; cur = t; break outer; }
+        else { r.left = t; r = t; l.right = cur; l = cur; cur = t.left; }
+        if (cur === null) break;
+      } else { l.right = cur; l = cur; cur = null; break; }
+    }
+  }
+
+  if (cur !== null) {
+    // Found equal key — CDT DT_OBAG found branch: close the partition tails,
+    // push the found node onto the RIGHT partition head, then new node roots.
+    l.right = cur.left;
+    r.left = cur.right;
+    cur.left = null;
+    cur.right = link.left;
+    link.left = cur;
+  } else {
+    // Not found — close partition tails.
+    r.left = null;
+    l.right = null;
+  }
+  // has_root: new node takes the two partitions as its subtrees.
+  node.left = link.right;
+  node.right = link.left;
+  return node;
+}
+
+/**
+ * Top-down splay.
+ *
+ * Splays the node whose key equals `key` (or the closest node) to root.
+ * Returns the new root.  Always performs structural mutations.
+ *
+ * @see lib/cdt/dttree.c:dttree (do_search loop)
+ */
+export function splay<T, K>(
+  root: SplayNode<T>,
+  key: K,
+  keyOf: KeyOf<T, K>,
+  compare: Comparator<K>,
+): SplayNode<T> {
+  // Dummy node: .right = LEFT partition head, .left = RIGHT partition head
+  const link: SplayNode<T> = {
+    left: null,
+    right: null,
+    obj: undefined as unknown as T,
+  };
+
+  // l = tail of LEFT partition  (extended via l.right = llink)
+  // r = tail of RIGHT partition (extended via r.left  = rlink)
+  let l: SplayNode<T> = link;
+  let r: SplayNode<T> = link;
+  let cur: SplayNode<T> | null = root;
+
+  outer: while (cur !== null) {
+    const cmp = compare(key, keyOf(cur.obj));
+
+    if (cmp === 0) {
+      break;
+    } else if (cmp < 0) {
+      const t: SplayNode<T> | null = cur.left;
+      if (t !== null) {
+        const cmp2 = compare(key, keyOf(t.obj));
+        if (cmp2 < 0) {
+          // zig-zig right: rrotate(cur, t) then rlink(r, t)
+          rrotate(cur, t);          // cur.left = t.right; t.right = cur
+          r.left = t; r = t;        // rlink: extend RIGHT partition
+          cur = t.left;
+        } else if (cmp2 === 0) {
+          // llink(l, t) — wait, C says: rlink(r, cur); root = t
+          // From dttree.c: else if(cmp==0){ llink(l,root); root = t; break; }
+          // (when we're going left and find key at t)
+          r.left = cur; r = cur;    // rlink(r, cur)
+          cur = t;
+          break outer;
+        } else {
+          // cmp2 > 0: llink(l, t) then rlink(r, cur)
+          l.right = t; l = t;       // llink: extend LEFT partition
+          r.left = cur; r = cur;    // rlink: extend RIGHT partition
+          cur = t.right;
+        }
+        if (cur === null) break;
+      } else {
+        // no left child: rlink(r, cur)
+        r.left = cur; r = cur;
+        cur = null;
+        break;
+      }
+    } else {
+      // cmp > 0
+      const t: SplayNode<T> | null = cur.right;
+      if (t !== null) {
+        const cmp2 = compare(key, keyOf(t.obj));
+        if (cmp2 > 0) {
+          // zig-zig left: lrotate(cur, t) then llink(l, t)
+          lrotate(cur, t);          // cur.right = t.left; t.left = cur
+          l.right = t; l = t;       // llink: extend LEFT partition
+          cur = t.right;
+        } else if (cmp2 === 0) {
+          // From dttree.c: else if(cmp==0){ llink(l,root); root = t; break; }
+          l.right = cur; l = cur;   // llink(l, cur)
+          cur = t;
+          break outer;
+        } else {
+          // cmp2 < 0: rlink(r, t) then llink(l, cur)
+          r.left = t; r = t;        // rlink: extend RIGHT partition
+          l.right = cur; l = cur;   // llink: extend LEFT partition
+          cur = t.left;
+        }
+        if (cur === null) break;
+      } else {
+        // no right child: llink(l, cur)
+        l.right = cur; l = cur;
+        cur = null;
+        break;
+      }
+    }
+  }
+
+  // Reassemble tree
+  if (cur !== null) {
+    // Found: close partitions, reattach
+    l.right = cur.left;
+    r.left  = cur.right;
+    cur.left  = link.right; // LEFT  partition → left subtree
+    cur.right = link.left;  // RIGHT partition → right subtree
+    return cur;
+  }
+
+  // Not found: close partition tails, merge via rightmost-of-left
+  r.left  = null;
+  l.right = null;
+
+  const leftPart  = link.right;
+  const rightPart = link.left;
+
+  // After the search fails, each partition is a right/left-spine chain
+  // whose HEAD is the first (largest/smallest) node added. We must splay
+  // the true predecessor/successor to root so that splaySplitInsert can
+  // split at a node adjacent to the missing key.
+  //
+  // leftPart chain: connected via .right (largest-first chain, head is
+  //   largest key < target).  splayMax(leftPart) brings true predecessor
+  //   to root.
+  // rightPart chain: connected via .left (smallest-last chain, tail is
+  //   smallest key > target = true successor).  splayMin(rightPart)
+  //   brings true successor to root.
+  if (leftPart === null)  return splayMin(rightPart!);
+  const maxLeft = splayMax(leftPart);
+  if (rightPart === null) return maxLeft;
+  maxLeft.right = rightPart;
+  return maxLeft;
+}

package/src/cdt/splay.ts

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * DtSplay — ordered set (DT_OSET) backed by a top-down splay tree.
+ *
+ * Iteration order: ascending by comparator (same as DT_OSET in the C source).
+ * Every operation is a structural mutation (splay rotation) — intentional.
+ *
+ * @see lib/cdt/dttree.c
+ */
+
+import type { Comparator, KeyOf } from "./types.js";
+import {
+  lrotate,
+  rrotate,
+  splay,
+  splayMax,
+  splayMin,
+  splaySplitInsert,
+} from "./splay-core.js";
+import type { SplayNode } from "./splay-core.js";
+
+export class DtSplay<T, K = T> {
+  /** Current root — analogous to dt->data.here in the C source. */
+  private _root: SplayNode<T> | null = null;
+  private _size = 0;
+  private readonly _keyOf: KeyOf<T, K>;
+  private readonly _compare: Comparator<K>;
+
+  constructor(keyOf: KeyOf<T, K>, compare: Comparator<K>) {
+    this._keyOf = keyOf;
+    this._compare = compare;
+  }
+
+  /** @see lib/cdt/dtsize.c:dtsize */
+  size(): number { return this._size; }
+
+  /**
+   * Insert obj.  If the key already exists returns the existing object
+   * unchanged (DT_OSET: no duplicates).
+   * @see lib/cdt/dttree.c:dttree DT_INSERT
+   */
+  insert(obj: T): T {
+    if (this._root === null) {
+      this._root = { left: null, right: null, obj };
+      this._size++;
+      return obj;
+    }
+
+    const key = this._keyOf(obj);
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    const cmp = this._compare(key, this._keyOf(this._root.obj));
+
+    if (cmp === 0) return this._root.obj; // DT_OSET: return existing
+
+    const node: SplayNode<T> = { left: null, right: null, obj };
+    this._root = splaySplitInsert(node, this._root, cmp);
+    this._size++;
+    return obj;
+  }
+
+  /**
+   * Delete obj by key.  Returns true if found and removed.
+   * @see lib/cdt/dttree.c:dttree DT_DELETE
+   */
+  delete(obj: T): boolean {
+    if (this._root === null) return false;
+
+    const key = this._keyOf(obj);
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    if (this._compare(key, this._keyOf(this._root.obj)) !== 0) return false;
+
+    const left  = this._root.left;
+    const right = this._root.right;
+    if (left === null) {
+      this._root = right;
+    } else {
+      const maxLeft = splayMax(left);
+      maxLeft.right = right;
+      this._root = maxLeft;
+    }
+
+    this._size--;
+    return true;
+  }
+
+  /**
+   * Search by key.  Splays found node to root.
+   * @see lib/cdt/dttree.c:dttree DT_SEARCH
+   */
+  search(key: K): T | undefined {
+    if (this._root === null) return undefined;
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    return this._compare(key, this._keyOf(this._root.obj)) === 0
+      ? this._root.obj : undefined;
+  }
+
+  /**
+   * Return the minimum element; splays it to root.
+   * @see lib/cdt/dttree.c:dttree DT_FIRST
+   */
+  first(): T | undefined {
+    if (this._root === null) return undefined;
+    this._root = splayMin(this._root);
+    return this._root.obj;
+  }
+
+  /**
+   * Return the in-order successor of obj.
+   * @see lib/cdt/dttree.c:dttree DT_NEXT
+   */
+  next(obj: T): T | undefined {
+    if (this._root === null) return undefined;
+
+    const key = this._keyOf(obj);
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    const cmp = this._compare(key, this._keyOf(this._root.obj));
+
+    // When no exact match and key < root.key, root IS the successor.
+    if (cmp < 0) return this._root.obj;
+
+    const right = this._root.right;
+    if (right === null) return undefined;
+
+    // Splay min of right subtree, attach old root as its left child.
+    const minNode = splayMin(right);
+    this._root.right = null;
+    minNode.left = this._root;
+    this._root = minNode;
+    return minNode.obj;
+  }
+
+  /**
+   * Return the maximum element; splays it to root.
+   * @see lib/cdt/dttree.c:dttree DT_LAST
+   */
+  last(): T | undefined {
+    if (this._root === null) return undefined;
+    this._root = splayMax(this._root);
+    return this._root.obj;
+  }
+
+  /**
+   * Return the in-order predecessor of obj.
+   * @see lib/cdt/dttree.c:dttree DT_PREV
+   */
+  prev(obj: T): T | undefined {
+    if (this._root === null) return undefined;
+
+    const key = this._keyOf(obj);
+    this._root = splay(this._root, key, this._keyOf, this._compare);
+    const cmp = this._compare(key, this._keyOf(this._root.obj));
+
+    // When no exact match and key > root.key, root IS the predecessor.
+    if (cmp > 0) return this._root.obj;
+
+    const left = this._root.left;
+    if (left === null) return undefined;
+
+    // Splay max of left subtree, attach old root as its right child.
+    const maxNode = splayMax(left);
+    this._root.left = null;
+    maxNode.right = this._root;
+    this._root = maxNode;
+    return maxNode.obj;
+  }
+
+  /** Remove all elements. @see lib/cdt/dttree.c:dttree DT_CLEAR */
+  clear(): void {
+    this._root = null;
+    this._size = 0;
+  }
+
+  /**
+   * Iterate in ascending comparator order via first() / next().
+   * Each step is a structural mutation per C DT_OSET spec.
+   */
+  [Symbol.iterator](): Iterator<T> {
+    let current: T | undefined = this.first();
+    const self = this;
+    return {
+      next(): IteratorResult<T> {
+        if (current === undefined) {
+          return { value: undefined as unknown as T, done: true };
+        }
+        const value = current;
+        current = self.next(value);
+        return { value, done: false };
+      },
+    };
+  }
+}

package/src/cdt/strhash.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * dtStrHash — polynomial rolling hash for null-terminated strings.
+ *
+ * Exact port of dtstrhash() from lib/cdt/dtstrhash.c (Kiem-Phong Vo, 02/28/03).
+ *
+ * Algorithm (n <= 0 / string mode):
+ *   Advance 2 bytes per step; if the second byte is \0, advance only 1.
+ *   h = (h + (s[0] << 8) + s[1]) * DT_PRIME  at each step.
+ *   Add string length at the end: (h + n) * DT_PRIME.
+ *
+ * The unusual 2-byte stepping with the \0 guard is a micro-optimisation in
+ * the original C and must be preserved exactly to produce matching hash values.
+ *
+ * @see lib/cdt/dtstrhash.c:dtstrhash
+ */
+
+/** 2#00000001 00000101 00010011 00110011 @see dtstrhash.c:DT_PRIME */
+const DT_PRIME = 17109811;
+
+/** Unsigned 32-bit multiply — mirrors C `unsigned` wrap-around. */
+function umul32(a: number, b: number): number {
+  // Use Math.imul for correct 32-bit integer multiply, then force unsigned.
+  return Math.imul(a, b) >>> 0;
+}
+
+/**
+ * Hash a JavaScript string using the dtstrhash algorithm (n <= 0 / string mode).
+ *
+ * TypeScript strings are UTF-16; we operate on char codes directly to match
+ * the C behaviour of treating each character as one byte (ASCII / Latin-1).
+ * Callers using non-ASCII keys must ensure their comparator is consistent.
+ *
+ * @see lib/cdt/dtstrhash.c:dtstrhash
+ */
+export function dtStrHash(s: string): number {
+  let h = 0;
+  let i = 0;
+  const len = s.length;
+
+  // for(; *s != 0; s += s[1] ? 2 : 1)
+  //   h = (h + ((unsigned)s[0] << 8u) + (unsigned)s[1]) * DT_PRIME;
+  while (i < len) {
+    const b0 = s.charCodeAt(i) & 0xff;
+    const b1 = (i + 1 < len) ? (s.charCodeAt(i + 1) & 0xff) : 0;
+    h = umul32((h + (b0 << 8) + b1) >>> 0, DT_PRIME);
+    i += b1 !== 0 ? 2 : 1;
+  }
+
+  // return (h + (unsigned)n) * DT_PRIME
+  return umul32((h + len) >>> 0, DT_PRIME);
+}

package/src/cdt/types.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Shared type definitions for lib/cdt.
+ * Kept in a leaf module to avoid circular imports.
+ *
+ * @see lib/cdt/cdt.h
+ */
+
+/** Key comparator: returns negative, zero, or positive. @see Dtcompar_f */
+export type Comparator<K> = (a: K, b: K) => number;
+
+/** Extract the key from an object. @see Dtdisc_t */
+export type KeyOf<T, K> = (obj: T) => K;

package/src/common/arith.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Arithmetic primitives shared with the C reference build.
+ *
+ * @see lib/common/arith.h
+ */
+
+/**
+ * C rounding: round half **away from zero**.
+ *
+ * This is the single shared implementation of the one rounding deviation that
+ * separates this port from C. Both C spellings agree on it:
+ *
+ * - libm `round()` — "rounding halfway cases away from zero" (C99 7.12.9.6),
+ *   used directly across `lib/` (e.g. `lib/dotgen/compound.c:41`,
+ *   `lib/pack/pack.c:435`, `lib/dotgen/position.c:966`).
+ * - the `ROUND` macro — `((f>=0)?(int)(f + .5):(int)(f - .5))`
+ *   (`lib/common/arith.h:48`), whose truncating casts also break ties away
+ *   from zero. `POINTS(a_inches)` (`lib/common/geom.h:62`) is `ROUND` too.
+ *
+ * JavaScript's `Math.round` breaks ties toward +∞ (`Math.round(-4.5) === -4`,
+ * C `round(-4.5) === -5`), so it diverges by 1 on **every exact negative
+ * half-integer**. Layout coordinates are routinely negative (center-origin
+ * engines, cluster walls left of an endpoint, port offsets from a node centre)
+ * and are often exact integers or halves, so such ties are ordinary, not
+ * exotic.
+ *
+ * Use this for every site that mirrors a C `round()`/`ROUND()`/`POINTS()`,
+ * including sites whose argument happens to be non-negative today — it costs
+ * nothing and states the intent. Do **not** use it where C rounds by some
+ * other rule (`(int)` truncation, `floor`, printf `%.0f` banker's rounding).
+ *
+ * @see lib/common/arith.h:48 (ROUND)
+ * @see C99 7.12.9.6 (round)
+ */
+export function cround(v: number): number {
+  return v >= 0 ? Math.floor(v + 0.5) : Math.ceil(v - 0.5);
+}