@knowvah/dot-engine 0.1.0

package/dist/util/agxbuf.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @see lib/util/agxbuf.h
+ * @see lib/util/agxbuf.c (agxbuf_trim_zeros)
+ *
+ * Dynamically expanding string buffer. SSO threshold need not be
+ * replicated — only the observable contract matters.
+ */
+/**
+ * Extensible string buffer, analogous to C's agxbuf.
+ *
+ * @see cgraph/agxbuf.h:agxbuf
+ */
+export declare class AgBuffer {
+    private _data;
+    /** @see cgraph/agxbuf.h:agxbput */
+    append(s: string): this;
+    /** @see cgraph/agxbuf.h:agxbputc */
+    appendChar(c: string): this;
+    /**
+     * Append first n characters of s.
+     * @see cgraph/agxbuf.h:agxbput_n
+     */
+    appendN(s: string, n: number): this;
+    /** @see cgraph/agxbuf.h:agxbclear */
+    clear(): void;
+    /**
+     * Matches agxbuse semantics: resets the buffer and returns the content.
+     * The returned string is valid only until the next write.
+     * @see cgraph/agxbuf.h:agxbuse
+     */
+    str(): string;
+    /**
+     * Caller takes ownership; buffer is reset.
+     * @see cgraph/agxbuf.h:agxbdisown
+     */
+    disown(): string;
+    /** @see cgraph/agxbuf.h:agxblen */
+    length(): number;
+    /**
+     * Removes and returns the last character (UTF-16 charCodeAt semantics
+     * matching C char-pop), or null if empty.
+     * @see cgraph/agxbuf.h:agxbpop
+     */
+    pop(): string | null;
+    /**
+     * Trim trailing fractional zeros from a printed floating-point value.
+     *
+     * Examples:
+     *   "42.00" → "42"
+     *   "42.01" → "42.01"
+     *   "42.10" → "42.1"
+     *   "-0.0"  → "0"
+     *
+     * @see cgraph/agxbuf.h:agxbuf_trim_zeros
+     */
+    trimZeros(): void;
+    /** Return index of last '.' in _data, or -1 if none. */
+    private _lastPeriodIndex;
+    /**
+     * Walk backwards from end; trim trailing '0' digits then the '.' if all
+     * fractional digits were zero. Returns the trimmed string, or null when
+     * no trimming is needed.
+     * @see cgraph/agxbuf.h:agxbuf_trim_zeros (truncate loop)
+     */
+    private _trimFractional;
+    /**
+     * Replace trailing "-0" with "0".
+     * @see cgraph/agxbuf.h:agxbuf_trim_zeros (-0 fix)
+     */
+    private static _fixNegativeZero;
+}
+//# sourceMappingURL=agxbuf.d.ts.map

package/dist/util/agxbuf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agxbuf.d.ts","sourceRoot":"","sources":["../../src/util/agxbuf.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAc;IAE3B,mCAAmC;IACnC,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKvB,oCAAoC;IACpC,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAK3B;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAKnC,qCAAqC;IACrC,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,GAAG,IAAI,MAAM;IAMb;;;OAGG;IACH,MAAM,IAAI,MAAM;IAIhB,mCAAmC;IACnC,MAAM,IAAI,MAAM;IAIhB;;;;OAIG;IACH,GAAG,IAAI,MAAM,GAAG,IAAI;IASpB;;;;;;;;;;OAUG;IACH,SAAS,IAAI,IAAI;IAOjB,wDAAwD;IACxD,OAAO,CAAC,gBAAgB;IAOxB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAOhC"}

package/dist/util/bsd-qsort.d.ts

