vector-mirror 1.0.0

package/src/lib/geom.js

@@ -0,0 +1,144 @@
+/**
+ * geom.js — AABB Geometry Mathematics for Vector Mirror v2.5
+ *
+ * Source of truth for axis-aligned bounding-box mathematics.
+ * All inputs are boxes of shape `{x, y, w, h}` (top-left + extent).
+ *
+ * Pure math: Node-only, no Playwright / DOM dependency.
+ *
+ * References:
+ *   - RB-02 Pattern 4.2 — Pomona / dyn4j AABB Signed-Gap formulation
+ *   - FIX_PLAN_2026-04-18 §1.2 P1-01
+ *   - ADR-024 Kernel-Vertrag (bbox is the inviolable geometric authority)
+ *
+ * Notes:
+ *   - SVG y-axis grows downward → "north" overflow means a sticks out *above* b.
+ *   - Touching edges (signedDist = 0) count as separated, not overlapping.
+ */
+
+/**
+ * Per-axis signed gaps between two AABBs.
+ * Negative on an axis ⇒ the boxes overlap on that axis.
+ * Used internally; exposed indirectly via signedGapComponents.
+ *
+ * @param {{x:number,y:number,w:number,h:number}} a
+ * @param {{x:number,y:number,w:number,h:number}} b
+ * @returns {{dx:number, dy:number}}
+ */
+function axisGaps(a, b) {
+  const dx = Math.max(a.x - (b.x + b.w), b.x - (a.x + a.w));
+  const dy = Math.max(a.y - (b.y + b.h), b.y - (a.y + a.h));
+  return { dx, dy };
+}
+
+/**
+ * Signed Euclidean gap between two AABBs (Pomona / dyn4j formulation).
+ *
+ *   > 0  separated, value = shortest empty-space distance between rectangles
+ *   = 0  touching (edge or corner aligned, no overlap)
+ *   < 0  overlapping, value = penetration depth along the dominant axis
+ *
+ * @param {{x:number,y:number,w:number,h:number}} a
+ * @param {{x:number,y:number,w:number,h:number}} b
+ * @returns {number}
+ */
+export function signedGapBoxToBox(a, b) {
+  const { dx, dy } = axisGaps(a, b);
+  if (dx < 0 && dy < 0) return Math.max(dx, dy);
+  return Math.hypot(Math.max(dx, 0), Math.max(dy, 0));
+}
+
+/**
+ * Signed gap with per-axis components, for vector-based corrections
+ * (Spotter "dx=-14px, dy=+3px" output).
+ *
+ * Components dx / dy are negative when the boxes overlap on that axis,
+ * zero when edges align, positive when there is empty space.
+ *
+ * `signedDist` follows {@link signedGapBoxToBox}.
+ *
+ * @returns {{dx:number, dy:number, signedDist:number}}
+ */
+export function signedGapComponents(a, b) {
+  const { dx, dy } = axisGaps(a, b);
+  const signedDist =
+    dx < 0 && dy < 0
+      ? Math.max(dx, dy)
+      : Math.hypot(Math.max(dx, 0), Math.max(dy, 0));
+  return { dx, dy, signedDist };
+}
+
+/**
+ * Containment ratio: how much of subject `a` lies within reference `b`.
+ *   0   ⇒ a is fully outside b (no intersection)
+ *   1   ⇒ a is fully inside b
+ *   0..1 partial — subject straddles a boundary
+ *
+ * Subjects with zero area collapse to 0 (they have no area to contain).
+ *
+ * @param {{x:number,y:number,w:number,h:number}} a   subject (typically element bbox)
+ * @param {{x:number,y:number,w:number,h:number}} b   reference (typically canvas bbox)
+ * @returns {number}
+ */
+export function containmentRatio(a, b) {
+  const ix = Math.max(a.x, b.x);
+  const iy = Math.max(a.y, b.y);
+  const ix2 = Math.min(a.x + a.w, b.x + b.w);
+  const iy2 = Math.min(a.y + a.h, b.y + b.h);
+  const intersection = Math.max(0, ix2 - ix) * Math.max(0, iy2 - iy);
+  const area = a.w * a.h;
+  return area === 0 ? 0 : intersection / area;
+}
+
+/**
+ * Overflow per cardinal edge — by how many pixels subject `a` exceeds
+ * container `b` on each side. Each component is non-negative.
+ *
+ * Compass mapping (SVG y-axis grows downward):
+ *   north — a's top edge is above b's top edge
+ *   south — a's bottom edge is below b's bottom edge
+ *   east  — a's right edge is right of b's right edge
+ *   west  — a's left edge is left of b's left edge
+ *
+ * @returns {{north:number, east:number, south:number, west:number}}
+ */
+export function overflowPerEdge(a, b) {
+  return {
+    north: Math.max(0, b.y - a.y),
+    east: Math.max(0, a.x + a.w - (b.x + b.w)),
+    south: Math.max(0, a.y + a.h - (b.y + b.h)),
+    west: Math.max(0, b.x - a.x),
+  };
+}
+
+/**
+ * Minimum Translation Vector — the smallest delta to apply to `a` so that
+ * `a` and `b` no longer overlap. Returns `{dx:0, dy:0, abs:0}` if the boxes
+ * are already separated (or merely touching).
+ *
+ * Resolution rules when overlapping:
+ *   - Push along the axis with the smaller penetration depth.
+ *   - On equal penetration, prefer the x-axis (deterministic tie-break).
+ *   - Sign points away from b: a moves away from b's center.
+ *   - When centers coincide, prefer +x (deterministic for fully congruent boxes).
+ *
+ * @returns {{dx:number, dy:number, abs:number}}
+ */
+export function mtv(a, b) {
+  const { dx, dy } = axisGaps(a, b);
+  if (dx >= 0 || dy >= 0) return { dx: 0, dy: 0, abs: 0 };
+
+  const penX = -dx;
+  const penY = -dy;
+
+  if (penX <= penY) {
+    const aCx = a.x + a.w / 2;
+    const bCx = b.x + b.w / 2;
+    const sign = aCx < bCx ? -1 : 1;
+    return { dx: sign * penX, dy: 0, abs: penX };
+  }
+  const aCy = a.y + a.h / 2;
+  const bCy = b.y + b.h / 2;
+  const sign = aCy < bCy ? -1 : 1;
+  return { dx: 0, dy: sign * penY, abs: penY };
+}

