vector-mirror 1.0.0

package/src/core/constraints/distance.js

@@ -0,0 +1,233 @@
+/**
+ * distance.js - DISTANCE-FROM Constraint
+ * Migrated from mirror.js:94-102
+ * Vector Mirror v2.0
+ * Uses ctx.value (multiplier, default 1) + ctx.grid
+ */
+import { registerConstraint } from './registry.js';
+
+registerConstraint('DISTANCE-FROM', {
+  check(subj, ref, { grid, value }) {
+    const gapX = Math.max(
+      0,
+      Math.max(subj.bbox.x, ref.bbox.x) -
+        Math.min(subj.bbox.x + subj.bbox.w, ref.bbox.x + ref.bbox.w),
+    );
+    const gapY = Math.max(
+      0,
+      Math.max(subj.bbox.y, ref.bbox.y) -
+        Math.min(subj.bbox.y + subj.bbox.h, ref.bbox.y + ref.bbox.h),
+    );
+    const actualDist = Math.sqrt(gapX * gapX + gapY * gapY);
+    const targetValue = value ?? 1;
+    // D-003: Ein negativer Ziel-Abstand ist eine INVALIDE Mess-Vorgabe — kein
+    // physikalisch sinnvoller Abstand kann < 0 sein. Ohne diese Wache liefe
+    // `actualDist >= expectedDist` mit expectedDist < 0 IMMER auf pass=true
+    // hinaus (jede nicht-negative reale Distanz erfuellt eine negative Schranke),
+    // d.h. das Auge meldete still "Alles korrekt" auf eine unmessbare Vorgabe.
+    // Das verletzt Prinzip-3 (keine stille Korrektur/Beschoenigung im Auge):
+    // wir CLAMPEN NICHT (das waere eine stille Korrektur der Vorgabe), sondern
+    // reichen den Wert unveraendert durch und melden ehrlich Unmessbarkeit.
+    // pass:null → arbitrate.js sortiert nach `unchecked`, NIE nach `passing`.
+    if (targetValue < 0) {
+      return {
+        pass: null,
+        reasonCode: 'INVALID_MEASUREMENT',
+        reasonCategory: 'SPECIFICATION',
+        detail: `Negativer Ziel-Abstand (${targetValue}) ist keine messbare Vorgabe — ein Abstand kann nicht < 0 sein.`,
+      };
+    }
+    const expectedDist = targetValue * grid.cellW;
+    const pass = actualDist >= expectedDist;
+    const shortfall = expectedDist - actualDist;
+    if (pass) {
+      return { pass: true, detail: null };
+    }
+    //
+    // + F-CODEX-Re-Review-F3 (Patch-2, 2026-05-31):
+    // Strukturierte Pixel-Korrektur dx/dy zusaetzlich zur detail-Prosa.
+    // REGEL-3 verlangt maschinenlesbare Deltas. INV-3 fordert Korrektheit:
+    // nach REALER AABB-Translation MUSS actualDist_after >= expectedDist.
+    //
+    // Strategie: VECTOR-SCALING (nicht 1D-Dominant-Axis).
+    //   Begruendung: Euklid-Distanz ist 2D. Die alte 1D-Dominant-Axis-Variante
+    //   lieferte fuer gapX=gapY=10, expected=20 ein dx=6 → neue Distanz
+    //   sqrt(16^2+10^2)=18.87 < 20 (Codex-Probe Patch-1). Korrekt ist
+    //   Skalierung des AABB-Gap-Vektors auf expectedDist via
+    //   factor = expectedDist/actualDist.
+    //
+    // Verifikation Codex-Probe (gapX=gapY=10, expected=20):
+    //   actualDist=14.14, factor=1.414, rawDx=rawDy=4.14
+    //   nach Apply: gap=(14.14,14.14), dist=19.99 ~ 20  ✓
+    //
+    // Sonderfaelle (in Reihenfolge):
+    //   1) actualDist == 0 (Elemente raeumlich ueberlappend, gapX=gapY=0):
+    //      Vector-Skalierung undefiniert. Push subj's linke (bzw. rechte) Kante
+    //      auf ref's gegenueberliegende Kante + expectedDist.
+    //      F-CODEX-Re-Review-F3-Fix:
+    //        Patch-1 setzte dx = expectedDist. Bei subj=ref=(0,0,10,10),
+    //        expected=20 → dx=20, neuer subj.x=20, AABB-gapX=20-10=10 → newDist=10 < 20  ✗
+    //      Korrekt: targetSubjX = ref.x + ref.w + expectedDist (push rechts)
+    //               dx = targetSubjX - subj.x = (ref.x + ref.w - subj.x) + expectedDist
+    //      Verifikation F-3-Probe (subj=ref=(0,0,10,10), expected=20):
+    //        dx = (0+10-0) + 20 = 30. Neuer subj.x=30. AABB-gapX=30-10=20.
+    //        newDist=20 >= 20  ✓
+    //      Sign-Wahl: signX aus centerDx (falls != 0), sonst default +1
+    //      (push rechts, analog arrange()-Fallback Z.148).
+    //   2) centerDx == 0 UND centerDy == 0 (identisch zentriert ABER mit gap>0,
+    //      z.B. konzentrische Boxen): Sign-Vektor undefiniert. Push in X um
+    //      shortfall (Konsistenz mit arrange()-Fallback). Hinweis: bei
+    //      identisch zentrierten Boxen IST actualDist == 0 (gapX=gapY=0
+    //      geometrisch zwingend), d.h. dieser Pfad ist defensiv und wird
+    //      vom Sonderfall 1 oben bereits abgedeckt — bleibt nur fuer
+    //      Floating-Point-Pathologie.
+    //   3) Sonst: rawDx/rawDy = (factor-1) * gapX/gapY, Sign aus center-Relativ.
+    //      Math.ceil fuer Korrektheit. Mindestens 1px nur wenn rawAchse != 0
+    //      (kein Achsen-Push fuer perfekt-vertikale/horizontale Gaps mit gap=0).
+    const sCx = subj.bbox.x + subj.bbox.w / 2;
+    const sCy = subj.bbox.y + subj.bbox.h / 2;
+    const rCx = ref.bbox.x + ref.bbox.w / 2;
+    const rCy = ref.bbox.y + ref.bbox.h / 2;
+    const centerDx = sCx - rCx;
+    const centerDy = sCy - rCy;
+    // G2 (D-006): detail beschreibt NUR das WAS/WIEVIEL-daneben (Ist-Distanz
+    // vs. Soll-Distanz, Defizit). Die strukturierte Korrektur lebt
+    // ausschliesslich in dx/dy — prose.js/structured.js bauen den
+    // Korrektur-Hinweis aus diesen Feldern, nicht mehr aus dem detail-String.
+    const detail = `Zu nah dran (${Math.round(actualDist)}px statt ${Math.round(expectedDist)}px, Defizit ~${Math.round(shortfall)}px)`;
+    // Sonderfall 1: actualDist == 0 → keine Skalierung moeglich.
+    // F-CODEX-Re-Review-F3-Fix: dx MUSS die raeumliche Ueberlappung +
+    // expectedDist ueberwinden. Push entlang dominanter Achse (X bei
+    // |centerDx|>=|centerDy|, sonst Y). Default +X bei centerDx==centerDy==0.
+    if (actualDist === 0) {
+      const dominantX = Math.abs(centerDx) >= Math.abs(centerDy);
+      if (dominantX) {
+        const signX = centerDx >= 0 ? 1 : -1;
+        // signX>0: subj nach rechts. targetSubjX = ref.x + ref.w + expectedDist
+        // signX<0: subj nach links.  targetSubjX = ref.x - subj.w - expectedDist
+        const targetSubjX =
+          signX > 0
+            ? ref.bbox.x + ref.bbox.w + expectedDist
+            : ref.bbox.x - subj.bbox.w - expectedDist;
+        const rawDx = targetSubjX - subj.bbox.x;
+        const dxRounded =
+          rawDx >= 0 ? Math.ceil(rawDx) : -Math.ceil(Math.abs(rawDx));
+        const dxFinal = dxRounded === 0 ? signX : dxRounded;
+        return { pass: false, detail, dx: dxFinal };
+      } else {
+        const signY = centerDy >= 0 ? 1 : -1;
+        const targetSubjY =
+          signY > 0
+            ? ref.bbox.y + ref.bbox.h + expectedDist
+            : ref.bbox.y - subj.bbox.h - expectedDist;
+        const rawDy = targetSubjY - subj.bbox.y;
+        const dyRounded =
+          rawDy >= 0 ? Math.ceil(rawDy) : -Math.ceil(Math.abs(rawDy));
+        const dyFinal = dyRounded === 0 ? signY : dyRounded;
+        return { pass: false, detail, dy: dyFinal };
+      }
+    }
+    // Sonderfall 2: identisch zentriert (centerDx==0 AND centerDy==0).
+    // Defensiv: geometrisch wird das bereits von Sonderfall 1 abgefangen
+    // (centers identisch ⇒ gapX=gapY=0 ⇒ actualDist=0), bleibt nur fuer
+    // Floating-Point-Pathologie.
+    if (centerDx === 0 && centerDy === 0) {
+      return {
+        pass: false,
+        detail,
+        dx: Math.max(1, Math.round(shortfall)),
+      };
+    }
+    // Vector-Scaling.
+    const factor = expectedDist / actualDist; // > 1 weil pass=false
+    const rawDx = (factor - 1) * gapX;
+    const rawDy = (factor - 1) * gapY;
+    // Sign aus center-Relativ (push-weg-vektor). Bei centerDx==0 (perfekt
+    // vertikal ausgerichtet): rawDx ist ohnehin 0 (gapX==0 in dem Setup) →
+    // sign-Wahl egal, dx=0.
+    const signX = centerDx >= 0 ? 1 : -1;
+    const signY = centerDy >= 0 ? 1 : -1;
+    // Aufrunden (Math.ceil) statt Math.round gegen Rundungs-Defizit:
+    // Math.round(4.142)=4 wuerde fuer Codex-Probe newDist=19.8 < 20 liefern
+    // und INV-3-Korrektheit brechen. Math.ceil garantiert
+    // newGap_axis >= raw_target → newDist >= expectedDist.
+    // Mindest-Push 1px erfolgt nur wenn rawAchse != 0 (sonst wuerde ein
+    // 1px-Push auf eine Achse ohne Gap kreiert, was semantisch falsch waere).
+    let dx = 0;
+    let dy = 0;
+    if (rawDx !== 0) {
+      const r = Math.ceil(Math.abs(rawDx));
+      dx = Math.max(1, r) * signX;
+    }
+    if (rawDy !== 0) {
+      const r = Math.ceil(Math.abs(rawDy));
+      dy = Math.max(1, r) * signY;
+    }
+    // Mindestens eine der beiden Achsen MUSS != 0 sein (REGEL-3-Vertrag).
+    // Wenn beide rawDx, rawDy == 0 waeren, waere actualDist == 0 — und das
+    // ist oben (Sonderfall 1) bereits abgefangen. Defensiv: wenn doch beide
+    // 0 (Floating-Point-Pathologie), fallback dx=1.
+    if (dx === 0 && dy === 0) {
+      dx = 1;
+    }
+    // Output: nur gesetzte Achsen aufnehmen (kanonische Form analog
+    // centered-in.js — undefined statt 0 ist semantisch "keine Korrektion").
+    const out = { pass: false, detail };
+    if (dx !== 0) out.dx = dx;
+    if (dy !== 0) out.dy = dy;
+    return out;
+  },
+  arrange(subj, ref, { canvas, value }) {
+    const cellsX = Math.max(4, Math.min(16, Math.round(canvas.width / 50)));
+    const cellW = canvas.width / cellsX;
+    const minDist = (value ?? 1) * cellW;
+
+    // AABB gap metric — identical to check() for consistency (Audit Fix J)
+    const gapX = Math.max(
+      0,
+      Math.max(subj.bbox.x, ref.bbox.x) -
+        Math.min(subj.bbox.x + subj.bbox.w, ref.bbox.x + ref.bbox.w),
+    );
+    const gapY = Math.max(
+      0,
+      Math.max(subj.bbox.y, ref.bbox.y) -
+        Math.min(subj.bbox.y + subj.bbox.h, ref.bbox.y + ref.bbox.h),
+    );
+    const actualDist = Math.sqrt(gapX * gapX + gapY * gapY);
+
+    // Already far enough apart — no-op
+    if (actualDist >= minDist) {
+      return { x: subj.bbox.x, y: subj.bbox.y };
+    }
+
+    // Push along dominant axis (center-to-center direction)
+    const sCx = subj.bbox.x + subj.bbox.w / 2;
+    const sCy = subj.bbox.y + subj.bbox.h / 2;
+    const rCx = ref.bbox.x + ref.bbox.w / 2;
+    const rCy = ref.bbox.y + ref.bbox.h / 2;
+    const dx = sCx - rCx;
+    const dy = sCy - rCy;
+
+    // Deterministic fallback for identical positions: push right (Audit Fix D)
+    if (dx === 0 && dy === 0) {
+      return { x: ref.bbox.x + ref.bbox.w + minDist, y: subj.bbox.y };
+    }
+
+    // Push along dominant axis so AABB gap = minDist
+    if (Math.abs(dx) >= Math.abs(dy)) {
+      const sign = dx >= 0 ? 1 : -1;
+      const targetX =
+        sign > 0
+          ? ref.bbox.x + ref.bbox.w + minDist
+          : ref.bbox.x - subj.bbox.w - minDist;
+      return { x: targetX, y: subj.bbox.y };
+    } else {
+      const sign = dy >= 0 ? 1 : -1;
+      const targetY =
+        sign > 0
+          ? ref.bbox.y + ref.bbox.h + minDist
+          : ref.bbox.y - subj.bbox.h - minDist;
+      return { x: subj.bbox.x, y: targetY };
+    }
+  },
+});