@@ -0,0 +1,22 @@
+/**
+ * BSD heapsort — the fallback Apple libc `_qsort` dispatches to when
+ * introsort's recursion-depth budget (`2*(fls(n)-1)`) is exhausted, guarding
+ * against adversarial inputs that defeat median-of-3 pivot selection. Not
+ * observed to trigger on this corpus (all inputs stay within budget), but
+ * CLAUDE.md requires porting every branch a faithful port can reach.
+ *
+ * @see apple-oss-distributions/Libc stdlib/FreeBSD/heapsort.c:heapsort
+ */
+export declare function heapSort<T>(arr: T[], lo: number, n: number, cmp: (a: T, b: T) => number): void;
+/**
+ * Sort `arr` in place, reproducing libc `qsort`'s permutation of
+ * comparator-equal elements (Bentley–McIlroy quicksort). Use this instead of
+ * `Array.prototype.sort` only where the C oracle's `qsort` tie ordering is
+ * load-bearing; elsewhere the stable native sort is preferred.
+ *
+ * @param arr Array sorted in place (also returned for convenience).
+ * @param cmp Comparator returning <0, 0, or >0 — matching the C comparator's
+ *   sign, including 0 for elements the C comparator treats as equal.
+ */
+export declare function gvQsort<T>(arr: T[], cmp: (a: T, b: T) => number): T[];
+//# sourceMappingURL=bsd-qsort.d.ts.map

package/dist/util/bsd-qsort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bsd-qsort.d.ts","sourceRoot":"","sources":["../../src/util/bsd-qsort.ts"],"names":[],"mappings":"AA+KA;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,CAQ9F;AAyCD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,CAAC,EAAE,CAOrE"}

package/dist/util/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public re-exports for src/util.
+ */
+export { AgBuffer } from "./agxbuf.js";
+export { List } from "./list.js";
+export { gvXmlEscape } from "./xml.js";
+export type { XmlFlags } from "./xml.js";
+export { isExactlyZero, isExactlyEqual, fcmp, imax, imin, d2i, d2f, gvStrtod, } from "./math.js";
+export { rkNewState, rkSeed, rkRandom, rkInterval, } from "./mt19937.js";
+export type { RkState } from "./mt19937.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,aAAa,EACb,cAAc,EACd,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,GAAG,EACH,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,UAAU,EACV,MAAM,EACN,QAAQ,EACR,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/util/list.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic doubly-linked list, replacing the C LIST macro.
+ *
+ * The C LIST macro is a type-generic ring-buffer backed dynamic array.
+ * For the TypeScript port we expose the same logical API using a simple
+ * doubly-linked node structure. The ring-buffer internals need not be
+ * replicated; only the observable contract matters.
+ *
+ * @see lib/util/list.h
+ */
+/**
+ * Type-generic doubly-linked list.
+ *
+ * Matches the observable behaviour of the C LIST macro:
+ *   push / pop  — operate on the back (LIST_APPEND / LIST_POP_BACK)
+ *   unshift / shift — operate on the front (LIST_PREPEND / LIST_POP_FRONT)
+ *   remove      — linear scan by identity (LIST_REMOVE)
+ *   Symbol.iterator — logical order, front to back
+ */
+export declare class List<T> {
+    private _head;
+    private _tail;
+    private _size;
+    /** Append item to back. @see lib/util/list.h:LIST_APPEND */
+    push(item: T): void;
+    /** Remove and return the last item, or undefined if empty.
+     *  @see lib/util/list.h:LIST_POP_BACK */
+    pop(): T | undefined;
+    /** Remove and return the first item, or undefined if empty.
+     *  @see lib/util/list.h:LIST_POP_FRONT */
+    shift(): T | undefined;
+    /** Prepend item to front. @see lib/util/list.h:LIST_PREPEND */
+    unshift(item: T): void;
+    /**
+     * Remove the first occurrence of item (by reference equality).
+     * Returns true if found and removed.
+     * @see lib/util/list.h:LIST_REMOVE
+     */
+    remove(item: T): boolean;
+    /** Iterate items in logical order (front to back). */
+    [Symbol.iterator](): Iterator<T>;
+    /** Number of items in the list. @see lib/util/list.h:LIST_SIZE */
+    get size(): number;
+    /** Detach a node from the list. */
+    private _unlink;
+}
+//# sourceMappingURL=list.d.ts.map