package/src/lib/palette.js

@@ -0,0 +1,236 @@
+/**
+ * palette.js - W3C CSS Named Colors & CIELAB Delta-E Logic
+ * Migrated from color-names.js (v1.6) + parseColor from grid.js
+ * Vector Mirror v2.0
+ */
+
+const PALETTE = [
+  { name: 'aliceblue', r: 240, g: 248, b: 255 },
+  { name: 'antiquewhite', r: 250, g: 235, b: 215 },
+  { name: 'aqua', r: 0, g: 255, b: 255 },
+  { name: 'aquamarine', r: 127, g: 255, b: 212 },
+  { name: 'azure', r: 240, g: 255, b: 255 },
+  { name: 'beige', r: 245, g: 245, b: 220 },
+  { name: 'bisque', r: 255, g: 228, b: 196 },
+  { name: 'black', r: 0, g: 0, b: 0 },
+  { name: 'blanchedalmond', r: 255, g: 235, b: 205 },
+  { name: 'blue', r: 0, g: 0, b: 255 },
+  { name: 'blueviolet', r: 138, g: 43, b: 226 },
+  { name: 'brown', r: 165, g: 42, b: 42 },
+  { name: 'burlywood', r: 222, g: 184, b: 135 },
+  { name: 'cadetblue', r: 95, g: 158, b: 160 },
+  { name: 'chartreuse', r: 127, g: 255, b: 0 },
+  { name: 'chocolate', r: 210, g: 105, b: 30 },
+  { name: 'coral', r: 255, g: 127, b: 80 },
+  { name: 'cornflowerblue', r: 100, g: 149, b: 237 },
+  { name: 'cornsilk', r: 255, g: 248, b: 220 },
+  { name: 'crimson', r: 220, g: 20, b: 60 },
+  { name: 'cyan', r: 0, g: 255, b: 255 },
+  { name: 'darkblue', r: 0, g: 0, b: 139 },
+  { name: 'darkcyan', r: 0, g: 139, b: 139 },
+  { name: 'darkgoldenrod', r: 184, g: 134, b: 11 },
+  { name: 'darkgray', r: 169, g: 169, b: 169 },
+  { name: 'darkgreen', r: 0, g: 100, b: 0 },
+  { name: 'darkkhaki', r: 189, g: 183, b: 107 },
+  { name: 'darkmagenta', r: 139, g: 0, b: 139 },
+  { name: 'darkolivegreen', r: 85, g: 107, b: 47 },
+  { name: 'darkorange', r: 255, g: 140, b: 0 },
+  { name: 'darkorchid', r: 153, g: 50, b: 204 },
+  { name: 'darkred', r: 139, g: 0, b: 0 },
+  { name: 'darksalmon', r: 233, g: 150, b: 122 },
+  { name: 'darkseagreen', r: 143, g: 188, b: 143 },
+  { name: 'darkslateblue', r: 72, g: 61, b: 139 },
+  { name: 'darkslategray', r: 47, g: 79, b: 79 },
+  { name: 'darkturquoise', r: 0, g: 206, b: 209 },
+  { name: 'darkviolet', r: 148, g: 0, b: 211 },
+  { name: 'deeppink', r: 255, g: 20, b: 147 },
+  { name: 'deepskyblue', r: 0, g: 191, b: 255 },
+  { name: 'dimgray', r: 105, g: 105, b: 105 },
+  { name: 'dodgerblue', r: 30, g: 144, b: 255 },
+  { name: 'firebrick', r: 178, g: 34, b: 34 },
+  { name: 'floralwhite', r: 255, g: 250, b: 240 },
+  { name: 'forestgreen', r: 34, g: 139, b: 34 },
+  { name: 'fuchsia', r: 255, g: 0, b: 255 },
+  { name: 'gainsboro', r: 220, g: 220, b: 220 },
+  { name: 'ghostwhite', r: 248, g: 248, b: 255 },
+  { name: 'gold', r: 255, g: 215, b: 0 },
+  { name: 'goldenrod', r: 218, g: 165, b: 32 },
+  { name: 'gray', r: 128, g: 128, b: 128 },
+  { name: 'green', r: 0, g: 128, b: 0 },
+  { name: 'greenyellow', r: 173, g: 255, b: 47 },
+  { name: 'honeydew', r: 240, g: 255, b: 240 },
+  { name: 'hotpink', r: 255, g: 105, b: 180 },
+  { name: 'indianred', r: 205, g: 92, b: 92 },
+  { name: 'indigo', r: 75, g: 0, b: 130 },
+  { name: 'ivory', r: 255, g: 255, b: 240 },
+  { name: 'khaki', r: 240, g: 230, b: 140 },
+  { name: 'lavender', r: 230, g: 230, b: 250 },
+  { name: 'lavenderblush', r: 255, g: 240, b: 245 },
+  { name: 'lawngreen', r: 124, g: 252, b: 0 },
+  { name: 'lemonchiffon', r: 255, g: 250, b: 205 },
+  { name: 'lightblue', r: 173, g: 216, b: 230 },
+  { name: 'lightcoral', r: 240, g: 128, b: 128 },
+  { name: 'lightcyan', r: 224, g: 255, b: 255 },
+  { name: 'lightgoldenrodyellow', r: 250, g: 250, b: 210 },
+  { name: 'lightgray', r: 211, g: 211, b: 211 },
+  { name: 'lightgreen', r: 144, g: 238, b: 144 },
+  { name: 'lightpink', r: 255, g: 182, b: 193 },
+  { name: 'lightsalmon', r: 255, g: 160, b: 122 },
+  { name: 'lightseagreen', r: 32, g: 178, b: 170 },
+  { name: 'lightskyblue', r: 135, g: 206, b: 250 },
+  { name: 'lightslategray', r: 119, g: 136, b: 153 },
+  { name: 'lightsteelblue', r: 176, g: 196, b: 222 },
+  { name: 'lightyellow', r: 255, g: 255, b: 224 },
+  { name: 'lime', r: 0, g: 255, b: 0 },
+  { name: 'limegreen', r: 50, g: 205, b: 50 },
+  { name: 'linen', r: 250, g: 240, b: 230 },
+  { name: 'magenta', r: 255, g: 0, b: 255 },
+  { name: 'maroon', r: 128, g: 0, b: 0 },
+  { name: 'mediumaquamarine', r: 102, g: 205, b: 170 },
+  { name: 'mediumblue', r: 0, g: 0, b: 205 },
+  { name: 'mediumorchid', r: 186, g: 85, b: 211 },
+  { name: 'mediumpurple', r: 147, g: 112, b: 219 },
+  { name: 'mediumseagreen', r: 60, g: 179, b: 113 },
+  { name: 'mediumslateblue', r: 123, g: 104, b: 238 },
+  { name: 'mediumspringgreen', r: 0, g: 250, b: 154 },
+  { name: 'mediumturquoise', r: 72, g: 209, b: 204 },
+  { name: 'mediumvioletred', r: 199, g: 21, b: 133 },
+  { name: 'midnightblue', r: 25, g: 25, b: 112 },
+  { name: 'mintcream', r: 245, g: 255, b: 250 },
+  { name: 'mistyrose', r: 255, g: 228, b: 225 },
+  { name: 'moccasin', r: 255, g: 228, b: 181 },
+  { name: 'navajowhite', r: 255, g: 222, b: 173 },
+  { name: 'navy', r: 0, g: 0, b: 128 },
+  { name: 'oldlace', r: 253, g: 245, b: 230 },
+  { name: 'olive', r: 128, g: 128, b: 0 },
+  { name: 'olivedrab', r: 107, g: 142, b: 35 },
+  { name: 'orange', r: 255, g: 165, b: 0 },
+  { name: 'orangered', r: 255, g: 69, b: 0 },
+  { name: 'orchid', r: 218, g: 112, b: 214 },
+  { name: 'palegoldenrod', r: 238, g: 232, b: 170 },
+  { name: 'palegreen', r: 152, g: 251, b: 152 },
+  { name: 'paleturquoise', r: 175, g: 238, b: 238 },
+  { name: 'palevioletred', r: 219, g: 112, b: 147 },
+  { name: 'papayawhip', r: 255, g: 239, b: 213 },
+  { name: 'peachpuff', r: 255, g: 218, b: 185 },
+  { name: 'peru', r: 205, g: 133, b: 63 },
+  { name: 'pink', r: 255, g: 192, b: 203 },
+  { name: 'plum', r: 221, g: 160, b: 221 },
+  { name: 'powderblue', r: 176, g: 224, b: 230 },
+  { name: 'purple', r: 128, g: 0, b: 128 },
+  { name: 'rebeccapurple', r: 102, g: 51, b: 153 },
+  { name: 'red', r: 255, g: 0, b: 0 },
+  { name: 'rosybrown', r: 188, g: 143, b: 143 },
+  { name: 'royalblue', r: 65, g: 105, b: 225 },
+  { name: 'saddlebrown', r: 139, g: 69, b: 19 },
+  { name: 'salmon', r: 250, g: 128, b: 114 },
+  { name: 'sandybrown', r: 244, g: 164, b: 96 },
+  { name: 'seagreen', r: 46, g: 139, b: 87 },
+  { name: 'seashell', r: 255, g: 245, b: 238 },
+  { name: 'sienna', r: 160, g: 82, b: 45 },
+  { name: 'silver', r: 192, g: 192, b: 192 },
+  { name: 'skyblue', r: 135, g: 206, b: 235 },
+  { name: 'slateblue', r: 106, g: 90, b: 205 },
+  { name: 'slategray', r: 112, g: 128, b: 144 },
+  { name: 'snow', r: 255, g: 250, b: 250 },
+  { name: 'springgreen', r: 0, g: 255, b: 127 },
+  { name: 'steelblue', r: 70, g: 130, b: 180 },
+  { name: 'tan', r: 210, g: 180, b: 140 },
+  { name: 'teal', r: 0, g: 128, b: 128 },
+  { name: 'thistle', r: 216, g: 191, b: 216 },
+  { name: 'tomato', r: 255, g: 99, b: 71 },
+  { name: 'turquoise', r: 64, g: 224, b: 208 },
+  { name: 'violet', r: 238, g: 130, b: 238 },
+  { name: 'wheat', r: 245, g: 222, b: 179 },
+  { name: 'white', r: 255, g: 255, b: 255 },
+  { name: 'whitesmoke', r: 245, g: 245, b: 245 },
+  { name: 'yellow', r: 255, g: 255, b: 0 },
+  { name: 'yellowgreen', r: 154, g: 205, b: 50 },
+];
+
+/**
+ * sRGB (0-255) -> CIELAB (D65)
+ */
+function srgbToLab(r, g, b) {
+  let lr = r / 255,
+    lg = g / 255,
+    lb = b / 255;
+  lr = lr > 0.04045 ? ((lr + 0.055) / 1.055) ** 2.4 : lr / 12.92;
+  lg = lg > 0.04045 ? ((lg + 0.055) / 1.055) ** 2.4 : lg / 12.92;
+  lb = lb > 0.04045 ? ((lb + 0.055) / 1.055) ** 2.4 : lb / 12.92;
+
+  const x = (lr * 0.4124564 + lg * 0.3575761 + lb * 0.1804375) / 0.95047;
+  const y = lr * 0.2126729 + lg * 0.7151522 + lb * 0.072175;
+  const z = (lr * 0.0193339 + lg * 0.119192 + lb * 0.9503041) / 1.08883;
+
+  const f = (t) => (t > 0.008856 ? t ** (1 / 3) : 7.787 * t + 16 / 116);
+  return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];
+}
+
+const PALETTE_LAB = PALETTE.map((c) => ({
+  ...c,
+  lab: srgbToLab(c.r, c.g, c.b),
+}));
+
+/**
+ * Returns the closest W3C color name for given RGB values.
+ */
+export function rgbToColorName(r, g, b) {
+  const [L1, a1, b1] = srgbToLab(r, g, b);
+  let minDe = Infinity,
+    closest = 'black';
+
+  for (const c of PALETTE_LAB) {
+    const [L2, a2, b2] = c.lab;
+    const de = Math.sqrt((L1 - L2) ** 2 + (a1 - a2) ** 2 + (b1 - b2) ** 2);
+    if (de < minDe) {
+      minDe = de;
+      closest = c.name;
+    }
+  }
+  return closest;
+}
+
+/**
+ * Parses CSS color string to W3C named color.
+ * Migrated from grid.js parseColor().
+ *
+ * §H9 P3 MESS-GRANULARITÄT: parseColor IST der Mess-Farbraum des Systems —
+ * jede numerische Farbe (hex/rgb) wird auf den NÄCHSTEN der 140 W3C-Namen
+ * quantisiert (CIELAB-Distanz, rgbToColorName). Konsequenz für Vergleiche
+ * (z.B. COLOR-Constraint): Hexes derselben Palette-Zelle sind GLEICH
+ * (#ff0000 ≡ #ff0001 ≡ 'red'), Hexes verschiedener Zellen verschieden
+ * (#ff0000 'red' ≢ #ff6347 'tomato'). Bewusste Mess-Granularität — eine
+ * hex-exakte Unterscheidung wäre ein eigener Kanal (Design-Runde), keine
+ * stille Änderung dieses Quantisierers.
+ */
+export function parseColor(css) {
+  if (!css || css === 'none' || css === 'rgba(0, 0, 0, 0)')
+    return 'transparent';
+  if (css === 'indeterminate') return 'indeterminate'; // §HEAL3b: ehrlicher Nicht-Mess-Token, erstklassig
+  if (css.startsWith('url(')) return 'gradient';
+  // §H9 K-08a: Hex-Formen (#rgb/#rrggbb) sind verlustfrei nach rgb auflösbar
+  // und werden in DENSELBEN Namensraum quantisiert wie die Mess-Seite
+  // (rgbToColorName/CIELAB) — kein zweites Farbsystem, keine Toleranz-Schwelle.
+  // Andere Token fallen wie bisher unverändert durch (Fallback unten).
+  const hex = css.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (hex) {
+    const h =
+      hex[1].length === 3
+        ? hex[1].replace(/./g, (c) => c + c)
+        : hex[1];
+    return rgbToColorName(
+      parseInt(h.slice(0, 2), 16),
+      parseInt(h.slice(2, 4), 16),
+      parseInt(h.slice(4, 6), 16),
+    );
+  }
+  const match = css.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+  if (match)
+    return rgbToColorName(
+      parseInt(match[1], 10),
+      parseInt(match[2], 10),
+      parseInt(match[3], 10),
+    );
+  return css;
+}

