@knowvah/dot-engine 1.2.4 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowvah/dot-engine",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Faithful TypeScript port of Graphviz (dot, neato, fdp, sfdp, circo, twopi, osage, patchwork) — no C: no native binary, no WASM. Oracle-verified against the C implementation, runs in the browser.",
   "keywords": [
     "graphviz",
@@ -98,7 +98,6 @@
     "@typescript/native-preview": "^7.0.0-dev.20260622.1",
     "@vitest/coverage-v8": "^4.1.9",
     "@xmldom/xmldom": "^0.9.10",
-    "canvas": "^3.2.3",
     "esbuild": "^0.28.1",
     "fontkit": "^2.0.4",
     "peggy": "^5.0.0",
@@ -106,6 +105,7 @@
     "tsx": "^4.23.1",
     "typedoc": "^0.28.20",
     "typedoc-plugin-markdown": "^4.12.0",
+    "@knowvah/vitepress-plugin-dot": "^1.0.0",
     "typedoc-vitepress-theme": "^1.1.3",
     "typescript": "^6.0.0",
     "vitepress": "^1.6.0",

package/src/common/graph-init.ts

@@ -181,29 +181,34 @@ function parseRatioKind(g: Graph): RatioKind | undefined {
 
 /**
  * Populate `g.info.drawing` for the ratio kinds whose layout reshape is ported
- * AND corpus-validated: `compress` (compressGraph x-NS, position-cluster.ts)
- * and `fill` (setAspect R_FILL, position-bbox.ts). `expand`/`value` have the
- * math in setAspect but no corpus coverage, and `auto` needs `idealsize`
- * (unported); all three stay deferred — leaving `drawing` unset keeps
- * setAspect/compressGraph a no-op for them.
+ * AND corpus-validated: `compress` (compressGraph x-NS, position-cluster.ts),
+ * `fill` (setAspect R_FILL, position-bbox.ts), and numeric `value` (setAspect
+ * R_VALUE; corpus coverage: 2621, `ratio=0.5625` — see
+ * `.agent-notes/2621-path-structure.md`). C stores the parsed ratio only for
+ * R_VALUE (`input.c setRatio: ratio = atof(p); if > 0`). `expand` has the math
+ * in setAspect but no corpus coverage, and `auto` needs `idealsize` (unported);
+ * both stay deferred — leaving `drawing` unset keeps setAspect a no-op for
+ * them.
  *
  * DELIBERATE DEVIATION from C, carried over verbatim from dot's old init: C
  * allocates GD_drawing unconditionally (`input.c:609`) and stores the parsed
  * ratio_kind for EVERY kind. Allocating it here would flip the
  * `drawing === undefined` guards at `dot/position-bbox.ts:142` (setAspect) and
- * `neato/set-aspect.ts:57`, activating the unvalidated expand/value/auto
- * reshapes and changing dot output. Scope is therefore unchanged by the
- * graph_init consolidation. See `.agent-notes/graph-init-consolidation.md`.
+ * `neato/set-aspect.ts:57`, activating the unvalidated expand/auto reshapes and
+ * changing dot output. Scope is therefore unchanged by the graph_init
+ * consolidation. See `.agent-notes/graph-init-consolidation.md`.
  *
  * @see lib/dotgen/position.c:set_aspect (904), compress_graph (501)
  * @see lib/common/input.c:576 setRatio, 693-694 (size)
  */
 function parseRatioDrawing(g: Graph): void {
   const kind = parseRatioKind(g);
-  if (kind !== 'compress' && kind !== 'fill') return;
+  if (kind !== 'compress' && kind !== 'fill' && kind !== 'value') return;
   const sz = parseSizePoints(g.attrs.get('size'));
   g.info.drawing = makeDrawing({
     ratioKind: kind,
+    // C: GD_drawing(g)->ratio = atof(p), set only for R_VALUE (setRatio).
+    ratio: kind === 'value' ? Number.parseFloat(g.attrs.get('ratio')!) : 0,
     size: sz ? { x: sz.x, y: sz.y } : { x: 0, y: 0 },
     filled: sz?.filled ?? false,
   });

package/src/common/splines-clip.ts

@@ -472,4 +472,29 @@ export function clipAndInstall(fe: Edge, hn: Node, ps: Point[], pn: number, info
   SplineClipHelper.arrowClip(fe, hn, ps, bounds, newspl, info);
   // C: update_bb_bz(&GD_bb(g), cp) — expand g's bb by each installed bezier.
   SplineClipHelper.copyToBezier(newspl, ps, bounds.start, bounds.end, g.info.bb);
+  if (clipDump) {
+    let cur = fe;
+    while (cur.info.to_orig != null && cur.info.edge_type !== 0) cur = cur.info.to_orig;
+    clipDump('S5_CLIP', cur.tail.name, cur.head.name, {
+      inputPn: pn,
+      bounds: { start: bounds.start, end: bounds.end },
+      sflag: newspl.sflag, eflag: newspl.eflag,
+      sp: { ...newspl.sp }, ep: { ...newspl.ep },
+      size: newspl.size,
+      // emit reads bz.size, not list.length (memory: bezier-emit-size-not-length)
+      list: newspl.list.slice(0, newspl.size).map(p => ({ ...p })),
+    });
+  }
+}
+
+/**
+ * Stage-dump hook for the clip/install output (diagnosis only; null in
+ * production — same pattern as splines-routespl.ts:setRouteDump).
+ */
+type ClipDumpFn = (stage: string, tail: string, head: string, payload: unknown) => void;
+let clipDump: ClipDumpFn | null = null;
+
+/** Install (or clear) the clip-stage dump callback. Diagnosis only. */
+export function setClipDump(fn: ClipDumpFn | null): void {
+  clipDump = fn;
 }

package/src/common/splines-routespl.ts

@@ -15,6 +15,50 @@ import { shortestPath, routeSpline, makePolyline } from '../pathplan/index.js';
 import type { Poly } from '../pathplan/types.js';
 import { INIT_DELTA, LOOP_TRIES, ROUTESPL_FUDGE } from './splines-constants.js';
 
+// ---------------------------------------------------------------------------
+// Stage-dump hook (diagnosis only; null in production — same pattern as
+// mincross-order.ts:setMincrossTrace). The callback receives the routing
+// stage name, the real edge's tail/head names (resolved through to_orig like
+// C's routesplines_ realedge walk), and a stage payload; filtering and
+// serialization are the callback's job. Browser-safe: no env reads here.
+// ---------------------------------------------------------------------------
+
+/** Stage payload consumer installed by a diagnosis harness. */
+export type RouteDumpFn = (
+  stage: string, tail: string, head: string, payload: unknown,
+) => void;
+
+let routeDump: RouteDumpFn | null = null;
+
+/** Install (or clear) the routing stage-dump callback. Diagnosis only. */
+export function setRouteDump(fn: RouteDumpFn | null): void {
+  routeDump = fn;
+}
+
+interface DumpEdgeLike {
+  tail?: { name?: string }; head?: { name?: string };
+  info?: { edge_type?: number; to_orig?: DumpEdgeLike };
+}
+
+function dumpIsVirtual(e: DumpEdgeLike): boolean {
+  return (e.info?.edge_type ?? 0) !== 0;
+}
+
+/** Resolve pp.data through to_orig to the real edge's names, as C does. */
+function dumpEdgeNames(pp: Path): [string, string] {
+  let e = pp.data as DumpEdgeLike | null;
+  // C: for (realedge = pp->data; realedge && ED_edge_type(realedge) != NORMAL;
+  //         realedge = ED_to_orig(realedge));  (NORMAL === 0)
+  while (e !== null && dumpIsVirtual(e)) e = e.info?.to_orig ?? null;
+  if (e === null) return ['?', '?'];
+  return [e.tail?.name ?? '?', e.head?.name ?? '?'];
+}
+
+/** Invoke the dump callback when installed; payload built lazily. */
+function emitDump(stage: string, names: [string, string] | null, mk: () => unknown): void {
+  if (routeDump !== null && names !== null) routeDump(stage, names[0], names[1], mk());
+}
+
 // ---------------------------------------------------------------------------
 // overlap helper
 // ---------------------------------------------------------------------------
@@ -353,8 +397,20 @@ function runLimitLoop(
 
 function routeSplinesInternal(pp: Path, polyline: boolean): Point[] | null {
   const boxes = pp.boxes;
+  const dumpNames = routeDump ? dumpEdgeNames(pp) : null;
+  emitDump('S1_INPUT', dumpNames, () => ({
+    nbox: pp.nbox,
+    boxes: pp.boxes.slice(0, pp.nbox).map(b => ({ ll: { ...b.ll }, ur: { ...b.ur } })),
+    start: { p: { ...pp.start.p }, theta: pp.start.theta, constrained: pp.start.constrained },
+    end: { p: { ...pp.end.p }, theta: pp.end.theta, constrained: pp.end.constrained },
+  }));
   if (checkPath(pp.nbox, boxes, pp)) return null;
   const effectiveBoxn = pp.nbox;
+  emitDump('S2_CHECKED', dumpNames, () => ({
+    nbox: effectiveBoxn,
+    boxes: boxes.slice(0, effectiveBoxn).map(b => ({ ll: { ...b.ll }, ur: { ...b.ur } })),
+    start: { p: { ...pp.start.p } }, end: { p: { ...pp.end.p } },
+  }));
 
   let flip = false;
   if (effectiveBoxn > 1 && boxes[0].ll.y > boxes[1].ll.y) {
@@ -389,6 +445,11 @@ function routeSplinesInternal(pp: Path, polyline: boolean): Point[] | null {
     console.warn('in routesplines, Pshortestpath failed');
     return null;
   }
+  emitDump('S3_POLY', dumpNames, () => ({
+    poly: polypoints.map(p => ({ ...p })),
+    eps: [{ ...eps[0] }, { ...eps[1] }],
+    pl: pl.map(p => ({ ...p })),
+  }));
 
   let ps: Point[];
   if (polyline) {
@@ -399,6 +460,11 @@ function routeSplinesInternal(pp: Path, polyline: boolean): Point[] | null {
     ps = routeSpline(edges, pl, evs);
     if (ps.length === 0) return null;
   }
+  emitDump('S4_SPL', dumpNames, () => ({
+    polyline,
+    evs: polyline ? undefined : buildConstraintVectors(pp).map(v => ({ ...v })),
+    ps: ps.map(p => ({ ...p })),
+  }));
 
   if (isTriviallyBounded(ps)) {
     applyTrivialBounds(boxes, effectiveBoxn, ps);