package/src/core/constraints/fill.js

@@ -0,0 +1,22 @@
+/**
+ * fill.js - FILL Constraint (arrange-only)
+ * Element fills the entire canvas (x:0, y:0, width:W, height:H)
+ * Vector Mirror v2.0 Phase 3a
+ */
+import { registerConstraint } from './registry.js';
+
+registerConstraint('FILL', {
+  // FILL braucht keine Referenz (Element fuellt die Leinwand). Ohne diesen
+  // Marker wuerde die pipeline-Wache (fail-closed-Default) FILL faelschlich
+  // als referenz-pflichtig behandeln.
+  requiresReference: false,
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(_subj, _ref, _ctx) {
+    // arrange-only constraint — check always returns null
+    return { pass: null, detail: 'FILL ist ein arrange-only Constraint' };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(_subj, _ref, { canvas }) {
+    return { x: 0, y: 0, width: canvas.width, height: canvas.height };
+  },
+});

package/src/core/constraints/inside.js

@@ -0,0 +1,52 @@
+/**
+ * inside.js - INSIDE Constraint
+ * Migrated from mirror.js:53-62
+ * Vector Mirror v2.0
+ */
+import { registerConstraint } from './registry.js';
+
+registerConstraint('INSIDE', {
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, ref, _ctx) {
+    const inside =
+      subj.bbox.x >= ref.bbox.x &&
+      subj.bbox.y >= ref.bbox.y &&
+      subj.bbox.x + subj.bbox.w <= ref.bbox.x + ref.bbox.w &&
+      subj.bbox.y + subj.bbox.h <= ref.bbox.y + ref.bbox.h;
+    if (inside) return { pass: true, detail: null };
+    const dx =
+      subj.bbox.x < ref.bbox.x
+        ? ref.bbox.x - subj.bbox.x
+        : subj.bbox.x + subj.bbox.w > ref.bbox.x + ref.bbox.w
+          ? ref.bbox.x + ref.bbox.w - (subj.bbox.x + subj.bbox.w)
+          : 0;
+    const dy =
+      subj.bbox.y < ref.bbox.y
+        ? ref.bbox.y - subj.bbox.y
+        : subj.bbox.y + subj.bbox.h > ref.bbox.y + ref.bbox.h
+          ? ref.bbox.y + ref.bbox.h - (subj.bbox.y + subj.bbox.h)
+          : 0;
+    const cParts = [];
+    if (dx !== 0) cParts.push(`dx=${Math.round(dx)}px`);
+    if (dy !== 0) cParts.push(`dy=${Math.round(dy)}px`);
+    const result = {
+      pass: false,
+      detail: `Ragt aus #${ref.id} heraus. Korrektur: ${cParts.join(', ')}`,
+    };
+    if (dx !== 0) result.dx = Math.round(dx);
+    if (dy !== 0) result.dy = Math.round(dy);
+    return result;
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(subj, ref, _ctx) {
+    const x = Math.max(
+      ref.bbox.x,
+      Math.min(subj.bbox.x, ref.bbox.x + ref.bbox.w - subj.bbox.w),
+    );
+    const y = Math.max(
+      ref.bbox.y,
+      Math.min(subj.bbox.y, ref.bbox.y + ref.bbox.h - subj.bbox.h),
+    );
+    return { x, y };
+  },
+});

package/src/core/constraints/loader.js

@@ -0,0 +1,65 @@
+/**
+ * loader.js - Side-Effect Imports for all Constraints + REGEL-3 Validation-Wrapper
+ * ADR-020: New constraint = 1 file + 1 import here
+ * Vector Mirror v2.0
+ *
+ *
+ *   Zusaetzlich zum side-effect-Registrieren exportiert loader.js jetzt
+ *   `validatedCheckConstraint(type, subj, ref, ctx)`. Diese Funktion
+ *   delegiert an registry.checkConstraint und prueft das Resultat gegen
+ *   constraintCheckSchema (REGEL-3 Output-Boundary-Gate, WELLE-β-004).
+ *
+ *   pipeline.js bleibt UNVERAENDERT — Edit C ist additive API. Die
+ *   Drift-Verhinderung greift via test_regel3_invariants.js (Edit H),
+ *   das validatedCheckConstraint generativ ueber alle registrierten
+ *   Constraints aufruft. Damit faengt jeder neue Constraint, der REGEL-3
+ *   bricht (kein dx/dy bei fail), schon im Unit-Test (Fail-Fast).
+ *
+ *   Warum nicht registry.js direkt patchen: registry.js liegt ausserhalb
+ *   der 8 Patch-Files (H-9). Andon-Cord-#3-Vermeidung — andere Constraints
+ *   (CENTERED-IN, NO-OVERLAP, etc.) bleiben unangetastet im Pipeline-Pfad,
+ *   keine Pre-Existing-Drift wird stillschweigend "nebenbei" gefixed.
+ */
+import './centered-in.js';
+import './no-overlap.js';
+import './inside.js';
+import './aligned.js';
+import './positional.js';
+import './distance.js';
+import './same-size.js';
+import './color.js';
+import './fill.js';
+
+import { constraintCheckSchema } from './_schema.js';
+import { checkConstraint } from './registry.js';
+
+/**
+ * REGEL-3 Output-Boundary-Gate.
+ *
+ * Aufruf delegiert an checkConstraint, validiert das Resultat gegen
+ * constraintCheckSchema und wirft bei Verletzung einen Error mit
+ * Constraint-Typ + Detail. Bei `pass === null` (Unbekannter Constraint)
+ * wird das Resultat ohne Validation zurueckgegeben — `null` ist eine
+ * gueltige "kein Verdict moeglich"-Antwort und faellt aus REGEL-3 raus.
+ *
+ * @param {string} type   Constraint-Typ (z.B. 'CENTERED-IN', 'DISTANCE-FROM')
+ * @param {object} subj   Subject-Element aus gridMap
+ * @param {object|null} ref  Reference-Element aus gridMap
+ * @param {object} ctx    Kontext { grid, value? }
+ * @returns {{ pass: boolean|null, detail: string|null, dx?: number, dy?: number, dw?: number, dh?: number }}
+ * @throws  Error wenn Constraint REGEL-3 verletzt (fail ohne dx/dy)
+ */
+export function validatedCheckConstraint(type, subj, ref, ctx) {
+  const result = checkConstraint(type, subj, ref, ctx);
+  // pass === null → "Unbekannter Constraint" (registry.js Z.29).
+  // Das ist KEIN REGEL-3-Bruch, sondern eine Lookup-Failure — durchreichen.
+  if (result.pass === null) return result;
+  const parsed = constraintCheckSchema.safeParse(result);
+  if (!parsed.success) {
+    const reason = parsed.error.issues.map((i) => i.message).join('; ');
+    throw new Error(
+      `[REGEL-3] Constraint '${type}' verletzt Output-Boundary-Vertrag: ${reason}`,
+    );
+  }
+  return result;
+}

package/src/core/constraints/no-overlap.js

@@ -0,0 +1,50 @@
+/**
+ * no-overlap.js - NO-OVERLAP Constraint
+ * Migrated from mirror.js:42-52
+ * Vector Mirror v2.0
+ */
+
+import { bboxOverlap } from '../../lib/bbox.js';
+import { registerConstraint } from './registry.js';
+
+registerConstraint('NO-OVERLAP', {
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, ref, _ctx) {
+    const overlaps = bboxOverlap(subj.bbox, ref.bbox);
+    if (!overlaps) return { pass: true, detail: null };
+    const dxL = ref.bbox.x + ref.bbox.w - subj.bbox.x;
+    const dxR = ref.bbox.x - (subj.bbox.x + subj.bbox.w);
+    const dyT = ref.bbox.y + ref.bbox.h - subj.bbox.y;
+    const dyB = ref.bbox.y - (subj.bbox.y + subj.bbox.h);
+    const moves = [
+      { v: dxL, type: 'dx', abs: Math.abs(dxL) },
+      { v: dxR, type: 'dx', abs: Math.abs(dxR) },
+      { v: dyT, type: 'dy', abs: Math.abs(dyT) },
+      { v: dyB, type: 'dy', abs: Math.abs(dyB) },
+    ];
+    const best = moves.reduce((a, b) => (a.abs < b.abs ? a : b));
+    const result = {
+      pass: false,
+      detail: `Überlappt #${ref.id}. Kürzester Fluchtweg: ${best.type}=${Math.round(best.v)}px`,
+    };
+    result[best.type] = Math.round(best.v);
+    return result;
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(subj, ref, _ctx) {
+    if (!bboxOverlap(subj.bbox, ref.bbox))
+      return { x: subj.bbox.x, y: subj.bbox.y };
+    const dxL = ref.bbox.x + ref.bbox.w - subj.bbox.x;
+    const dxR = ref.bbox.x - (subj.bbox.x + subj.bbox.w);
+    const dyT = ref.bbox.y + ref.bbox.h - subj.bbox.y;
+    const dyB = ref.bbox.y - (subj.bbox.y + subj.bbox.h);
+    const moves = [
+      { dx: dxL, dy: 0, abs: Math.abs(dxL) },
+      { dx: dxR, dy: 0, abs: Math.abs(dxR) },
+      { dx: 0, dy: dyT, abs: Math.abs(dyT) },
+      { dx: 0, dy: dyB, abs: Math.abs(dyB) },
+    ];
+    const best = moves.reduce((a, b) => (a.abs < b.abs ? a : b));
+    return { x: subj.bbox.x + best.dx, y: subj.bbox.y + best.dy };
+  },
+});

package/src/core/constraints/positional.js

@@ -0,0 +1,46 @@
+/**
+ * positional.js - LEFT-OF + ABOVE Constraints
+ * Migrated from mirror.js:80-93
+ * Vector Mirror v2.0
+ */
+import { registerConstraint } from './registry.js';
+
+registerConstraint('LEFT-OF', {
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, ref, _ctx) {
+    const expectedMaxX = ref.bbox.x;
+    const actualMaxX = subj.bbox.x + subj.bbox.w;
+    const pass = actualMaxX <= expectedMaxX;
+    const dx = actualMaxX - expectedMaxX;
+    if (pass) return { pass, detail: null };
+    return {
+      pass,
+      detail: `Nicht links davon. Korrektur: dx=${Math.round(-dx)}px`,
+      dx: Math.round(-dx),
+    };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(subj, ref, _ctx) {
+    return { x: ref.bbox.x - subj.bbox.w };
+  },
+});
+
+registerConstraint('ABOVE', {
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, ref, _ctx) {
+    const expectedMaxY = ref.bbox.y;
+    const actualMaxY = subj.bbox.y + subj.bbox.h;
+    const pass = actualMaxY <= expectedMaxY;
+    const dy = actualMaxY - expectedMaxY;
+    if (pass) return { pass, detail: null };
+    return {
+      pass,
+      detail: `Nicht oberhalb. Korrektur: dy=${Math.round(-dy)}px`,
+      dy: Math.round(-dy),
+    };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(subj, ref, _ctx) {
+    return { y: ref.bbox.y - subj.bbox.h };
+  },
+});

package/src/core/constraints/registry.js

@@ -0,0 +1,98 @@
+/**
+ * registry.js - Constraint Registry (Plug-In Pattern)
+ * ADR-020: Map<type, {check, arrange}>
+ * ADR-022: Context-Object Pattern (ctx = { grid, value? })
+ * Vector Mirror v2.0
+ */
+
+const handlers = new Map();
+
+/**
+ * Registers a constraint handler.
+ *
+ * `requiresReference` (default true) markiert, ob `check()`/`arrange()` ein
+ * Referenz-Element (`ref`) DEREFERENZIEREN — z.B. `ref.bbox`. Der Default ist
+ * fail-closed (true): ein neu registrierter, unmarkierter Constraint gilt als
+ * referenz-pflichtig, damit eine fehlende Referenz NIE still in einen
+ * null-Deref-Crash laeuft (REGEL-8). Nur Constraints, die ohne Referenz
+ * arbeiten (COLOR, FILL), setzen `requiresReference: false` explizit.
+ *
+ * @param {string} type - Constraint type (e.g. 'CENTERED-IN')
+ * @param {{ check: Function, arrange?: Function, requiresReference?: boolean }} handler
+ */
+export function registerConstraint(
+  type,
+  { check, arrange, requiresReference },
+) {
+  handlers.set(type, {
+    check,
+    arrange,
+    requiresReference: requiresReference !== false,
+  });
+}
+
+/**
+ * Ob ein Constraint-Typ ueberhaupt registriert (bekannt) ist.
+ *
+ * Trennt die zwei Diagnosen sauber: ein UNBEKANNTER Typ (Tippfehler/Phantasie)
+ * darf NICHT vom ref-Guard maskiert werden — er fliesst weiter zu
+ * checkConstraint → CONSTRAINT_TYPE_UNKNOWN (+ Levenshtein-Vorschlag). Nur fuer
+ * BEKANNTE, ref-pflichtige Typen ohne ref greift der fail-closed REFERENCE_NOT_FOUND.
+ *
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function isRegistered(type) {
+  return handlers.has(type);
+}
+
+/**
+ * Ob ein Constraint-Typ ein Referenz-Element braucht (siehe registerConstraint).
+ * Fail-closed: unbekannte Typen gelten als referenz-pflichtig (true), damit ein
+ * fehlender ref nie in einen Deref-Crash faellt.
+ *
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function requiresReference(type) {
+  const h = handlers.get(type);
+  return h ? h.requiresReference : true;
+}
+
+/**
+ * Checks a single constraint.
+ * @param {string} type
+ * @param {object} subj - Subject element from gridMap
+ * @param {object|null} ref - Reference element from gridMap
+ * @param {object} ctx - { grid, value? }
+ * @returns {{ pass: boolean|null, detail?: string, dx?: number, dy?: number }}
+ */
+export function checkConstraint(type, subj, ref, ctx) {
+  const h = handlers.get(type);
+  if (!h) return { pass: null, detail: `Unbekannter Constraint: ${type}` };
+  return h.check(subj, ref, ctx);
+}
+
+/**
+ * Arranges a single constraint (inverse of check).
+ * @param {string} type
+ * @param {object} subj - Subject element { bbox }
+ * @param {object|null} ref - Reference element { bbox }
+ * @param {object} ctx - { canvas, value? }
+ * @returns {object|null} Attribute patch or null if no arrange handler
+ */
+export function arrangeConstraint(type, subj, ref, ctx) {
+  const h = handlers.get(type);
+  if (!h?.arrange) return null;
+  return h.arrange(subj, ref, ctx);
+}
+
+/**
+ * Lists all registered constraint types.
+ */
+export function listConstraints() {
+  return [...handlers.entries()].map(([type, h]) => ({
+    type,
+    hasArrange: !!h.arrange,
+  }));
+}

package/src/core/constraints/same-size.js

@@ -0,0 +1,35 @@
+/**
+ * same-size.js - SAME-SIZE Constraint
+ * Migrated from mirror.js:73-79
+ * Vector Mirror v2.0
+ */
+
+import { getTolX, getTolY } from '../tolerance.js';
+import { registerConstraint } from './registry.js';
+
+registerConstraint('SAME-SIZE', {
+  check(subj, ref, { grid }) {
+    if (ref.bbox.w === 0 || ref.bbox.h === 0)
+      return { pass: null, detail: 'Referenz hat Grösse 0' };
+    const dw = subj.bbox.w - ref.bbox.w;
+    const dh = subj.bbox.h - ref.bbox.h;
+    const pass =
+      Math.abs(dw) <= getTolX(ref.bbox.w, grid) &&
+      Math.abs(dh) <= getTolY(ref.bbox.h, grid);
+    if (pass) return { pass, detail: null };
+    // G2 (D-006): detail beschreibt NUR das WAS/WIEVIEL-daneben. Die
+    // strukturierte Korrektur lebt ausschliesslich in dw/dh — prose.js/
+    // structured.js bauen den Hinweis aus diesen Feldern, nicht mehr aus
+    // dem detail-String (kein String-Leak, gate-bar in S8).
+    return {
+      pass,
+      detail: `Grösse weicht ab (Δw=${Math.round(dw)}px, Δh=${Math.round(dh)}px)`,
+      dw: Math.round(-dw),
+      dh: Math.round(-dh),
+    };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(_subj, ref, _ctx) {
+    return { width: ref.bbox.w, height: ref.bbox.h };
+  },
+});