package/src/lib/transforms.js

@@ -0,0 +1,111 @@
+/**
+ * transforms.js — SVG transform-Token-Algebra (Hexagonal-rein, lib/-Schicht)
+ * Vector Mirror v2.6 · Sprint §1.5 Transform-Fallback
+ *
+ * lib-Modul (REGEL-4 Hexagonal): pure Funktionen, KEINE Importe aus adapters/
+ * oder interface/. Konsumenten: pipeline.js (arrange-Pfad) + structured.js
+ * (Emitter §1.5 Transform-Fallback).
+ *
+ * Extraktion aus pipeline.js (§1.5 Block B): buildTransform + hasTranslateTransform
+ * lebten im Orchestrator; der Emitter braucht sie für den Transform-Fallback.
+ * Verschiebung in lib/ macht sie für beide Schichten importierbar, ohne dass der
+ * Emitter den Orchestrator zieht (Hexagonal-Layering).
+ *
+ * ── Zwei Translate-Merge-Semantiken (R-A-Auflösung §1.5, bewusst getrennt) ──
+ *   buildTransform   (REPLACE-IN-PLACE): translate ersetzt den bestehenden
+ *     translate-Token an dessen Original-Position (bzw. Listenanfang, wenn keiner
+ *     existiert). Korrekt für arrange(): dort sind dx/dy Deltas im LOKALEN,
+ *     un-transformierten Element-Koordinatensystem (state.bbox ist die deklarierte
+ *     Local-BBox, NICHT die CTM-projizierte). Der Autor-transform (scale/rotate)
+ *     bleibt als Kontext erhalten — Erhalt der Autor-Intention.
+ *     Empirie-Anker: test_arrange.js:428 'rotate(45) translate(5 6) scale(2)'
+ *     → 'rotate(45) translate(140 280) scale(2)'.
+ *
+ *   prependTranslate (FRONT-PREPEND): translate steht IMMER am Listenanfang
+ *     (zuletzt angewendet = wirkt in finaler Welt-Koordinate). Korrekt für den
+ *     §1.5-Position-Fix: dort kommen dx/dy vom Spotter, berechnet auf der
+ *     CTM-PROJIZIERTEN Welt-BBox. Die Gegenbewegung muss außen wrappen, damit sie
+ *     unabhängig von einem Autor-scale()/rotate() in Welt-px wirkt (SOTA Präzision 1).
+ *
+ * Beide Funktionen entfernen vorhandene translate-Tokens VOR dem Insert →
+ * Idempotenz (G-14): wiederholte Anwendung mit gleichem dx/dy ist Fixpunkt.
+ */
+
+/**
+ * True, wenn der transform-String einen translate/translateX/translateY/
+ * translateZ-Token trägt. Case-insensitiv; tolerant gegen null/undefined.
+ */
+export function hasTranslateTransform(transform) {
+  return /\btranslate[XYZ]?\s*\(/i.test(transform ?? '');
+}
+
+/**
+ * Zerlegt einen transform-String in Funktions-Tokens (z.B. ['rotate(45)',
+ * 'scale(2)']). Liefert null, wenn kein Token erkennbar ist.
+ */
+function tokenize(transform) {
+  const trimmed = transform?.trim();
+  if (!trimmed) return [];
+  return trimmed.match(/[a-zA-Z]+\s*\([^)]*\)/g);
+}
+
+/**
+ * buildTransform (REPLACE-IN-PLACE) — siehe Modul-Doku.
+ * Setzt translate(dx dy) an die Position des ersten bestehenden translate-Tokens
+ * (oder an den Listenanfang, wenn keiner existiert) und entfernt alle übrigen
+ * translate-Tokens. Erhält die relative Ordnung der Nicht-translate-Tokens.
+ *
+ * @param {string|undefined} existingTransform - bestehender transform-Attribut-Wert.
+ * @param {number} dx - X-Verschiebung.
+ * @param {number} dy - Y-Verschiebung.
+ * @returns {string} neuer transform-String.
+ */
+export function buildTransform(existingTransform, dx, dy) {
+  const translate = `translate(${dx} ${dy})`;
+  const trimmed = existingTransform?.trim();
+  if (!trimmed) return translate;
+
+  const tokens = tokenize(trimmed);
+  if (!tokens) return `${translate} ${trimmed}`;
+
+  const nextTokens = [];
+  let translateIndex = null;
+
+  for (const token of tokens) {
+    if (/^translate[XYZ]?\s*\(/i.test(token)) {
+      if (translateIndex === null) translateIndex = nextTokens.length;
+      continue;
+    }
+    nextTokens.push(token.trim());
+  }
+
+  const insertAt = translateIndex ?? 0;
+  nextTokens.splice(insertAt, 0, translate);
+  return nextTokens.join(' ').trim();
+}
+
+/**
+ * prependTranslate (FRONT-PREPEND) — siehe Modul-Doku.
+ * Stellt translate(dx dy) IMMER an den Listenanfang und entfernt alle
+ * bestehenden translate-Tokens (Idempotenz). Erhält die relative Ordnung der
+ * Nicht-translate-Tokens hinter dem neuen translate.
+ *
+ * Für den §1.5-Position-Fix: dx/dy sind Welt-px-Deltas, die außen wrappen
+ * müssen, damit sie unabhängig von Autor-scale()/rotate() wirken.
+ *
+ * @param {string|undefined} existingTransform - bestehender transform-Attribut-Wert.
+ * @param {number} dx - X-Verschiebung in Welt-px.
+ * @param {number} dy - Y-Verschiebung in Welt-px.
+ * @returns {string} neuer transform-String, beginnt mit 'translate('.
+ */
+export function prependTranslate(existingTransform, dx, dy) {
+  const translate = `translate(${dx} ${dy})`;
+  const tokens = tokenize(existingTransform);
+  if (!tokens || tokens.length === 0) return translate;
+
+  const kept = tokens
+    .filter((token) => !/^translate[XYZ]?\s*\(/i.test(token))
+    .map((token) => token.trim());
+
+  return [translate, ...kept].join(' ').trim();
+}