package/dist/util/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/util/list.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAQH;;;;;;;;GAQG;AACH,qBAAa,IAAI,CAAC,CAAC;IACjB,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,KAAK,CAAa;IAE1B,4DAA4D;IAC5D,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAWnB;6CACyC;IACzC,GAAG,IAAI,CAAC,GAAG,SAAS;IAOpB;8CAC0C;IAC1C,KAAK,IAAI,CAAC,GAAG,SAAS;IAOtB,+DAA+D;IAC/D,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAWtB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAUxB,sDAAsD;IACtD,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC;IAYhC,kEAAkE;IAClE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mCAAmC;IACnC,OAAO,CAAC,OAAO;CAahB"}

package/dist/util/math.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Arithmetic helper functions.
+ *
+ * @see lib/util/gv_math.h
+ */
+/**
+ * Bit-exact zero check via DataView (mirrors C memcmp against 0).
+ * -0.0 returns false; +0.0 returns true.
+ *
+ * CRITICAL (AD-9): must use bit-level comparison, NOT === 0.
+ * @see lib/util/gv_math.h:is_exactly_zero
+ */
+export declare function isExactlyZero(v: number): boolean;
+/**
+ * Bit-exact equality via DataView (mirrors C memcmp).
+ * Distinguishes +0.0 from -0.0.
+ *
+ * CRITICAL (AD-9): must use bit-level comparison, NOT ===.
+ * @see lib/util/gv_math.h:is_exactly_equal
+ */
+export declare function isExactlyEqual(a: number, b: number): boolean;
+/**
+ * Three-way double comparator.
+ * Returns -1 if a<b, 0 if a==b, 1 if a>b (numerical, not bit-exact).
+ * @see lib/util/gv_math.h:fcmp
+ */
+export declare function fcmp(a: number, b: number): -1 | 0 | 1;
+/**
+ * Integer maximum.
+ * @see lib/util/gv_math.h:imax
+ */
+export declare function imax(a: number, b: number): number;
+/**
+ * Integer minimum.
+ * @see lib/util/gv_math.h:imin
+ */
+export declare function imin(a: number, b: number): number;
+/**
+ * Convert double to int32, clamping to [INT_MIN, INT_MAX].
+ * @see lib/util/gv_math.h:d2i
+ */
+export declare function d2i(v: number): number;
+/**
+ * Round-trip through Float32Array to get float32 precision,
+ * clamping to [-FLT_MAX, FLT_MAX].
+ * @see lib/util/gv_math.h:d2f
+ */
+export declare function d2f(v: number): number;
+/**
+ * Parse a string to a number. Returns NaN for non-numeric strings.
+ * Wraps parseFloat, matching C strtod behaviour for well-formed input.
+ */
+export declare function gvStrtod(s: string): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/util/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/util/math.ts"],"names":[],"mappings":"AACA;;;;GAIG;AASH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKhD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU5D;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAIrD;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIrC;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C"}

package/dist/util/mt19937.d.ts

@@ -0,0 +1,40 @@
+/**
+ * MT19937 Mersenne Twister — port of Random Kit 1.3.
+ *
+ * Must produce bit-identical output to the C reference for any seed.
+ * All arithmetic is kept in 32-bit unsigned space via >>> 0.
+ *
+ * @see lib/neatogen/randomkit.c
+ * @see lib/neatogen/randomkit.h
+ */
+/**
+ * Mersenne Twister state.
+ * @see randomkit.h:rk_state_
+ */
+export interface RkState {
+    /** 624-element state array (uint32). */
+    mt: Uint32Array;
+    /** Current position in the state array; RK_STATE_LEN means "needs twist". */
+    mti: number;
+}
+/** Allocate a fresh, uninitialised state. */
+export declare function rkNewState(): RkState;
+/**
+ * Seed the RNG with a 32-bit unsigned integer.
+ * @see randomkit.c:rk_seed
+ */
+export declare function rkSeed(seed: number, state: RkState): void;
+/**
+ * Generate the next 32-bit pseudo-random value.
+ * @see randomkit.c:rk_random
+ */
+export declare function rkRandom(state: RkState): number;
+/**
+ * Return a random value in [0, max] inclusive.
+ * Uses rejection sampling to avoid modulo bias.
+ * On this platform ULONG_MAX == 0xffffffff (32-bit path).
+ *
+ * @see randomkit.c:rk_interval
+ */
+export declare function rkInterval(max: number, state: RkState): number;
+//# sourceMappingURL=mt19937.d.ts.map

