novac 2.0.1 → 2.2.0

package/kits/kitmatrix/kitdef.js

@@ -0,0 +1,960 @@
+'use strict';
+
+/**
+ * kitmatrix — Nova Spatial Computation Kit
+ *
+ * A coordinate space model for geometry, movement, simulation, and layout.
+ * Not a rendering engine by default — a pure spatial model with optional
+ * terminal rendering (ANSI) and NVML rendering.
+ *
+ * Usage in Nova:
+ *   import "kitmatrix"
+ *
+ *   let m = new Matrix(40, 20)
+ *   let a = m.point(5, 5)
+ *   let b = m.point(20, 15)
+ *   m.debug.drawPoints()
+ *   m.debug.drawGraph(myGraph)
+ *   m.render.frame()           // full ANSI terminal frame
+ *   m.nvml.page()              // generate NVML page source
+ */
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+
+function _deg2rad(d) { return d * Math.PI / 180; }
+function _rad2deg(r) { return r * 180 / Math.PI; }
+function _clamp(v, lo, hi) { return Math.max(lo, Math.min(hi, v)); }
+function _approxEq(a, b, eps = 1e-10) { return Math.abs(a - b) < eps; }
+
+// ANSI helpers
+const A = {
+  reset:    '\x1b[0m',
+  bold:     '\x1b[1m',
+  dim:      '\x1b[2m',
+  fg:  (n)  => `\x1b[38;5;${n}m`,
+  bg:  (n)  => `\x1b[48;5;${n}m`,
+  rgb: (r,g,b) => `\x1b[38;2;${r};${g};${b}m`,
+  bgRgb:(r,g,b)=> `\x1b[48;2;${r};${g};${b}m`,
+  pos: (r,c) => `\x1b[${r};${c}H`,
+  cls:      '\x1b[2J',
+  home:     '\x1b[H',
+  hide:     '\x1b[?25l',
+  show:     '\x1b[?25h',
+  alt:      '\x1b[?1049h',
+  main:     '\x1b[?1049l',
+};
+
+// Box drawing
+const BOX = {
+  tl:'┌', tr:'┐', bl:'└', br:'┘', h:'─', v:'│',
+  ml:'├', mr:'┤', mt:'┬', mb:'┴', x:'┼',
+  dtl:'╔',dtr:'╗',dbl:'╚',dbr:'╝',dh:'═',dv:'║',
+};
+
+// ── MatrixAxis ───────────────────────────────────────────────────────────────
+
+class MatrixAxis {
+  constructor(angle = 0, margin = 1) { this.angle = angle; this.margin = margin; }
+  unitVector() { const r=_deg2rad(this.angle); return {x:Math.cos(r),y:Math.sin(r)}; }
+  project(x,y) { const u=this.unitVector(); return (x*u.x+y*u.y)*this.margin; }
+  toOffset(s)  { const u=this.unitVector(),sc=s*this.margin; return {x:u.x*sc,y:u.y*sc}; }
+  clone()      { return new MatrixAxis(this.angle,this.margin); }
+  toString()   { return `MatrixAxis(${this.angle}°, margin=${this.margin})`; }
+  static horizontal()  { return new MatrixAxis(0,1); }
+  static vertical()    { return new MatrixAxis(90,1); }
+  static diagonal()    { return new MatrixAxis(45,1); }
+  static isometricX()  { return new MatrixAxis(30,1); }
+  static isometricY()  { return new MatrixAxis(150,1); }
+}
+
+// ── MatrixVector ─────────────────────────────────────────────────────────────
+
+class MatrixVector {
+  constructor(dx=0,dy=0) { this.dx=dx; this.dy=dy; }
+  magnitude()   { return Math.hypot(this.dx,this.dy); }
+  magnitudeSq() { return this.dx*this.dx+this.dy*this.dy; }
+  normalize()   { const m=this.magnitude(); return m===0?new MatrixVector(0,0):new MatrixVector(this.dx/m,this.dy/m); }
+  scale(n)      { return new MatrixVector(this.dx*n,this.dy*n); }
+  dot(v)        { return this.dx*v.dx+this.dy*v.dy; }
+  cross(v)      { return this.dx*v.dy-this.dy*v.dx; }
+  angle()       { return _rad2deg(Math.atan2(this.dy,this.dx)); }
+  add(v)        { return new MatrixVector(this.dx+v.dx,this.dy+v.dy); }
+  sub(v)        { return new MatrixVector(this.dx-v.dx,this.dy-v.dy); }
+  negate()      { return new MatrixVector(-this.dx,-this.dy); }
+  perpendicular(){ return new MatrixVector(-this.dy,this.dx); }
+  rotate(deg)   { const r=_deg2rad(deg),c=Math.cos(r),s=Math.sin(r); return new MatrixVector(this.dx*c-this.dy*s,this.dx*s+this.dy*c); }
+  reflect(n)    { const u=n.normalize(),d=this.dot(u)*2; return new MatrixVector(this.dx-u.dx*d,this.dy-u.dy*d); }
+  lerp(v,t)     { return new MatrixVector(this.dx+(v.dx-this.dx)*t,this.dy+(v.dy-this.dy)*t); }
+  projectOnto(v){ const d=v.dot(v); return d===0?MatrixVector.zero():v.scale(this.dot(v)/d); }
+  rejectFrom(v) { return this.sub(this.projectOnto(v)); }
+  isZero(eps=1e-10) { return this.magnitude()<eps; }
+  equals(v,eps=0){ return eps===0?this.dx===v.dx&&this.dy===v.dy:_approxEq(this.dx,v.dx,eps)&&_approxEq(this.dy,v.dy,eps); }
+  toArray()     { return [this.dx,this.dy]; }
+  toObject()    { return {dx:this.dx,dy:this.dy}; }
+  clone()       { return new MatrixVector(this.dx,this.dy); }
+  toString()    { return `MatrixVector(${this.dx},${this.dy} |${this.magnitude().toFixed(3)}|)`; }
+  static fromPoints(a,b){ return new MatrixVector(b.x-a.x,b.y-a.y); }
+  static fromAngle(deg,mag=1){ const r=_deg2rad(deg); return new MatrixVector(Math.cos(r)*mag,Math.sin(r)*mag); }
+  static zero()  { return new MatrixVector(0,0); }
+  static unitX() { return new MatrixVector(1,0); }
+  static unitY() { return new MatrixVector(0,1); }
+}
+
+// ── MatrixPoint ──────────────────────────────────────────────────────────────
+
+class MatrixPoint {
+  constructor(matrix,x=0,y=0) { this.matrix=matrix; this.x=x; this.y=y; this.label=null; this.color=null; }
+  oppositingPoint(cx=0,cy=0) { return new MatrixPoint(this.matrix,2*cx-this.x,2*cy-this.y); }
+  distanceTo(o)    { return Math.hypot(o.x-this.x,o.y-this.y); }
+  distanceSqTo(o)  { return (o.x-this.x)**2+(o.y-this.y)**2; }
+  manhattanTo(o)   { return Math.abs(o.x-this.x)+Math.abs(o.y-this.y); }
+  chebyshevTo(o)   { return Math.max(Math.abs(o.x-this.x),Math.abs(o.y-this.y)); }
+  vectorTo(o)      { return new MatrixVector(o.x-this.x,o.y-this.y); }
+  midpointTo(o)    { return new MatrixPoint(this.matrix,(this.x+o.x)/2,(this.y+o.y)/2); }
+  angleTo(o)       { return _rad2deg(Math.atan2(o.y-this.y,o.x-this.x)); }
+  projectOnAxis(ax){ return ax.project(this.x,this.y); }
+  isInBounds(b)    { return b.contains(this); }
+  translate(dxOrV,dy=0) {
+    if (dxOrV instanceof MatrixVector) return new MatrixPoint(this.matrix,this.x+dxOrV.dx,this.y+dxOrV.dy);
+    return new MatrixPoint(this.matrix,this.x+dxOrV,this.y+dy);
+  }
+  rotateAround(ox,oy,deg) {
+    const r=_deg2rad(deg),c=Math.cos(r),s=Math.sin(r),dx=this.x-ox,dy=this.y-oy;
+    return new MatrixPoint(this.matrix,ox+dx*c-dy*s,oy+dx*s+dy*c);
+  }
+  scaleFrom(ox,oy,sx,sy=sx) { return new MatrixPoint(this.matrix,ox+(this.x-ox)*sx,oy+(this.y-oy)*sy); }
+  lerp(o,t) { return new MatrixPoint(this.matrix,this.x+(o.x-this.x)*t,this.y+(o.y-this.y)*t); }
+  snap(sx,sy=sx) { return new MatrixPoint(this.matrix,Math.round(this.x/sx)*sx,Math.round(this.y/sy)*sy); }
+  equals(o,eps=0) { return eps===0?this.x===o.x&&this.y===o.y:_approxEq(this.x,o.x,eps)&&_approxEq(this.y,o.y,eps); }
+  withLabel(l) { this.label=l; return this; }
+  withColor(c) { this.color=c; return this; }
+  toArray()  { return [this.x,this.y]; }
+  toObject() { return {x:this.x,y:this.y}; }
+  clone()    { const p=new MatrixPoint(this.matrix,this.x,this.y); p.label=this.label; p.color=this.color; return p; }
+  toString() { return `MatrixPoint(${this.x},${this.y}${this.label?` "${this.label}"`:''})`; }
+}
+
+// ── MatrixBounds ─────────────────────────────────────────────────────────────
+
+class MatrixBounds {
+  constructor(matrix,minX,minY,maxX,maxY) {
+    this.matrix=matrix;
+    this.minX=Math.min(minX,maxX); this.minY=Math.min(minY,maxY);
+    this.maxX=Math.max(minX,maxX); this.maxY=Math.max(minY,maxY);
+  }
+  get width()    { return this.maxX-this.minX; }
+  get height()   { return this.maxY-this.minY; }
+  get area()     { return this.width*this.height; }
+  get perimeter(){ return 2*(this.width+this.height); }
+  get centerX()  { return (this.minX+this.maxX)/2; }
+  get centerY()  { return (this.minY+this.maxY)/2; }
+  get center()   { return new MatrixPoint(this.matrix,this.centerX,this.centerY); }
+  contains(p)    { return p.x>=this.minX&&p.x<=this.maxX&&p.y>=this.minY&&p.y<=this.maxY; }
+  clamp(p)       { return new MatrixPoint(this.matrix,_clamp(p.x,this.minX,this.maxX),_clamp(p.y,this.minY,this.maxY)); }
+  overlaps(o)    { return this.minX<=o.maxX&&this.maxX>=o.minX&&this.minY<=o.maxY&&this.maxY>=o.minY; }
+  intersection(o){
+    const mnX=Math.max(this.minX,o.minX),mnY=Math.max(this.minY,o.minY);
+    const mxX=Math.min(this.maxX,o.maxX),mxY=Math.min(this.maxY,o.maxY);
+    if (mnX>mxX||mnY>mxY) return null;
+    return new MatrixBounds(this.matrix,mnX,mnY,mxX,mxY);
+  }
+  union(o)       { return new MatrixBounds(this.matrix,Math.min(this.minX,o.minX),Math.min(this.minY,o.minY),Math.max(this.maxX,o.maxX),Math.max(this.maxY,o.maxY)); }
+  expand(mx,my=mx){ return new MatrixBounds(this.matrix,this.minX-mx,this.minY-my,this.maxX+mx,this.maxY+my); }
+  corners()      { return [new MatrixPoint(this.matrix,this.minX,this.minY),new MatrixPoint(this.matrix,this.maxX,this.minY),new MatrixPoint(this.matrix,this.maxX,this.maxY),new MatrixPoint(this.matrix,this.minX,this.maxY)]; }
+  randomPoint()  { return new MatrixPoint(this.matrix,this.minX+Math.random()*this.width,this.minY+Math.random()*this.height); }
+  toObject()     { return {minX:this.minX,minY:this.minY,maxX:this.maxX,maxY:this.maxY,width:this.width,height:this.height}; }
+  toString()     { return `MatrixBounds([${this.minX},${this.minY}]→[${this.maxX},${this.maxY}])`; }
+  static fromPoints(matrix,pts) { const xs=pts.map(p=>p.x),ys=pts.map(p=>p.y); return new MatrixBounds(matrix,Math.min(...xs),Math.min(...ys),Math.max(...xs),Math.max(...ys)); }
+  static fromCenter(matrix,cx,cy,hw,hh=hw){ return new MatrixBounds(matrix,cx-hw,cy-hh,cx+hw,cy+hh); }
+}
+
+// ── MatrixTranslation ─────────────────────────────────────────────────────────
+
+class MatrixTranslation {
+  constructor(matrix,a,b) { this.matrix=matrix; this.a=a; this.b=b; this.dx=b.x-a.x; this.dy=b.y-a.y; }
+  for(p)      { return new MatrixPoint(this.matrix,p.x+this.dx,p.y+this.dy); }
+  inverse()   { return new MatrixTranslation(this.matrix,this.b,this.a); }
+  toVector()  { return new MatrixVector(this.dx,this.dy); }
+  magnitude() { return Math.hypot(this.dx,this.dy); }
+  toString()  { return `MatrixTranslation(dx=${this.dx},dy=${this.dy})`; }
+}
+
+// ── MatrixTransform ───────────────────────────────────────────────────────────
+
+class MatrixTransform {
+  constructor(matrix,{a=1,b=0,c=0,d=1,tx=0,ty=0}={}) { this.matrix=matrix; this.a=a;this.b=b;this.c=c;this.d=d;this.tx=tx;this.ty=ty; }
+  apply(p)   { return new MatrixPoint(this.matrix,this.a*p.x+this.c*p.y+this.tx,this.b*p.x+this.d*p.y+this.ty); }
+  applyVector(v){ return new MatrixVector(this.a*v.dx+this.c*v.dy,this.b*v.dx+this.d*v.dy); }
+  combine(o) {
+    return new MatrixTransform(this.matrix,{
+      a:this.a*o.a+this.c*o.b, b:this.b*o.a+this.d*o.b, c:this.a*o.c+this.c*o.d, d:this.b*o.c+this.d*o.d,
+      tx:this.a*o.tx+this.c*o.ty+this.tx, ty:this.b*o.tx+this.d*o.ty+this.ty
+    });
+  }
+  inverse() {
+    const det=this.a*this.d-this.b*this.c;
+    if (_approxEq(det,0)) throw new Error('MatrixTransform: singular');
+    const inv=1/det;
+    return new MatrixTransform(this.matrix,{a:this.d*inv,b:-this.b*inv,c:-this.c*inv,d:this.a*inv,tx:(this.c*this.ty-this.d*this.tx)*inv,ty:(this.b*this.tx-this.a*this.ty)*inv});
+  }
+  determinant(){ return this.a*this.d-this.b*this.c; }
+  isIdentity() { return _approxEq(this.a,1)&&_approxEq(this.b,0)&&_approxEq(this.c,0)&&_approxEq(this.d,1)&&_approxEq(this.tx,0)&&_approxEq(this.ty,0); }
+  decompose()  {
+    const sx=Math.hypot(this.a,this.b),shear=(this.a*this.c+this.b*this.d)/(sx*sx);
+    const sy=Math.hypot(this.c-shear*this.a,this.d-shear*this.b);
+    return {translation:{x:this.tx,y:this.ty},rotation:_rad2deg(Math.atan2(this.b,this.a)),scale:{x:sx,y:sy},shear};
+  }
+  toArray()  { return [this.a,this.b,this.c,this.d,this.tx,this.ty]; }
+  toString() { return `MatrixTransform([${this.a},${this.b},${this.c},${this.d}] t=[${this.tx},${this.ty}])`; }
+  static identity(m)           { return new MatrixTransform(m); }
+  static translate(m,dx,dy)    { return new MatrixTransform(m,{tx:dx,ty:dy}); }
+  static scale(m,sx,sy=sx,cx=0,cy=0){ return new MatrixTransform(m,{a:sx,d:sy,tx:cx-sx*cx,ty:cy-sy*cy}); }
+  static rotate(m,deg,cx=0,cy=0){
+    const r=_deg2rad(deg),c=Math.cos(r),s=Math.sin(r);
+    return new MatrixTransform(m,{a:c,b:s,c:-s,d:c,tx:cx-c*cx+s*cy,ty:cy-s*cx-c*cy});
+  }
+  static shear(m,shx,shy=0)    { return new MatrixTransform(m,{c:shx,b:shy}); }
+  static reflectX(m)           { return new MatrixTransform(m,{d:-1}); }
+  static reflectY(m)           { return new MatrixTransform(m,{a:-1}); }
+  static reflectOrigin(m)      { return new MatrixTransform(m,{a:-1,d:-1}); }
+}
+
+// ── MatrixTransformChain ──────────────────────────────────────────────────────
+
+class MatrixTransformChain {
+  constructor(matrix,transforms=[]) { this.matrix=matrix; this.transforms=[...transforms]; }
+  add(t)          { this.transforms.push(t); return this; }
+  clear()         { this.transforms=[]; return this; }
+  resolve()       { return this.transforms.reduce((acc,t)=>acc.combine(t),MatrixTransform.identity(this.matrix)); }
+  apply(p)        { return this.resolve().apply(p); }
+  applyInverse(p) { return this.resolve().inverse().apply(p); }
+  toString()      { return `MatrixTransformChain(${this.transforms.length})`; }
+}
+
+// ── MatrixConnector ───────────────────────────────────────────────────────────
+
+class MatrixConnector {
+  constructor(matrix,points=[]) { this.matrix=matrix; this.points=[...points]; }
+  length() { let t=0; for(let i=1;i<this.points.length;i++) t+=this.points[i-1].distanceTo(this.points[i]); return t; }
+  reverse()    { return new MatrixConnector(this.matrix,[...this.points].reverse()); }
+  extend(p)    { return new MatrixConnector(this.matrix,[...this.points,p]); }
+  bounds()     { return MatrixBounds.fromPoints(this.matrix,this.points); }
+  sample(t) {
+    if (!this.points.length) return null;
+    if (this.points.length===1) return this.points[0].clone();
+    t=_clamp(t,0,1);
+    const total=this.length(); if (total===0) return this.points[0].clone();
+    let target=total*t,walked=0;
+    for (let i=1;i<this.points.length;i++) {
+      const seg=this.points[i-1].distanceTo(this.points[i]);
+      if (walked+seg>=target) return this.points[i-1].lerp(this.points[i],(target-walked)/seg);
+      walked+=seg;
+    }
+    return this.points[this.points.length-1].clone();
+  }
+  toString() { return `MatrixConnector(${this.points.length}pts, len=${this.length().toFixed(3)})`; }
+}
+
+// ── MatrixPath ────────────────────────────────────────────────────────────────
+
+class MatrixPath {
+  constructor(matrix,points=[]) { this.matrix=matrix; this.points=[...points]; }
+  length()     { let t=0; for(let i=1;i<this.points.length;i++) t+=this.points[i-1].distanceTo(this.points[i]); return t; }
+  sample(t)    { return new MatrixConnector(this.matrix,this.points).sample(t); }
+  reverse()    { return new MatrixPath(this.matrix,[...this.points].reverse()); }
+  append(o)    { return new MatrixPath(this.matrix,[...this.points,...o.points]); }
+  bounds()     { return MatrixBounds.fromPoints(this.matrix,this.points); }
+  subdivide(n=2) {
+    if (this.points.length<2) return this.clone();
+    const pts=[];
+    for(let i=0;i<this.points.length-1;i++) for(let j=0;j<n;j++) pts.push(this.points[i].lerp(this.points[i+1],j/n));
+    pts.push(this.points[this.points.length-1].clone());
+    return new MatrixPath(this.matrix,pts);
+  }
+  transform(t){ return new MatrixPath(this.matrix,this.points.map(p=>t.apply(p))); }
+  clone()     { return new MatrixPath(this.matrix,this.points.map(p=>p.clone())); }
+  toString()  { return `MatrixPath(${this.points.length}pts, len=${this.length().toFixed(3)})`; }
+}
+
+// ── MatrixGrid ────────────────────────────────────────────────────────────────
+
+class MatrixGrid {
+  constructor(matrix,rows,cols,ox=0,oy=0,cw=1,ch=1) {
+    this.matrix=matrix; this.rows=rows; this.cols=cols;
+    this.originX=ox; this.originY=oy; this.cellW=cw; this.cellH=ch; this._pts=null;
+  }
+  _build() {
+    if (this._pts) return;
+    this._pts=[];
+    for(let r=0;r<this.rows;r++){
+      const row=[];
+      for(let c=0;c<this.cols;c++) row.push(new MatrixPoint(this.matrix,this.originX+c*this.cellW,this.originY+r*this.cellH));
+      this._pts.push(row);
+    }
+  }
+  at(r,c)    { this._build(); return this._pts[r]?.[c]??null; }
+  flat()     { this._build(); return this._pts.flat(); }
+  all()      { this._build(); return this._pts.map(r=>[...r]); }
+  forEach(fn){ this._build(); this._pts.forEach((row,r)=>row.forEach((p,c)=>fn(p,r,c))); }
+  map(fn)    { this._build(); return this._pts.map((row,r)=>row.map((p,c)=>fn(p,r,c))); }
+  filter(fn) { this._build(); return this._pts.flat().filter((p,i)=>fn(p,Math.floor(i/this.cols),i%this.cols)); }
+  neighbors(r,c,diag=false) {
+    this._build();
+    const dirs=[[0,1],[0,-1],[1,0],[-1,0]];
+    if(diag) dirs.push([1,1],[1,-1],[-1,1],[-1,-1]);
+    return dirs.map(([dr,dc])=>this.at(r+dr,c+dc)).filter(Boolean);
+  }
+  snap(p) {
+    this._build();
+    const c=_clamp(Math.round((p.x-this.originX)/this.cellW),0,this.cols-1);
+    const r=_clamp(Math.round((p.y-this.originY)/this.cellH),0,this.rows-1);
+    return this.at(r,c);
+  }
+  indexOf(p) {
+    const c=Math.round((p.x-this.originX)/this.cellW),r=Math.round((p.y-this.originY)/this.cellH);
+    if(c<0||c>=this.cols||r<0||r>=this.rows) return null;
+    return {row:r,col:c};
+  }
+  cellBounds(r,c) { const x=this.originX+c*this.cellW,y=this.originY+r*this.cellH; return new MatrixBounds(this.matrix,x,y,x+this.cellW,y+this.cellH); }
+  toString() { return `MatrixGrid(${this.rows}×${this.cols} cell=${this.cellW}×${this.cellH})`; }
+}
+
+// ── MatrixGraph ───────────────────────────────────────────────────────────────
+
+class MatrixGraph {
+  constructor(matrix) { this.matrix=matrix; this._nodes=new Map(); this._edges=new Map(); this._ids=new WeakMap(); this._nextId=0; }
+  _id(p) {
+    if(!this._ids.has(p)){const id=this._nextId++;this._ids.set(p,id);this._nodes.set(id,p);this._edges.set(id,new Map());}
+    return this._ids.get(p);
+  }
+  connect(a,b,w=null,dir=false) {
+    const ia=this._id(a),ib=this._id(b),wt=w??a.distanceTo(b);
+    this._edges.get(ia).set(ib,wt); if(!dir) this._edges.get(ib).set(ia,wt); return this;
+  }
+  disconnect(a,b,dir=false) {
+    const ia=this._id(a),ib=this._id(b);
+    this._edges.get(ia)?.delete(ib); if(!dir) this._edges.get(ib)?.delete(ia); return this;
+  }
+  neighbors(p) { const id=this._id(p); return [...(this._edges.get(id)||new Map()).keys()].map(nid=>this._nodes.get(nid)).filter(Boolean); }
+  weight(a,b)  { return this._edges.get(this._id(a))?.get(this._id(b))??Infinity; }
+  hasEdge(a,b) { return (this._edges.get(this._id(a))||new Map()).has(this._id(b)); }
+  nodes()      { return [...this._nodes.values()]; }
+  get nodeCount(){ return this._nodes.size; }
+  get edgeCount(){ let t=0; for(const e of this._edges.values()) t+=e.size; return t/2; }
+
+  shortestPath(start,goal) {
+    const sid=this._id(start),gid=this._id(goal),dist=new Map(),prev=new Map(),q=new Set();
+    for(const id of this._nodes.keys()){dist.set(id,Infinity);q.add(id);}
+    dist.set(sid,0);
+    while(q.size>0){
+      let u=null; for(const id of q) if(u===null||dist.get(id)<dist.get(u)) u=id;
+      if(u===null||u===gid) break; q.delete(u);
+      for(const [v,w] of (this._edges.get(u)||new Map())){ if(!q.has(v)) continue; const alt=dist.get(u)+w; if(alt<dist.get(v)){dist.set(v,alt);prev.set(v,u);} }
+    }
+    if(dist.get(gid)===Infinity) return {path:[],cost:Infinity};
+    const path=[];let cur=gid; while(cur!==undefined){path.unshift(this._nodes.get(cur));cur=prev.get(cur);}
+    return {path,cost:dist.get(gid)};
+  }
+
+  astar(start,goal) {
+    const sid=this._id(start),gid=this._id(goal),h=(id)=>{const p=this._nodes.get(id);return p?p.distanceTo(goal):0;};
+    const gS=new Map(),fS=new Map(),prev=new Map(),open=new Set([sid]);
+    for(const id of this._nodes.keys()){gS.set(id,Infinity);fS.set(id,Infinity);}
+    gS.set(sid,0);fS.set(sid,h(sid));
+    while(open.size>0){
+      let u=null; for(const id of open) if(u===null||fS.get(id)<fS.get(u)) u=id;
+      if(u===gid) break; open.delete(u);
+      for(const [v,w] of (this._edges.get(u)||new Map())){
+        const g=gS.get(u)+w; if(g<gS.get(v)){prev.set(v,u);gS.set(v,g);fS.set(v,g+h(v));open.add(v);}
+      }
+    }
+    if(gS.get(gid)===Infinity) return {path:[],cost:Infinity};
+    const path=[];let cur=gid; while(cur!==undefined){path.unshift(this._nodes.get(cur));cur=prev.get(cur);}
+    return {path,cost:gS.get(gid)};
+  }
+
+  reachable(start) {
+    const sid=this._id(start),visited=new Set([sid]),q=[sid];
+    while(q.length>0){const u=q.shift();for(const v of (this._edges.get(u)||new Map()).keys()) if(!visited.has(v)){visited.add(v);q.push(v);}}
+    return [...visited].map(id=>this._nodes.get(id)).filter(Boolean);
+  }
+  toString() { return `MatrixGraph(${this.nodeCount}nodes, ${this.edgeCount}edges)`; }
+}
+
+// ── MatrixProjection ──────────────────────────────────────────────────────────
+
+class MatrixProjection {
+  constructor(matrix){ this.matrix=matrix; }
+  ontoAxis(p,ax){ const s=ax.project(p.x,p.y),off=ax.toOffset(s/ax.margin); return {scalar:s,projected:new MatrixPoint(this.matrix,off.x,off.y)}; }
+  isometric(x,y,z=0,tw=1,th=0.5){ return new MatrixPoint(this.matrix,(x-y)*tw/2,(x+y)*th/2-z*th); }
+  oblique(x,y,z=0,za=45,zs=0.5){ const r=_deg2rad(za); return new MatrixPoint(this.matrix,x+z*zs*Math.cos(r),y+z*zs*Math.sin(r)); }
+  perspective(x,y,z,f=1,cx=0,cy=0){ if(z===0) return new MatrixPoint(this.matrix,cx,cy); return new MatrixPoint(this.matrix,cx+(x-cx)*f/z,cy+(y-cy)*f/z); }
+  remap(p,src,dst){ const tx=(p.x-src.minX)/(src.width||1),ty=(p.y-src.minY)/(src.height||1); return new MatrixPoint(this.matrix,dst.minX+tx*dst.width,dst.minY+ty*dst.height); }
+}
+
+// ── MatrixInterpolation ───────────────────────────────────────────────────────
+
+class MatrixInterpolation {
+  constructor(matrix){ this.matrix=matrix; }
+  lerp(a,b,t)         { return a.lerp(b,_clamp(t,0,1)); }
+  cosine(a,b,t)       { return a.lerp(b,(1-Math.cos(t*Math.PI))/2); }
+  smoothstep(a,b,t)   { const s=_clamp(t,0,1); return a.lerp(b,s*s*(3-2*s)); }
+  smootherstep(a,b,t) { const s=_clamp(t,0,1); return a.lerp(b,s*s*s*(s*(6*s-15)+10)); }
+  catmullRom(p0,p1,p2,p3,t){
+    const t2=t*t,t3=t2*t;
+    return new MatrixPoint(this.matrix,
+      0.5*((2*p1.x)+(-p0.x+p2.x)*t+(2*p0.x-5*p1.x+4*p2.x-p3.x)*t2+(-p0.x+3*p1.x-3*p2.x+p3.x)*t3),
+      0.5*((2*p1.y)+(-p0.y+p2.y)*t+(2*p0.y-5*p1.y+4*p2.y-p3.y)*t2+(-p0.y+3*p1.y-3*p2.y+p3.y)*t3)
+    );
+  }
+  bezierQuadratic(p0,cp,p2,t){ const mt=1-t; return new MatrixPoint(this.matrix,mt*mt*p0.x+2*mt*t*cp.x+t*t*p2.x,mt*mt*p0.y+2*mt*t*cp.y+t*t*p2.y); }
+  bezierCubic(p0,c1,c2,p3,t){ const mt=1-t,m2=mt*mt,t2=t*t; return new MatrixPoint(this.matrix,m2*mt*p0.x+3*m2*t*c1.x+3*mt*t2*c2.x+t2*t*p3.x,m2*mt*p0.y+3*m2*t*c1.y+3*mt*t2*c2.y+t2*t*p3.y); }
+}
+
+// ── MatrixCanvas ──────────────────────────────────────────────────────────────
+// Internal braille/block pixel canvas for terminal rendering.
+// Uses 2×4 braille dots per character cell → 2× horizontal, 4× vertical resolution.
+
+class MatrixCanvas {
+  constructor(charW, charH) {
+    this.charW  = charW;
+    this.charH  = charH;
+    this.pixelW = charW * 2;   // braille: 2 dots wide
+    this.pixelH = charH * 4;   // braille: 4 dots tall
+    // braille cell dot pattern index: [col0row0, col0row1, col0row2, col0row3, col1row0, col1row1, col1row2, col1row3]
+    // Unicode braille: U+2800 + bitmask
+    // Bit layout:  dot1=0x01 dot2=0x02 dot3=0x04 dot4=0x40  (left col, top→bottom)
+    //              dot5=0x08 dot6=0x10 dot7=0x20 dot8=0x80  (right col, top→bottom)
+    this._dots  = new Uint8Array(charW * charH);   // bitmask per cell
+    this._color = new Array(charW * charH).fill(''); // ANSI color prefix per cell
+    this._bg    = new Array(charW * charH).fill(''); // ANSI bg per cell
+    // Braille bit index: [left-col bits top→bottom, right-col bits top→bottom]
+    this._brailleBits = [
+      [0x01,0x02,0x04,0x40],  // left column, rows 0..3
+      [0x08,0x10,0x20,0x80],  // right column, rows 0..3
+    ];
+    this._charBuf = new Array(charW * charH).fill(' '); // fallback char buf
+  }
+
+  _cell(cx, cy) { return cy * this.charW + cx; }
+
+  // Set a pixel (px,py in pixel space)
+  setPixel(px, py, colorAnsi = '') {
+    px = Math.round(px); py = Math.round(py);
+    if (px < 0 || px >= this.pixelW || py < 0 || py >= this.pixelH) return;
+    const cx = Math.floor(px / 2), cy = Math.floor(py / 4);
+    const col = px % 2, row = py % 4;
+    const idx = this._cell(cx, cy);
+    this._dots[idx]  |= this._brailleBits[col][row];
+    if (colorAnsi) this._color[idx] = colorAnsi;
+  }
+
+  // Clear all pixels
+  clear() {
+    this._dots.fill(0);
+    this._color.fill('');
+    this._bg.fill('');
+    this._charBuf.fill(' ');
+  }
+
+  // Place a text character at a char-space position
+  setChar(cx, cy, ch, colorAnsi = '') {
+    if (cx < 0 || cx >= this.charW || cy < 0 || cy >= this.charH) return;
+    const idx = this._cell(cx, cy);
+    this._charBuf[idx] = ch;
+    if (colorAnsi) this._color[idx] = colorAnsi;
+    this._dots[idx] = 0; // char overrides braille
+  }
+
+  // Render to a string (no cursor positioning — just rows)
+  render(options = {}) {
+    const { border = true, title = '' } = options;
+    const rows = [];
+    if (border) {
+      const titleStr = title ? ` ${title} ` : '';
+      const totalW   = this.charW;
+      const pad      = Math.max(0, totalW - titleStr.length - 2);
+      const lpad     = Math.floor(pad / 2), rpad = pad - lpad;
+      rows.push(BOX.dtl + BOX.dh.repeat(lpad) + (titleStr ? A.bold + titleStr + A.reset : '') + BOX.dh.repeat(rpad) + BOX.dtr);
+    }
+    for (let cy = 0; cy < this.charH; cy++) {
+      let row = border ? BOX.dv : '';
+      for (let cx = 0; cx < this.charW; cx++) {
+        const idx  = this._cell(cx, cy);
+        const bits = this._dots[idx];
+        const col  = this._color[idx];
+        const bg   = this._bg[idx];
+        const ch   = this._charBuf[idx];
+        let glyph;
+        if (ch !== ' ' && bits === 0) {
+          // explicit char placed
+          glyph = ch;
+        } else if (bits === 0) {
+          glyph = ' ';
+        } else {
+          glyph = String.fromCodePoint(0x2800 + bits);
+        }
+        row += (col || bg) ? (bg + col + glyph + A.reset) : glyph;
+      }
+      row += border ? BOX.dv : '';
+      rows.push(row);
+    }
+    if (border) rows.push(BOX.dbl + BOX.dh.repeat(this.charW) + BOX.dbr);
+    return rows.join('\n');
+  }
+}
+
+// ── MatrixRenderer ────────────────────────────────────────────────────────────
+// Terminal + NVML renderer attached to a Matrix.
+// m.render.frame(options)   — print a full ANSI frame to stdout
+// m.render.toNVML(options)  — return an NVML page source string
+// m.render.toHTML(options)  — return an HTML <pre> block string
+
+class MatrixRenderer {
+  constructor(matrix) {
+    this.matrix  = matrix;
+    this._canvas = null;
+    this.options = {
+      charW:       80,
+      charH:       24,
+      padding:     1,
+      bg:          '',
+      pointColor:  A.rgb(100,200,255),
+      edgeColor:   A.rgb(80,80,120),
+      pathColor:   A.rgb(255,200,80),
+      gridColor:   A.rgb(60,80,60),
+      labelColor:  A.rgb(255,255,180),
+      axisColor:   A.rgb(120,120,200),
+      title:       '',
+      showAxes:    true,
+      showLabels:  true,
+      showGrid:    false,
+    };
+  }
+
+  configure(opts) { Object.assign(this.options, opts); return this; }
+
+  // Map a matrix (x,y) to canvas pixel (px,py)
+  _toPixel(x, y, canvas, matBounds) {
+    const o    = this.options;
+    const mb   = matBounds || new MatrixBounds(this.matrix, 0, 0, this.matrix.width, this.matrix.height);
+    const padX = o.padding, padY = o.padding;
+    const pw   = canvas.pixelW - padX * 2;
+    const ph   = canvas.pixelH - padY * 2;
+    const tx   = (x - mb.minX) / (mb.width  || 1);
+    const ty   = (y - mb.minY) / (mb.height || 1);
+    return {
+      px: Math.round(padX + tx * pw),
+      py: Math.round(padY + (1 - ty) * ph),   // flip Y so +y is up
+    };
+  }
+
+  // Bresenham line in pixel space on canvas
+  _drawLine(canvas, x0, y0, x1, y1, colorAnsi) {
+    let dx = Math.abs(x1-x0), dy = Math.abs(y1-y0);
+    let sx = x0<x1?1:-1, sy = y0<y1?1:-1, err = dx-dy;
+    while(true){
+      canvas.setPixel(x0, y0, colorAnsi);
+      if(x0===x1&&y0===y1) break;
+      const e2=2*err;
+      if(e2>-dy){err-=dy;x0+=sx;}
+      if(e2< dx){err+=dx;y0+=sy;}
+    }
+  }
+
+  // Draw a circle outline in pixel space
+  _drawCircle(canvas, cx, cy, r, colorAnsi) {
+    const steps = Math.max(12, Math.round(2 * Math.PI * r));
+    for (let i = 0; i < steps; i++) {
+      const a = (i / steps) * Math.PI * 2;
+      canvas.setPixel(Math.round(cx + Math.cos(a) * r), Math.round(cy + Math.sin(a) * r), colorAnsi);
+    }
+  }
+
+  // Build a canvas from the current matrix state
+  _build(overrideOpts = {}) {
+    const o    = Object.assign({}, this.options, overrideOpts);
+    const m    = this.matrix;
+    const c    = new MatrixCanvas(o.charW, o.charH);
+    const mb   = m._registeredBounds || new MatrixBounds(m, 0, 0, m.width, m.height);
+    const tp   = (x, y) => this._toPixel(x, y, c, mb);
+
+    // Draw axes
+    if (o.showAxes) {
+      const originPx = tp(0, 0);
+      // x axis
+      const xEnd = tp(m.width, 0);
+      this._drawLine(c, tp(0, 0).px, tp(0, 0).py, xEnd.px, xEnd.py, o.axisColor);
+      // y axis
+      const yEnd = tp(0, m.height);
+      this._drawLine(c, tp(0, 0).px, tp(0, 0).py, yEnd.px, yEnd.py, o.axisColor);
+      // origin marker
+      c.setChar(Math.floor(originPx.px/2), Math.floor(originPx.py/4), '0', o.axisColor);
+    }
+
+    // Draw registered grid if any
+    if (o.showGrid && m._registeredGrid) {
+      const g = m._registeredGrid;
+      g.forEach((p) => {
+        const {px,py} = tp(p.x, p.y);
+        c.setPixel(px, py, o.gridColor);
+      });
+    }
+
+    // Draw registered edges (graphs, connectors, paths)
+    for (const edge of (m._renderEdges || [])) {
+      const {a, b, color} = edge;
+      const pa = tp(a.x, a.y), pb = tp(b.x, b.y);
+      this._drawLine(c, pa.px, pa.py, pb.px, pb.py, color || o.edgeColor);
+    }
+
+    // Draw path lines
+    for (const pathObj of (m._renderPaths || [])) {
+      const {points, color} = pathObj;
+      for (let i = 1; i < points.length; i++) {
+        const pa = tp(points[i-1].x, points[i-1].y);
+        const pb = tp(points[i].x,   points[i].y);
+        this._drawLine(c, pa.px, pa.py, pb.px, pb.py, color || o.pathColor);
+      }
+    }
+
+    // Draw points
+    for (const p of m._points) {
+      const {px, py} = tp(p.x, p.y);
+      const col = p.color || o.pointColor;
+      this._drawCircle(c, px, py, 2, col);
+      c.setPixel(px, py, col);
+      if (o.showLabels && p.label) {
+        const cx = Math.floor(px/2) + 1, cy = Math.floor(py/4);
+        const lbl = p.label.slice(0,6);
+        for (let i = 0; i < lbl.length; i++) c.setChar(cx+i, cy, lbl[i], o.labelColor);
+      }
+    }
+
+    return { canvas: c, options: o };
+  }
+
+  // ── Terminal render ──────────────────────────────────────────────────────
+
+  // Register a graph for rendering — draws all its edges
+  addGraph(graph, color) {
+    if (!this.matrix._renderEdges) this.matrix._renderEdges = [];
+    for (const [id, edges] of graph._edges) {
+      const a = graph._nodes.get(id);
+      for (const [nid] of edges) {
+        const b = graph._nodes.get(nid);
+        if (a && b) this.matrix._renderEdges.push({ a, b, color });
+      }
+    }
+    return this;
+  }
+
+  // Register a path for rendering
+  addPath(path, color) {
+    if (!this.matrix._renderPaths) this.matrix._renderPaths = [];
+    this.matrix._renderPaths.push({ points: path.points, color });
+    return this;
+  }
+
+  // Set the visible bounds explicitly (overrides 0,0→w,h)
+  setBounds(bounds) { this.matrix._registeredBounds = bounds; return this; }
+
+  // Clear all registered render overlays
+  clearOverlays() { this.matrix._renderEdges = []; this.matrix._renderPaths = []; return this; }
+
+  // Print a frame to stdout
+  frame(opts = {}) {
+    const { canvas, options: o } = this._build(opts);
+    process.stdout.write(canvas.render({ border: true, title: o.title || this.matrix.toString() }) + '\n');
+    return this;
+  }
+
+  // Print frame with cursor positioning (for live update)
+  frameAt(row = 1, col = 1, opts = {}) {
+    const { canvas, options: o } = this._build(opts);
+    const lines = canvas.render({ border: true, title: o.title || '' }).split('\n');
+    let out = A.hide;
+    lines.forEach((line, i) => { out += A.pos(row + i, col) + line; });
+    out += A.show;
+    process.stdout.write(out);
+    return this;
+  }
+
+  // Start a live animation loop: fn(matrix, renderer, frame) called each tick
+  animate(fn, fps = 12, opts = {}) {
+    const ms      = Math.round(1000 / fps);
+    let   frame   = 0;
+    const charW   = opts.charW || this.options.charW;
+    const charH   = opts.charH || this.options.charH;
+    process.stdout.write(A.alt + A.hide + A.cls + A.home);
+    const interval = setInterval(() => {
+      try {
+        fn(this.matrix, this, frame++);
+        this.frameAt(1, 1, opts);
+      } catch (e) {
+        clearInterval(interval);
+        process.stdout.write(A.main + A.show);
+        throw e;
+      }
+    }, ms);
+    // Stop on Ctrl+C
+    process.on('SIGINT', () => {
+      clearInterval(interval);
+      process.stdout.write(A.main + A.show + '\n');
+      process.exit(0);
+    });
+    return () => { clearInterval(interval); process.stdout.write(A.main + A.show + '\n'); };
+  }
+
+  // ── HTML render ──────────────────────────────────────────────────────────
+
+  toHTML(opts = {}) {
+    const { canvas } = this._build(opts);
+    const o    = Object.assign({}, this.options, opts);
+    const title = o.title || this.matrix.toString();
+    // Strip ANSI codes and produce an HTML <pre> block with spans for colors
+    const raw  = canvas.render({ border: true, title });
+    // Simple ANSI→HTML (handles 24-bit RGB and reset)
+    let html   = raw
+      .replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
+      .replace(/\x1b\[38;2;(\d+);(\d+);(\d+)m/g, (_,r,g,b) => `<span style="color:rgb(${r},${g},${b})">`)
+      .replace(/\x1b\[0m/g, '</span>')
+      .replace(/\x1b\[[0-9;]*m/g, '');
+    return `<pre class="nvml-matrix" style="font-family:monospace;line-height:1.1;background:#0a0a0f;color:#ccc;padding:1rem;border-radius:6px;overflow:auto">${html}</pre>`;
+  }
+
+  // ── NVML render ──────────────────────────────────────────────────────────
+  // Returns a complete .nvml page source string.
+
+  toNVML(opts = {}) {
+    const o     = Object.assign({}, this.options, opts);
+    const title = o.title || `Matrix ${this.matrix.width}×${this.matrix.height}`;
+    const html  = this.toHTML(opts);
+
+    // Build signal data for any named points
+    const signals = this.matrix._points
+      .filter(p => p.label)
+      .map(p => `  ${p.label}_x=${p.x},\n  ${p.label}_y=${p.y},`)
+      .join('\n');
+
+    const pointRows = this.matrix._points
+      .filter(p => p.label)
+      .map(p => `        {tr} [\n          {td}='${p.label}'\n          {td} [ text -> ${p.label}_x ]\n          {td} [ text -> ${p.label}_y ]\n        ]`)
+      .join('\n');
+
+    const stateBlock = signals
+      ? `@state [\n${signals}\n]\n\n`
+      : '';
+
+    return `@config [\n  title='${title}',\n  lang='en',\n  charset='UTF-8',\n]\n\n${stateBlock}@ss [\n  {body} [ font-family='monospace', background='#0a0a0f', color='#ccc', margin='0', padding='2rem' ]\n  {h1} [ color='#6c63ff', font-size='1.4rem', margin-bottom='1rem' ]\n  {.matrix-wrap} [ overflow='auto', margin-bottom='2rem' ]\n  {table} [ border-collapse='collapse', font-size='0.85rem', color='#ccc' ]\n  {th} [ padding='0.3rem 0.8rem', background='#1a1a2e', color='#6c63ff', border='1px solid #333' ]\n  {td} [ padding='0.3rem 0.8rem', border='1px solid #222', text-align='center' ]\n]\n\n@visual [\n  {h1}='${title}'\n\n  {div} [\n    class='matrix-wrap',\n    [..]::code=(\n${html.replace(/\\/g,'\\\\').replace(/`/g,'\\`')}\n    )\n  ]\n\n${pointRows ? `  {h2}='Named Points'\n  {table} [\n    {thead} [ {tr} [ {th}='Name' {th}='X' {th}='Y' ] ]\n    {tbody} [\n${pointRows}\n    ]\n  ]\n` : ''}\n]`;
+  }
+}
+
+// ── MatrixDebug ───────────────────────────────────────────────────────────────
+// ASCII debug + quick terminal output (no braille — plain chars)
+
+class MatrixDebug {
+  constructor(matrix) { this.matrix = matrix; }
+
+  drawPoints(opts = {}) {
+    const m     = this.matrix;
+    const scale = opts.scale ?? 2;
+    const W     = Math.ceil(m.width  * scale) + 3;
+    const H     = Math.ceil(m.height * scale) + 3;
+    const buf   = Array.from({length:H},()=>Array(W).fill(' '));
+    const plot  = (x, y, ch, col='') => {
+      const cx=Math.round(x*scale)+1, cy=H-Math.round(y*scale)-2;
+      if(cx>=0&&cx<W&&cy>=0&&cy<H) buf[cy][cx]={ ch, col };
+    };
+    // axes
+    for(let i=0;i<W;i++) buf[H-2][i]={ ch:'─', col:A.fg(240) };
+    for(let i=0;i<H;i++) buf[i][1]  ={ ch:'│', col:A.fg(240) };
+    buf[H-2][1]={ ch:'└', col:A.fg(240) };
+    // points
+    for(const p of m._points) {
+      const col = p.color || A.rgb(100,200,255);
+      plot(p.x, p.y, p.label?p.label[0]:'●', col);
+    }
+    // output
+    console.log(A.bold + (opts.title||m.toString()) + A.reset);
+    for(const row of buf){
+      let line='';
+      for(const cell of row){
+        if(typeof cell==='object'&&cell!==null) line+=cell.col+cell.ch+A.reset;
+        else line+=' ';
+      }
+      console.log(line);
+    }
+  }
+
+  drawGraph(graph, opts = {}) {
+    const m     = this.matrix;
+    const scale = opts.scale ?? 2;
+    const W     = Math.ceil(m.width  * scale) + 3;
+    const H     = Math.ceil(m.height * scale) + 3;
+    const buf   = Array.from({length:H},()=>Array(W).fill(' '));
+    const toC   = (x,y) => ({cx:Math.round(x*scale)+1, cy:H-Math.round(y*scale)-2});
+
+    const plotLine = (x0,y0,x1,y1,col) => {
+      // Bresenham in char space
+      let dx=Math.abs(x1-x0),dy=Math.abs(y1-y0),sx=x0<x1?1:-1,sy=y0<y1?1:-1,err=dx-dy;
+      while(true){
+        if(x0>=0&&x0<W&&y0>=0&&y0<H) buf[y0][x0]={ ch:dx>dy?'─':'│', col };
+        if(x0===x1&&y0===y1) break;
+        const e2=2*err; if(e2>-dy){err-=dy;x0+=sx;} if(e2<dx){err+=dx;y0+=sy;}
+      }
+    };
+
+    // axes
+    for(let i=0;i<W;i++) buf[H-2][i]={ ch:'─', col:A.fg(240) };
+    for(let i=0;i<H;i++) buf[i][1]  ={ ch:'│', col:A.fg(240) };
+    buf[H-2][1]={ ch:'└', col:A.fg(240) };
+
+    // edges
+    const seen = new Set();
+    for(const [id,edges] of graph._edges){
+      const a = graph._nodes.get(id);
+      if(!a) continue;
+      for(const [nid] of edges){
+        const key=[Math.min(id,nid),Math.max(id,nid)].join('-');
+        if(seen.has(key)) continue; seen.add(key);
+        const b = graph._nodes.get(nid);
+        if(!b) continue;
+        const pa=toC(a.x,a.y), pb=toC(b.x,b.y);
+        plotLine(pa.cx,pa.cy,pb.cx,pb.cy,A.rgb(80,100,160));
+      }
+    }
+    // nodes
+    for(const p of graph.nodes()){
+      const {cx,cy}=toC(p.x,p.y);
+      const col=p.color||A.rgb(100,200,255);
+      if(cx>=0&&cx<W&&cy>=0&&cy<H) buf[cy][cx]={ ch:p.label?p.label[0]:'●', col };
+      if(p.label){
+        for(let i=0;i<Math.min(p.label.length,5);i++){
+          const lx=cx+i+1;
+          if(lx<W) buf[cy][lx]={ ch:p.label[i], col:A.rgb(255,255,180) };
+        }
+      }
+    }
+
+    console.log(A.bold+(opts.title||`Graph: ${graph.nodeCount}n ${graph.edgeCount}e`)+A.reset);
+    for(const row of buf){
+      let line='';
+      for(const cell of row){
+        if(typeof cell==='object'&&cell!==null) line+=cell.col+cell.ch+A.reset;
+        else line+=' ';
+      }
+      console.log(line);
+    }
+  }
+
+  drawPath(path, opts = {}) {
+    console.log(A.bold+(opts.title||path.toString())+A.reset);
+    path.points.forEach((p,i) => {
+      const bar  = '█'.repeat(Math.min(40, Math.round(p.x)));
+      const col  = p.color||A.rgb(255,200,80);
+      console.log(`  ${String(i).padStart(3,' ')} (${String(p.x).padStart(6,' ')}, ${String(p.y).padStart(6,' ')}) ${col}${bar}${A.reset}${p.label?' '+p.label:''}`);
+    });
+  }
+
+  drawGrid(grid, opts = {}) {
+    console.log(A.bold+(opts.title||grid.toString())+A.reset);
+    const col = A.fg(240);
+    for(let r=0;r<grid.rows;r++){
+      let line='  ';
+      for(let c=0;c<grid.cols;c++){
+        const p=grid.at(r,c);
+        const ch=p?.label?p.label[0]:'+';
+        const pcol=p?.color||col;
+        line+=pcol+ch+A.reset+' ';
+      }
+      console.log(line);
+    }
+  }
+
+  drawAxes() {
+    const m=this.matrix;
+    console.log(A.bold+`Matrix ${m.width}×${m.height} axes:`+A.reset);
+    m.axes.forEach((ax,i)=>{
+      const u=ax.unitVector();
+      console.log(`  ${A.fg(99)}[${i}]${A.reset} angle=${ax.angle}° margin=${ax.margin} unit=(${u.x.toFixed(3)},${u.y.toFixed(3)})`);
+    });
+  }
+
+  info() {
+    const m=this.matrix;
+    console.log([
+      A.bold+`Matrix {`+A.reset,
+      `  ${A.fg(99)}size${A.reset}:   ${m.width} × ${m.height}`,
+      `  ${A.fg(99)}axes${A.reset}:   ${m.axes.length}`,
+      `  ${A.fg(99)}points${A.reset}: ${m._points.length}`,
+      `}`
+    ].join('\n'));
+  }
+}
+
+// ── Matrix ────────────────────────────────────────────────────────────────────
+
+class Matrix {
+  constructor(width=100,height=100,axes=[]) {
+    this.width   = width;
+    this.height  = height;
+    this.axes    = axes.length>0?axes:[new MatrixAxis(0,1),new MatrixAxis(90,1)];
+    this._points = [];
+    this._renderEdges = [];
+    this._renderPaths = [];
+    this.debug   = new MatrixDebug(this);
+    this.render  = new MatrixRenderer(this);
+    this.interp  = new MatrixInterpolation(this);
+    this.projection = new MatrixProjection(this);
+  }
+
+  point(x=0,y=0)      { const p=new MatrixPoint(this,x,y); this._points.push(p); return p; }
+  removePoint(p)       { const i=this._points.indexOf(p); if(i!==-1) this._points.splice(i,1); }
+  clearPoints()        { this._points=[]; }
+
+  distance(a,b)        { return a.distanceTo(b); }
+  manhattan(a,b)       { return a.manhattanTo(b); }
+  chebyshev(a,b)       { return a.chebyshevTo(b); }
+  midpoint(a,b)        { return a.midpointTo(b); }
+  angle(a,b)           { return a.angleTo(b); }
+  axisDistance(a,b)    { return this.axes.reduce((s,ax)=>s+Math.abs(ax.project(b.x-a.x,b.y-a.y)),0); }
+  getLengthOf(points)  { let t=0; for(let i=1;i<points.length;i++) t+=points[i-1].distanceTo(points[i]); return t; }
+
+  bounds(mnX,mnY,mxX,mxY) { return new MatrixBounds(this,mnX,mnY,mxX,mxY); }
+  boundsFromPoints(pts)    { return MatrixBounds.fromPoints(this,pts); }
+  spaceBounds()            { return new MatrixBounds(this,0,0,this.width,this.height); }
+
+  grid(rows,cols,ox=0,oy=0,cw=1,ch=1) { return new MatrixGrid(this,rows,cols,ox,oy,cw,ch); }
+  translation(a,b)     { return new MatrixTranslation(this,a,b); }
+  transform(cfg)       { return new MatrixTransform(this,cfg); }
+  translateTransform(dx,dy)    { return MatrixTransform.translate(this,dx,dy); }
+  rotateTransform(deg,cx,cy)   { return MatrixTransform.rotate(this,deg,cx,cy); }
+  scaleTransform(sx,sy,cx,cy)  { return MatrixTransform.scale(this,sx,sy,cx,cy); }
+  shearTransform(shx,shy)      { return MatrixTransform.shear(this,shx,shy); }
+  chain(transforms)            { return new MatrixTransformChain(this,transforms); }
+  path(points)                 { return new MatrixPath(this,points); }
+  connector(points)            { return new MatrixConnector(this,points); }
+  graph()                      { return new MatrixGraph(this); }
+  vector(dx,dy)                { return new MatrixVector(dx,dy); }
+  lerp(a,b,t)                  { return this.interp.lerp(a,b,t); }
+  smoothstep(a,b,t)            { return this.interp.smoothstep(a,b,t); }
+  bezierQuadratic(p0,cp,p2,t)  { return this.interp.bezierQuadratic(p0,cp,p2,t); }
+  bezierCubic(p0,c1,c2,p3,t)  { return this.interp.bezierCubic(p0,c1,c2,p3,t); }
+  project(p,ax)                { return this.projection.ontoAxis(p,ax); }
+  isometric(x,y,z,tw,th)       { return this.projection.isometric(x,y,z,tw,th); }
+  snap(p,sx,sy)                { return p.snap(sx,sy); }
+  normalize(v)                 { return v.normalize?v.normalize():new MatrixVector(v.x,v.y).normalize(); }
+  clone(p)                     { return p.clone(); }
+  clonePath(p)                 { return p.clone(); }
+  toString() { return `Matrix(${this.width}×${this.height} axes=${this.axes.length} pts=${this._points.length})`; }
+}
+
+module.exports = {
+  kitdef: {
+    Matrix, MatrixAxis, MatrixPoint, MatrixVector,
+    MatrixBounds, MatrixTranslation, MatrixTransform, MatrixTransformChain,
+    MatrixConnector, MatrixPath, MatrixGrid, MatrixGraph,
+    MatrixProjection, MatrixInterpolation, MatrixDebug, MatrixRenderer, MatrixCanvas,
+  }
+};