package/dist/util/mt19937.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mt19937.d.ts","sourceRoot":"","sources":["../../src/util/mt19937.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAeH;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,wCAAwC;IACxC,EAAE,EAAE,WAAW,CAAC;IAChB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAOzD;AAeD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAO/C;AAmCD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAS9D"}

package/dist/util/printf-round.d.ts

@@ -0,0 +1,45 @@
+/**
+ * C-printf-compatible decimal rounding.
+ *
+ * `Number.prototype.toFixed` and `Number.prototype.toPrecision` round exact
+ * binary-decimal ties (e.g. 1399.25 at 5 significant digits, 34.125 at 2
+ * fixed decimals — both exactly representable in float64) half-away-from-
+ * zero. C's snprintf ("%.Nf", "%.Ng") rounds exact ties half-to-even under
+ * the default FE_TONEAREST rounding mode, so a value that lands exactly on
+ * a tie diverges from native dot's DOT/xdot attribute output.
+ *
+ * Every finite float64 has an EXACT, finite decimal expansion (its
+ * denominator is a power of two, which always divides some power of ten).
+ * These functions decompose the IEEE-754 bit pattern into an exact integer
+ * mantissa and binary exponent, convert to an exact decimal digit string via
+ * BigInt scaling (multiply by 5^k to trade a factor of 2^k for 10^k), and
+ * round that EXACT digit string half-to-even at the target position. This
+ * never approximates with epsilon-based tie detection — the tie predicate
+ * (`remainder === half`) is computed on exact integers.
+ *
+ * @see lib/gvc/gvdevice.c:gvprintdouble (%.2f) · lib/common/output.c
+ *   (agxbprint "%.5g")
+ */
+/**
+ * Format `v` as C's `%.<decimals>f` would (fixed decimal places, rounded
+ * half-to-even on exact ties). Mirrors `Number.prototype.toFixed(decimals)`
+ * byte-for-byte on every non-tie input; only exact-tie inputs differ.
+ *
+ * @see lib/gvc/gvdevice.c:gvprintdouble
+ */
+export declare function printfFixed(v: number, decimals: number): string;
+/**
+ * Format `v` with `sig` significant digits, using the same notational
+ * contract as `Number.prototype.toPrecision(sig)` — fixed form when the
+ * decimal exponent `e` (0-indexed power of ten of the leading digit)
+ * satisfies `-6 <= e < sig`, otherwise exponential form
+ * `d.ddd...e±N` (unpadded exponent, sign always present). Exact ties round
+ * half-to-even; every other input is byte-identical to `toPrecision(sig)`.
+ * Callers that need C's `%g` exponent threshold (`e < -4 || e >= precision`)
+ * or trailing-zero trimming apply that on top of this — unchanged from the
+ * pre-existing `toPrecision`-based behavior.
+ *
+ * @see lib/common/output.c:71 (agxbprint "%.5g")
+ */
+export declare function printfSig(v: number, sig: number): string;
+//# sourceMappingURL=printf-round.d.ts.map

package/dist/util/printf-round.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printf-round.d.ts","sourceRoot":"","sources":["../../src/util/printf-round.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4DH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqB/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAqCxD"}

package/dist/util/xml.d.ts

@@ -0,0 +1,24 @@
+/**
+ * XML/SVG escaping.
+ *
+ * @see lib/util/xml.h
+ * @see lib/util/xml.c
+ */
+/** Options to tweak the behaviour of XML escaping. @see lib/util/xml.h:xml_flags_t */
+export interface XmlFlags {
+    /** Escape & unconditionally; also escape \n and \r. */
+    raw: boolean;
+    /** Escape '-' as -. */
+    dash: boolean;
+    /** Convert 2nd+ consecutive space to  . */
+    nbsp: boolean;
+    /** Encode non-ASCII as &#xNNNN;. */
+    utf8: boolean;
+}
+/**
+ * XML-escape a string.
+ *
+ * @see lib/util/xml.c:gv_xml_escape
+ */
+export declare function gvXmlEscape(s: string, flags: XmlFlags): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/util/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/util/xml.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,2BAA2B;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAE9D"}

package/dist/vpsc/Block.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Block: a group of variables that must be moved together to satisfy active
+ * constraints. Variables in a block are spanned by a tree of active constraints.
+ *
+ * @see lib/vpsc/block.h
+ * @see lib/vpsc/block.cpp
+ */
+import { Variable } from "./Variable.js";
+import { Constraint } from "./Constraint.js";
+export declare class Block {
+    vars: Variable[];
+    posn: number;
+    weight: number;
+    wposn: number;
+    deleted: boolean;
+    timeStamp: number;
+    /** In-constraint min-heap: external constraints arriving at this block. */
+    in: Constraint[];
+    /** Out-constraint min-heap: external constraints leaving this block. */
+    out: Constraint[];
+    /** Shared reference to the owning Blocks instance's blockTimeCtr. */
+    readonly timeCtr: {
+        value: number;
+    };
+    /** @see lib/vpsc/block.cpp: Block::Block(Variable *v) */
+    constructor(timeCtr: {
+        value: number;
+    }, v?: Variable);
+    /** @see lib/vpsc/block.cpp: Block::addVariable */
+    addVariable(v: Variable): void;
+    /** @see lib/vpsc/block.cpp: Block::desiredWeightedPosition */
+    desiredWeightedPosition(): number;
+    /** @see lib/vpsc/block.cpp: Block::setUpInConstraints */
+    setUpInConstraints(): void;
+    /** @see lib/vpsc/block.cpp: Block::setUpOutConstraints */
+    setUpOutConstraints(): void;
+    /** @see lib/vpsc/block.cpp: Block::setUpConstraintHeap */
+    private setupHeap;
+    /**
+     * Two-arg merge: pick orientation then call three-arg.
+     * @see lib/vpsc/block.cpp: Block::merge(Block* b, Constraint* c)
+     */
+    mergeTwoArg(b: Block, c: Constraint): void;
+    /**
+     * Merge block b into this across constraint c by dist.
+     * @see lib/vpsc/block.cpp: Block::merge(Block *b, Constraint *c, double dist)
+     */
+    mergeInto(b: Block, c: Constraint, dist: number): void;
+    /** @see lib/vpsc/block.cpp: Block::mergeIn */
+    mergeIn(b: Block): void;
+    /** @see lib/vpsc/block.cpp: Block::mergeOut */
+    mergeOut(b: Block): void;
+    /** @see lib/vpsc/block.cpp: Block::findMinInConstraint */
+    findMinInConstraint(): Constraint | null;
+    /** @see lib/vpsc/block.cpp: Block::findMinOutConstraint */
+    findMinOutConstraint(): Constraint | null;
+    /** @see lib/vpsc/block.cpp: Block::deleteMinInConstraint */
+    deleteMinInConstraint(): void;
+    /** @see lib/vpsc/block.cpp: Block::deleteMinOutConstraint */
+    deleteMinOutConstraint(): void;
+    private canFollowLeft;
+    private canFollowRight;
+    /**
+     * Resets LMs for all active constraints to 0 starting from v.
+     * @see lib/vpsc/block.cpp: Block::reset_active_lm
+     */
+    private resetActiveLm;
+    /**
+     * Computes dfdv and Lagrange multipliers; records min-LM constraint.
+     * @see lib/vpsc/block.cpp: Block::compute_dfdv
+     */
+    private computeDfdv;
+    /**
+     * Process one in-constraint during computeDfdvBetween.
+     * Returns [dfdv contribution, updated r, updated m].
+     */
+    private processBetweenIn;
+    /**
+     * Process one out-constraint during computeDfdvBetween.
+     * Returns [dfdv contribution, updated r, updated m].
+     */
+    private processBetweenOut;
+    /**
+     * Computes dfdv between two variables and finds the min-LM constraint.
+     * @see lib/vpsc/block.cpp: Block::compute_dfdv_between
+     */
+    private computeDfdvBetween;
+    /**
+     * Finds the constraint with the minimum Lagrange multiplier.
+     * @see lib/vpsc/block.cpp: Block::findMinLM
+     */
+    findMinLM(): Constraint | null;
+    /** @see lib/vpsc/block.cpp: Block::findMinLMBetween */
+    findMinLMBetween(lv: Variable, rv: Variable): Constraint | null;
+    /**
+     * Populates block b by traversing the active constraint tree from v.
+     * @see lib/vpsc/block.cpp: Block::populateSplitBlock
+     */
+    private populateSplit;
+    /**
+     * Creates two new blocks l and r, splitting this block across constraint c.
+     * @see lib/vpsc/block.cpp: Block::split(Block* &l, Block* &r, Constraint* c)
+     */
+    splitInto(c: Constraint): [Block, Block];
+    /**
+     * Finds the split constraint between vl and vr and splits.
+     * @see lib/vpsc/block.cpp: Block::splitBetween
+     */
+    splitBetween(vl: Variable, vr: Variable): [Constraint, Block, Block];
+    /**
+     * Squared euclidean distance of variables from their desired positions.
+     * @see lib/vpsc/block.cpp: Block::cost
+     */
+    cost(): number;
+}
+//# sourceMappingURL=Block.d.ts.map

package/dist/vpsc/Block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Block.d.ts","sourceRoot":"","sources":["../../src/vpsc/Block.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAW7C,qBAAa,KAAK;IAChB,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,EAAE,EAAE,UAAU,EAAE,CAAC;IACjB,wEAAwE;IACxE,GAAG,EAAE,UAAU,EAAE,CAAC;IAElB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAEpC,yDAAyD;gBAC7C,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC,EAAE,QAAQ;IAgBpD,kDAAkD;IAClD,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI;IAQ9B,8DAA8D;IAC9D,uBAAuB,IAAI,MAAM;IAQjC,yDAAyD;IACzD,kBAAkB,IAAI,IAAI;IAI1B,0DAA0D;IAC1D,mBAAmB,IAAI,IAAI;IAI3B,0DAA0D;IAC1D,OAAO,CAAC,SAAS;IAgBjB;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,GAAG,IAAI;IAW1C;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAatD,8CAA8C;IAC9C,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;IAMvB,+CAA+C;IAC/C,QAAQ,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;IAMxB,0DAA0D;IAC1D,mBAAmB,IAAI,UAAU,GAAG,IAAI;IAsBxC,2DAA2D;IAC3D,oBAAoB,IAAI,UAAU,GAAG,IAAI;IAWzC,4DAA4D;IAC5D,qBAAqB,IAAI,IAAI;IAE7B,6DAA6D;IAC7D,sBAAsB,IAAI,IAAI;IAE9B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,OAAO,CAAC,aAAa;IASrB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAuBnB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;OAGG;IACH,SAAS,IAAI,UAAU,GAAG,IAAI;IAO9B,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IAM/D;;;OAGG;IACH,OAAO,CAAC,aAAa;IAUrB;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;IASxC;;;OAGG;IACH,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC;IAOpE;;;OAGG;IACH,IAAI,IAAI,MAAM;CAQf"}

package/dist/vpsc/Blocks.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Blocks: the block structure defined over the set of variables.
+ *
+ * Each block contains 1 or more variables. All constraints inside a block are
+ * satisfied by keeping the variables fixed relative to one another.
+ *
+ * In C++ Blocks extends std::set<Block*>; here we use a Set<Block>.
+ *
+ * @see lib/vpsc/blocks.h
+ * @see lib/vpsc/blocks.cpp
+ */
+import { Variable } from "./Variable.js";
+import { Constraint } from "./Constraint.js";
+import { Block } from "./Block.js";
+export declare class Blocks {
+    private _blocks;
+    private _vs;
+    /**
+     * blockTimeCtr: private instance field on Blocks, NOT a module-level global.
+     * Exposed as a readonly ref so Block instances can read and increment it.
+     * @see lib/vpsc/blocks.cpp: long blockTimeCtr;  (was global; moved here per AD-4)
+     */
+    readonly timeCtr: {
+        value: number;
+    };
+    /** @see lib/vpsc/blocks.cpp: Blocks::Blocks(const int n, Variable *vs_[]) */
+    constructor(vs: Variable[]);
+    /** Iterate over all blocks (including deleted ones not yet cleaned up). */
+    [Symbol.iterator](): IterableIterator<Block>;
+    /** Add a block to the set. */
+    insert(b: Block): void;
+    /**
+     * Returns a topologically sorted list of variables determined by the
+     * constraint DAG.
+     * @see lib/vpsc/blocks.cpp: Blocks::totalOrder
+     */
+    totalOrder(): Variable[];
+    /** @see lib/vpsc/blocks.cpp: Blocks::dfsVisit */
+    private dfsVisit;
+    /**
+     * Processes incoming constraints most-violated first, merging with the left
+     * neighbouring block until no more violated constraints exist.
+     * @see lib/vpsc/blocks.cpp: Blocks::mergeLeft
+     */
+    mergeLeft(r: Block): void;
+    /**
+     * Symmetrical to mergeLeft.
+     * @see lib/vpsc/blocks.cpp: Blocks::mergeRight
+     */
+    mergeRight(l: Block): void;
+    /** @see lib/vpsc/blocks.cpp: Blocks::removeBlock */
+    private removeBlock;
+    /** @see lib/vpsc/blocks.cpp: Blocks::cleanup */
+    cleanup(): void;
+    /**
+     * Splits block b across constraint c into two new blocks.
+     * @see lib/vpsc/blocks.cpp: Blocks::split
+     */
+    split(b: Block, c: Constraint): [Block, Block];
+    /**
+     * Total squared distance of all variables from their desired positions.
+     * @see lib/vpsc/blocks.cpp: Blocks::cost
+     */
+    cost(): number;
+}
+//# sourceMappingURL=Blocks.d.ts.map

package/dist/vpsc/Blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Blocks.d.ts","sourceRoot":"","sources":["../../src/vpsc/Blocks.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,qBAAa,MAAM;IACjB,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,GAAG,CAAa;IAExB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAEpC,6EAA6E;gBACjE,EAAE,EAAE,QAAQ,EAAE;IAS1B,2EAA2E;IAC3E,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC;IAI5C,8BAA8B;IAC9B,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;IAItB;;;;OAIG;IACH,UAAU,IAAI,QAAQ,EAAE;IASxB,iDAAiD;IACjD,OAAO,CAAC,QAAQ;IAQhB;;;;OAIG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;IAsBzB;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;IAmB1B,oDAAoD;IACpD,OAAO,CAAC,WAAW;IAInB,gDAAgD;IAChD,OAAO,IAAI,IAAI;IAMf;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;IAgB9C;;;OAGG;IACH,IAAI,IAAI,MAAM;CAKf"}

package/dist/vpsc/Constraint.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A constraint determines a minimum spacing required between two variables:
+ *   right.position() - left.position() >= gap
+ *
+ * @see lib/vpsc/constraint.h
+ * @see lib/vpsc/constraint.cpp
+ */
+import type { Block } from "./Solver.js";
+import { Variable } from "./Variable.js";
+/**
+ * Compare two constraints for ordering in a min-heap.
+ * Ports the `compareConstraints` inline from constraint.h.
+ *
+ * @see lib/vpsc/constraint.h: static inline bool compareConstraints(...)
+ */
+export declare function compareConstraints(l: Constraint, r: Constraint): boolean;
+export declare class Constraint {
+    left: Variable;
+    right: Variable;
+    gap: number;
+    /** Lagrange multiplier. @see lib/vpsc/constraint.h */
+    lm: number;
+    /** Timestamp for block membership staleness detection. @see lib/vpsc/constraint.h */
+    timeStamp: number;
+    /** Whether this constraint is currently active (part of a block's spanning tree). */
+    active: boolean;
+    /** Visited flag used during DFS traversals. */
+    visited: boolean;
+    /**
+     * Construct a constraint and register it on both variables.
+     * @see lib/vpsc/constraint.cpp: Constraint::Constraint(...)
+     */
+    constructor(left: Variable, right: Variable, gap: number);
+    /**
+     * Compute slack: how much room exists above the minimum separation.
+     * @see lib/vpsc/constraint.h: double slack() const { return right->position() - gap - left->position(); }
+     */
+    slack(): number;
+    /**
+     * Unregister this constraint from both variables' in/out lists.
+     * Replaces the C++ destructor logic.
+     * @see lib/vpsc/constraint.cpp: Constraint::~Constraint()
+     */
+    destroy(): void;
+}
+/**
+ * Re-export Block type used in compareConstraints so callers don't have a
+ * circular dependency when they only need the type.
+ */
+export type { Block };
+//# sourceMappingURL=Constraint.d.ts.map

package/dist/vpsc/Constraint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Constraint.d.ts","sourceRoot":"","sources":["../../src/vpsc/Constraint.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAiBxE;AAED,qBAAa,UAAU;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;gBACS,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM;IAaxD;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAMhB;AAED;;;GAGG;AACH,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/vpsc/HeapUtils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Min-heap helpers over Constraint arrays.
+ *
+ * The C++ code uses std::make_heap / std::push_heap / std::pop_heap with a
+ * `gt` comparator that flips compareConstraints, producing a min-heap.
+ * We replicate that with a standard binary heap stored in an array.
+ *
+ * @see lib/vpsc/block.cpp: make_heap, insert, deleteMin, findMin, merge_heaps, gt
+ */
+import { Constraint } from "./Constraint.js";
+/**
+ * Greater-than comparator: flips compareConstraints to turn a max-heap into
+ * a min-heap (matching the C++ `gt` lambda).
+ * @see lib/vpsc/block.cpp: static bool gt(...)
+ */
+export declare function heapGt(l: Constraint, r: Constraint): boolean;
+/**
+ * Bubble element at index i upward until the heap property is restored.
+ * @see lib/vpsc/block.cpp: std::push_heap internals
+ */
+export declare function heapSiftUp(h: Constraint[], i: number): void;
+/**
+ * Push element at index i downward until the heap property is restored.
+ * @see lib/vpsc/block.cpp: std::pop_heap internals
+ */
+export declare function heapSiftDown(h: Constraint[], i: number): void;
+/** @see lib/vpsc/block.cpp: static void make_heap(...) */
+export declare function makeHeap(h: Constraint[]): void;
+/** @see lib/vpsc/block.cpp: static Constraint *findMin(...) */
+export declare function heapFindMin(h: Constraint[]): Constraint;
+/** @see lib/vpsc/block.cpp: static void deleteMin(...) */
+export declare function heapDeleteMin(h: Constraint[]): void;
+/** @see lib/vpsc/block.cpp: static void insert(...) */
+export declare function heapInsert(h: Constraint[], c: Constraint): void;
+/** @see lib/vpsc/block.cpp: static void merge_heaps(...) */
+export declare function mergeHeaps(heap1: Constraint[], heap2: Constraint[]): void;
+//# sourceMappingURL=HeapUtils.d.ts.map

package/dist/vpsc/HeapUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeapUtils.d.ts","sourceRoot":"","sources":["../../src/vpsc/HeapUtils.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAsB,MAAM,iBAAiB,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAE5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAS3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAc7D;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,IAAI,CAI9C;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,UAAU,CAEvD;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,IAAI,CAInD;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,IAAI,CAG/D;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAGzE"}