vector-mirror 1.0.0

package/src/core/diff.js

@@ -0,0 +1,118 @@
+/**
+ * diff.js - Diff Computation between GridMaps
+ * Migrated from mirror.js:113-147 + findClosest (164-172)
+ * Vector Mirror v2.0
+ *
+ * Core module: NO imports from adapters/ or interface/
+ */
+
+/**
+ * Computes changes between two GridMaps.
+ * Phase 1: Exact ID matching. Phase 2: Proximity matching.
+ */
+export function computeDiff(oldMap, newMap) {
+  const changes = [];
+  const matchedOldIds = new Set();
+  const matchedNewIds = new Set();
+
+  // Phase 1: Exact Match (IDs)
+  for (const newEl of newMap.elements) {
+    const oldEl = oldMap.elements.find((e) => e.id === newEl.id);
+    if (oldEl) {
+      matchedOldIds.add(oldEl.id);
+      matchedNewIds.add(newEl.id);
+      // Sniper-Identität: eine Form-Mutation (circle→ellipse) bei gleicher
+      // Zelle/Farbe ist eine echte Szenen-Änderung — ohne diesen Vergleich
+      // bliebe sie still (leerer Diff = Mess-Lüge). Exakt im Muster von
+      // VERSCHOBEN/FARBÄNDERUNG (oldEl = matched Vorgänger).
+      if (oldEl.tag !== newEl.tag)
+        changes.push({
+          type: 'FORMÄNDERUNG',
+          id: newEl.id,
+          from: oldEl.tag,
+          to: newEl.tag,
+        });
+      if (oldEl.cell !== newEl.cell)
+        changes.push({
+          type: 'VERSCHOBEN',
+          id: newEl.id,
+          from: oldEl.cell,
+          to: newEl.cell,
+        });
+      if (oldEl.color !== newEl.color)
+        changes.push({
+          type: 'FARBÄNDERUNG',
+          id: newEl.id,
+          from: oldEl.color,
+          to: newEl.color,
+        });
+    }
+  }
+
+  // Phase 2: Proximity Matching for unmatched
+  const unmatchedOld = oldMap.elements.filter((e) => !matchedOldIds.has(e.id));
+  const unmatchedNew = newMap.elements.filter((e) => !matchedNewIds.has(e.id));
+
+  for (const newEl of unmatchedNew) {
+    const candidate = findClosest(newEl, unmatchedOld, oldMap.grid);
+    if (candidate) {
+      matchedOldIds.add(candidate.id);
+      unmatchedOld.splice(unmatchedOld.indexOf(candidate), 1);
+      // Symmetrisch zu Phase 1: Form-Mutation ist eine echte Änderung, nicht
+      // still. (Heute matcht findClosest nur tag-gleich, der Zweig ist also
+      // eine Sicherung gegen künftiges tag-agnostisches Matching — kein toter
+      // Pfad an der API-Grenze, sondern dieselbe Wahrheit in beiden Phasen.)
+      if (candidate.tag !== newEl.tag)
+        changes.push({
+          type: 'FORMÄNDERUNG',
+          id: newEl.id,
+          from: candidate.tag,
+          to: newEl.tag,
+        });
+      if (newEl.cell !== candidate.cell)
+        changes.push({
+          type: 'VERSCHOBEN',
+          id: newEl.id,
+          from: candidate.cell,
+          to: newEl.cell,
+        });
+      if (newEl.color !== candidate.color)
+        changes.push({
+          type: 'FARBÄNDERUNG',
+          id: newEl.id,
+          from: candidate.color,
+          to: newEl.color,
+        });
+    } else {
+      changes.push({
+        type: 'NEU',
+        id: newEl.id,
+        cell: newEl.cell,
+        color: newEl.color,
+      });
+    }
+  }
+
+  unmatchedOld.forEach((oldEl) => {
+    changes.push({ type: 'ENTFERNT', id: oldEl.id, cell: oldEl.cell });
+  });
+  return changes;
+}
+
+/**
+ * Finds the closest element by tag + distance within 2 cell threshold.
+ * Private to diff module (DDD Shared Kernel, ADR C-1).
+ */
+function findClosest(target, candidates, grid) {
+  let best = null,
+    minD = Math.max(grid.cellW, grid.cellH) * 2;
+  candidates.forEach((c) => {
+    if (c.tag !== target.tag) return;
+    const d = Math.sqrt((target.cx - c.cx) ** 2 + (target.cy - c.cy) ** 2);
+    if (d < minD) {
+      minD = d;
+      best = c;
+    }
+  });
+  return best;
+}

package/src/core/element_vocabulary.js

@@ -0,0 +1,241 @@
+/**
+ * element_vocabulary.js — SSOT für Element-Vokabular (Sprint-β2 §1.3 LAYER-TRENNUNG)
+ * Vector Mirror v2.6
+ *
+ * Core module (REGEL-4 Hexagonal): lebt in core/, darf aus core/ + node:* importieren,
+ *   wird von adapters/* und tests/* konsumiert; importiert NICHT aus adapters/ oder interface/.
+ *
+ * Layer-Trennung (Patch2, Mini-Review-Konvergenz Opus+Codex):
+ *   - DOMAIN-Layer:  isSpotterTag(tag) Predicate + AUTO_ID_FORMAT_REGEX (hier).
+ *   - FORMAT-Layer:  formatAutoId/extractAutoIds/computeSvgHashPrefix in auto_ids.js
+ *                    (pure Format-Helper, keine Domain-Listen).
+ *
+ * Begründung Predicate-API (F-PATCH-CODEX-001 + F-OPUS-MINI-002 konvergent):
+ *   `Object.freeze(new Set(...))` ist auf V8 SCHEIN-Defensive — interne Set-Slots
+ *   sind nicht via Property-Descriptor geschützt, `set.add(...)` läuft trotzdem
+ *   durch. Konsequenz: das Set in Modul-Scope PRIVAT halten, nur als Predicate
+ *   nach aussen geben → keine externe Mutation möglich (V8-mechanisch).
+ *
+ * Tag-Wahl SPOTTER-Set (15 Tags, MDN-Renderable minus pure Container):
+ *   - Wurzel-Quelle: MDN <https://developer.mozilla.org/en-US/docs/Web/SVG/Element>
+ *     "Renderable elements" — Elemente, die grafische Ausgabe erzeugen können.
+ *   - Pure Container ausgenommen: <g>, <svg>, <symbol> (haben keine eigene Geometrie,
+ *     ihre Geometrie ist die ihrer Kinder; in SKIP_TAGS).
+ *   - Inkludiert: a, circle, ellipse, foreignObject, image, line, path, polygon,
+ *     polyline, rect, switch, text, textPath, tspan, use.
+ *   - Adressiert F-OPUS-MINI-001 (Verhaltens-Drift): vor Patch1 lieferte
+ *     getStablePath() für ALLE non-SKIP-Tags eine ID, der Spotter sah <a>,
+ *     <switch>, <textPath>, <tspan>. Patch1 mit 10er-Liste droppte diese stumm.
+ *   - <foreignObject> Defensive: DOMPurify USE_PROFILES.svg strippt aktuell,
+ *     aber Profile-Erweiterung ist zukünftige Möglichkeit — Predicate ist
+ *     dann ohne Code-Änderung korrekt.
+ *
+ * Wurzel-Fix für F-CODEX-002 (Tag-Allowlist nicht erzwungen) + SC-4-Drift
+ * (Format-Regex nicht ausführbar grep-bar): 4 Reviewer (Validator + Opus
+ * + Gemini + Codex) konvergent fanden 4 widersprüchliche Tag-Listen verstreut
+ * im Code. Die Synthese identifizierte als Wurzel: "Kein Single-Source-of-
+ * Truth für Element-Vokabular".
+ *
+ * Pattern-Vorlage: fabric.js
+ * `parser/constants.ts` (zentrale Constants, alle Konsumenten importieren).
+ *
+ * Quellen für die übrigen Sets:
+ *   - SKIP_TAGS: Spotter-Negativ-Liste — semantisch nicht-geometrisch oder
+ *     Container/Definitions/Style/Script. Disjunkt-Konstellation: SKIP_TAGS
+ *     und das (private) Spotter-Set überlappen nicht.
+ *   - DELTA_ATTRIBUTABLE_TAGS: Untermenge des Spotter-Sets, für die der
+ *     Emitter (structured.js) eine delta-zu-Attribut-Mapping kennt
+ *     (Subset-Drift-Test via isSpotterTag-Predicate).
+ *
+ * Format-Vertrag (AUTO_ID_FORMAT_REGEX):
+ *   Aus _SPOTTER_SET dynamisch abgeleitet — Drift ist mechanisch ausgeschlossen,
+ *   weil die Regex bei Vokabular-Änderung automatisch folgt.
+ */
+
+/**
+ * Privates Spotter-Set (15 Tags). NICHT exportiert — nur über isSpotterTag()
+ * und AUTO_ID_FORMAT_REGEX zugänglich. Damit ist externe Mutation
+ * V8-mechanisch ausgeschlossen (Predicate hat keine .add/.delete-Surface).
+ *
+ * Case-Konvention (Patch3, F-PATCH2-OPUS-001 + F-PATCH2-CODEX-001 konvergent
+ * HIGH): ALLE Tokens lowercase. Begründung — Browser-DOM-API liefert über
+ * `el.tagName.toLowerCase()` einheitlich lowercase (HTML-Konvention; im
+ * SVG-Namespace ist tagName zwar case-preserving, aber Renderer-Adapter
+ * normalisiert defensiv). Vorherige Patch2-Schreibweise (`foreignObject`,
+ * `textPath` camelCase) erzeugte Asymmetrie zum Browser-Pfad, weshalb diese
+ * beiden Tags im Renderer stumm gedropt wurden. Lowercase-everywhere ist
+ * die kanonische Single-Boundary-Normalisierung (kein Lookup-Table,
+ * SKIP_TAGS war ohnehin schon lowercase — Symmetrie hergestellt).
+ *
+ * Reihenfolge: alphabetisch (Determinismus für die abgeleitete Regex-Alternation).
+ */
+const _SPOTTER_SET = new Set([
+  'a',
+  'circle',
+  'ellipse',
+  'foreignobject',
+  'image',
+  'line',
+  'path',
+  'polygon',
+  'polyline',
+  'rect',
+  'switch',
+  'text',
+  'textpath',
+  'tspan',
+  'use',
+]);
+
+/**
+ * Predicate: ist `tag` ein Spotter-Tag (geometrisch messbar via getBBox,
+ * kein purer Container)? O(1) Set-Lookup auf privates Set.
+ *
+ * Konsumenten (playwright.js Browser-Scope, Tests): nutzen diesen Predicate
+ * statt eines Set-Exports — das verhindert die V8-Set-Mutation-Lücke
+ * (F-PATCH-CODEX-001 + F-OPUS-MINI-002).
+ *
+ * Hinweis Browser-Bridge (playwright.js): Predicate-Funktionen können nicht
+ * über page.evaluate() seriali­siert werden. Adapter berechnet stattdessen
+ * EINMAL `[..._SPOTTER_SET]` indirekt via `isSpotterTag`-Probing über eine
+ * bekannte Tag-Liste ODER importiert eine separate Liste vom Renderer-
+ * Adapter-Lifecycle. ABER: hier in core/ exportieren wir bewusst nur den
+ * Predicate. Renderer-Bridge-Strategie ist Adapter-Sache (siehe playwright.js).
+ *
+ * Case-Defensive (Patch3): Input wird via `String(tag).toLowerCase()`
+ * normalisiert. Damit liefert der Predicate für `textPath`, `textpath`
+ * und `TEXTPATH` einheitlich `true`. Non-String Inputs (null, undefined,
+ * Zahlen) werden via `String(...)` zu ihrer String-Repräsentation
+ * koerciert (`"null"`, `"undefined"`, `"123"`) und matchen damit das Set
+ * NICHT — funktional false ohne Exception. Bewusste Wahl: defensiv
+ * statt strikt, weil der Browser-Pfad in einer Promise-Chain läuft und
+ * unerwartete TypeError-Throws schwer zu lokalisieren wären.
+ *
+ * @param {string} tag - SVG-Element-Tag in beliebiger Schreibweise;
+ *   Predicate normalisiert intern via toLowerCase().
+ * @returns {boolean} true wenn Spotter sehen soll, false sonst.
+ */
+export function isSpotterTag(tag) {
+  return _SPOTTER_SET.has(String(tag).toLowerCase());
+}
+
+/**
+ * Frozen Snapshot-Array des Spotter-Sets, AUSSCHLIESSLICH für die Renderer-
+ * Adapter-Bridge (playwright.js → page.evaluate). Sets sind nicht JSON-
+ * serialisierbar, Predicate-Funktionen nicht über page.evaluate übertragbar
+ * (Browser-Sandbox-Boundary, H-10/PH-10). Daher diese Array-API: Adapter
+ * serialisiert sie als Arg-Pass, der Browser-Scope rekonstruiert ein eigenes
+ * Set über `new Set(arr)` (mutation-isoliert vom Node-Land).
+ *
+ * Object.freeze auf einem Array IST effektiv: push/pop/splice werfen im
+ * strict-mode bzw. werden silent verworfen. Im Gegensatz zu Set ist das
+ * V8-Mutations-Lock hier real (Property-Descriptor sperrt length + Indizes).
+ *
+ * Reihenfolge: dieselbe wie _SPOTTER_SET (alphabetisch). Tests dürfen sich
+ * NICHT auf eine bestimmte Reihenfolge verlassen — die Liste ist semantisch
+ * ein Set, der Array-Wrapper ist Serialisierungs-Trick.
+ *
+ * Case-Garantie (Patch3): Liste ist via `[..._SPOTTER_SET]` direkt aus dem
+ * lowercase-Set abgeleitet — jedes Element ist lowercase. Drift-Guard in
+ * playwright.js verifiziert das zusätzlich Build-/Runtime (Case-Invariante).
+ *
+ * Konsumenten-Hinweis: Code, der über die Tag-Mitgliedschaft entscheiden
+ * muss, soll `isSpotterTag(tag)` benutzen, NICHT diese Liste iterieren.
+ * Die Liste ist nur das Bridge-Snapshot zur Browser-Sandbox.
+ */
+export const SPOTTER_TAGS_LIST = Object.freeze([..._SPOTTER_SET]);
+
+/**
+ * Skip-Tags: Renderer-seitige Negativ-Liste (playwright.js iteriert
+ * darüber hinweg). Container (`g`, `svg`, `symbol`), Definitions (`defs`,
+ * `marker`), Style/Script/Metadata sowie Mask/Clip/Filter — keiner davon
+ * trägt eigene Geometrie, die der Spotter messen soll.
+ *
+ * Bleibt als Set-Export, weil die Browser-Bridge die Liste iteriert
+ * (`new Set(skipTagsArr)` im Browser-Scope, Mutation in core ist nicht
+ * Trust-Boundary). pattern/svg/marker/symbol sind hier nicht alle drin —
+ * sie werden durch `!isSpotterTag(tag)` ohnehin dynamisch geskippt; SKIP_TAGS
+ * ist die EXPLIZITE Liste der Tags, die playwright.js per Fast-Path früh
+ * verwirft (vor jeder Style/BBox-Inspektion).
+ *
+ * §HEAL3 (ST-A) Doku-Schuld (HEAL §7-4): `pattern` fehlt hier BEWUSST und
+ * BLEIBT es — SKIP_TAGS unterdrückt nur die Container SELBST, nicht deren
+ * KINDER (das <rect> IN einem <defs>/<symbol>/<clipPath>/<pattern>), die als
+ * Phantome durchrutschen würden. Der kategorische closest()-Schnitt in
+ * playwright.js (`el.closest('defs,symbol,clipPath,mask,pattern,marker')`)
+ * deckt BEIDE Lecks zugleich: die fehlende Container-Mitgliedschaft (pattern)
+ * UND die Container-Kinder. Daher KEINE Erweiterung von SKIP_TAGS nötig —
+ * das wäre eine zweite, falsche Vergleichs-Ebene (SKIP_TAGS testet gegen
+ * tagName.toLowerCase() → lowercase `clippath`; closest() matcht den
+ * qualifizierten SVG-Namen → camelCase `clipPath`). NICHT vermischen.
+ */
+export const SKIP_TAGS = Object.freeze(
+  new Set([
+    'defs',
+    'title',
+    'desc',
+    'metadata',
+    'style',
+    'script',
+    'g',
+    'filter',
+    'clippath',
+    'mask',
+    'symbol',
+    'marker',
+    'stop',
+  ]),
+);
+
+/**
+ * Delta-attributable Tags: Untermenge des Spotter-Sets, für die der
+ * Emitter (structured.js `deltaToAttribute`) eine dx/dy/dw/dh→Attribut-
+ * Mapping vorhält. Subset-Invariante zum Spotter-Set (Drift-Test in
+ * test_element_vocabulary.js prüft `every tag => isSpotterTag(tag)`).
+ *
+ * Bleibt als Set-Export, weil der Drift-Test iteriert.
+ */
+export const DELTA_ATTRIBUTABLE_TAGS = Object.freeze(
+  new Set(['circle', 'rect', 'text', 'ellipse', 'line', 'image']),
+);
+
+/**
+ * Predicate: trägt `tag` eine native dx/dy/dw/dh→Attribut-Mapping (= ist er in
+ * DELTA_ATTRIBUTABLE_TAGS)? Single-Point-of-Truth für die §1.5-Verzweigung in
+ * structured.js buildFix: JA → bestehender Attribut-Pfad (x/y/cx/cy/r/...),
+ * NEIN → Transform-Fallback (translate) bzw. SIZE_FIX_UNSUPPORTED_FOR_TAG.
+ *
+ * Symmetrisch zu isSpotterTag: normalisiert Input via String(tag).toLowerCase()
+ * (Browser-Pfad liefert lowercase; defensive Koerzierung für null/undefined/
+ * Zahlen → false ohne Throw).
+ *
+ * @param {string} tag - SVG-Element-Tag in beliebiger Schreibweise.
+ * @returns {boolean} true wenn der Tag eine native Delta-Attribut-Mapping hat.
+ */
+export function isTagDeltaAttributable(tag) {
+  return DELTA_ATTRIBUTABLE_TAGS.has(String(tag).toLowerCase());
+}
+
+/**
+ * Auto-ID-Format-Regex — aus _SPOTTER_SET DYNAMISCH abgeleitet.
+ *
+ * Format-Vertrag (D-004, ADR-025 §3): `_<8hex>_<tag><n>` mit
+ *   <tag> ∈ Spotter-Set, <8hex> = lowercase hex (sha256-Prefix),
+ *   <n>   = monoton steigender, tag-lokaler Counter (1-basiert).
+ *
+ * Drift-Garantie: wenn _SPOTTER_SET sich ändert, folgt die Regex
+ * AUTOMATISCH — keine zweite, hardcoded Liste pflegen.
+ *
+ * Case-Konvention (Patch3, F-PATCH2-OPUS-001 + F-PATCH2-CODEX-001): kanonische
+ * Auto-ID-Schreibweise ist lowercase. Begründung — _SPOTTER_SET ist
+ * lowercase, Renderer (playwright.js) baut Auto-IDs aus tag-lowercase +
+ * hash-prefix-lowercase + zähler. Damit ist die Auto-ID kanonisch
+ * lowercase, und die Format-Regex ist deterministisch case-sensitive
+ * (kein `i`-Flag mehr). Das `i`-Flag aus Patch2 war kompensatorisch zur
+ * camelCase-Set-Asymmetrie; mit lowercase-everywhere ist die Asymmetrie
+ * eliminiert. Konsequenz: `_deadbeef_foreignObject1` matcht nicht mehr —
+ * solche IDs sind per Vertrag nicht produzierbar (Renderer normalisiert).
+ */
+export const AUTO_ID_FORMAT_REGEX = new RegExp(
+  `^_[0-9a-f]{8}_(${[..._SPOTTER_SET].join('|')})\\d+$`,
+);

package/src/core/grid.js

@@ -0,0 +1,240 @@
+/**
+ * grid.js - Grid Mapping & Offset Correction
+ * Migrated from grid.js (v1.6), parseColor moved to lib/palette.js
+ * Vector Mirror v2.0
+ *
+ * Core module: NO imports from adapters/ or interface/
+ */
+import { parseColor } from '../lib/palette.js';
+
+export function mapToGridMap(resolved, lastGridMap = null) {
+  const { canvas, elements } = resolved;
+  const grid = createGrid(canvas);
+
+  const mappedElements = elements.map((el) => {
+    const cx = el.bbox.x + el.bbox.w / 2;
+    const cy = el.bbox.y + el.bbox.h / 2;
+
+    const col = clamp(
+      Math.floor((cx - canvas.vbX) / grid.cellW),
+      0,
+      grid.cellsX - 1,
+    );
+    const row = clamp(
+      Math.floor((cy - canvas.vbY) / grid.cellH),
+      0,
+      grid.cellsY - 1,
+    );
+
+    let cell = String.fromCharCode(65 + col) + (row + 1);
+
+    // Hysteresis (10% Overlap Rule)
+    if (lastGridMap) {
+      const lastEl = lastGridMap.elements.find((e) => e.id === el.id);
+      if (lastEl && lastEl.cell !== cell) {
+        const overlap = cellOverlapRatio(
+          el.bbox,
+          col,
+          row,
+          grid,
+          canvas.vbX,
+          canvas.vbY,
+        );
+        if (overlap < 0.1) cell = lastEl.cell;
+      }
+    }
+
+    const xInCell = (cx - canvas.vbX - col * grid.cellW) / grid.cellW;
+    const yInCell = (cy - canvas.vbY - row * grid.cellH) / grid.cellH;
+    const direction = getDirection(xInCell, yInCell);
+    const span = computeSpan(el.bbox, grid, canvas.vbX, canvas.vbY);
+
+    return {
+      id: el.id,
+      tag: el.tag,
+      cell,
+      direction,
+      span,
+      // §F-AT-7-02 STILLE STROKE-FARB-LÜGE (Heilung, Opt-A-Kern). Die EINE `color`
+      // war fill-only — ein nur-stroke-sichtbares Element meldete `transparent`
+      // (Lese-Lüge). Wenn der Renderer visible_color_source='stroke' gemessen hat
+      // (fill trägt keine sichtbare Farbe bei, stroke malt sichtbar), wird die EINE
+      // sichtbare Farbe aus el.stroke projiziert — kein Layer-Crossing (grid.js
+      // importiert nur palette.js), reine Projektion eines bereits gemessenen
+      // Signals. Bei 'multiple' (beide sichtbar) bleibt color=fill (Status quo); die
+      // MULTIPLE_PAINT_SOURCES-Warning trägt dort die Wahrheit (Visions-Gate: keine
+      // willkürliche Einzel-Farbe küren). SK4: der echte parsed fill wird INTERN in
+      // fill_color separat bewahrt — die Palette (structured.js) liest fill_color,
+      // NICHT color, sonst entstünde eine neue Lüge (stroke-only → fill:rot).
+      color:
+        el.visible_color_source === 'stroke'
+          ? parseColor(el.stroke)
+          : parseColor(el.fill),
+      fill_color: parseColor(el.fill),
+      stroke: parseColor(el.stroke),
+      opacity: el.opacity,
+      bbox: el.bbox,
+      cx: Math.round(cx),
+      cy: Math.round(cy),
+      textContent: el.textContent,
+      // §1.2b L-002a: bbox_reliability + warnings vom Renderer-Element durchreichen
+      // (REGEL-3 Spotter-Anti-Luege auf MCP-Caller-Ebene). Reine Daten-Durchreichung,
+      // kein Layer-Crossing (H-16 REGEL-4 Hexagonal: core/ importiert weiter nichts
+      // aus adapters/ oder interface/).
+      bbox_reliability: el.bbox_reliability,
+      // §1.5 Block G: parent_id/parent_tag vom Renderer-Element durchreichen
+      // (tspan/textPath-Kontext, R-C). EXAKT analog zum warnings-Muster oben:
+      // conditional-spread, nur wenn vorhanden (Top-Level-Elemente tragen sie
+      // nicht). Reine Daten-Durchreichung, kein Layer-Crossing.
+      ...(el.parent_id != null ? { parent_id: el.parent_id } : {}),
+      ...(el.parent_tag != null ? { parent_tag: el.parent_tag } : {}),
+      // §1.5 Block H / Patch P1+P2: Autor-transform + tspan native_dx durchreichen
+      // (gleiches conditional-spread-Muster). transform → buildTransformFix.current
+      // (Autor-scale/rotate-Erhalt); native_dx → buildTspanShiftFix-Relativbasis.
+      ...(el.transform != null ? { transform: el.transform } : {}),
+      ...(el.native_dx != null ? { native_dx: el.native_dx } : {}),
+      ...(el.warnings ? { warnings: el.warnings } : {}),
+      // §E4 (F-AT-004, DoD-3): Paint-Extent-Ehrlichkeit vom Renderer-Element
+      // durchreichen — EXAKT dasselbe conditional-spread-Muster wie bbox_reliability/
+      // parent_id/transform/warnings oben. REINE Daten-Durchreichung: die geom-bbox-
+      // basierte cell/span/cx/cy/direction-Abbildung bleibt UNVERÄNDERT (VISION P3:
+      // der Konsument/das Gehirn entscheidet, was es mit dem Flag tut). Kein
+      // Layer-Crossing (REGEL-4: grid.js importiert weiter nichts aus adapters/).
+      ...(el.has_paint_overflow != null
+        ? { has_paint_overflow: el.has_paint_overflow }
+        : {}),
+      ...(el.visual_bbox != null ? { visual_bbox: el.visual_bbox } : {}),
+      // §HEAL-R6 / T1 (F-AT-6-01, DoD-2): Paint-Presence-Felder durchreichen —
+      // EXAKT dasselbe conditional-spread-Muster (REINE Daten-Durchreichung, kein
+      // Layer-Crossing; core/ importiert weiter nichts aus adapters/interface).
+      // fill/stroke_paint_factor sind immer vorhanden (Diagnostik); paint_visible
+      // nur bei painted===false (Negativ-Kontrolle: sichtbare Elemente tragen es nicht).
+      ...(el.fill_paint_factor != null
+        ? { fill_paint_factor: el.fill_paint_factor }
+        : {}),
+      ...(el.stroke_paint_factor != null
+        ? { stroke_paint_factor: el.stroke_paint_factor }
+        : {}),
+      ...(el.paint_visible != null ? { paint_visible: el.paint_visible } : {}),
+      // §D5 / R6-STATE (state_dependent): reine Daten-Durchreichung (REGEL-4, kein
+      // Layer-Crossing). grid baut das Element-Objekt NEU — ohne diese Zeile ist das
+      // Feld downstream undefined. Die Warning fließt schon via warnings@81.
+      ...(el.state_dependent != null
+        ? { state_dependent: el.state_dependent }
+        : {}),
+      // §F-AT-6-09 / R6-MEDIA (media_dependent): reine Daten-Durchreichung (REGEL-4,
+      // kein Layer-Crossing). grid baut das Element-Objekt NEU — ohne diese Zeile ist
+      // das Feld downstream undefined. Die Warning fließt schon via warnings@81.
+      ...(el.media_dependent != null
+        ? { media_dependent: el.media_dependent }
+        : {}),
+      // §HEAL-5 / Zeit-Achse (motion_dependent): reine Daten-Durchreichung
+      // (REGEL-4, kein Layer-Crossing) — exakt nach media_dependent-Vorlage.
+      // grid baut das Element-Objekt NEU — ohne diese Zeile ist das Feld
+      // downstream undefined (und die Verdikt-Wache in pipeline.js bliebe
+      // blind). Die Warning fließt schon via warnings@oben.
+      ...(el.motion_dependent != null
+        ? { motion_dependent: el.motion_dependent }
+        : {}),
+      // §H10 R11-06 / Paint-Zeit-Achse (paint_time_variant): reine Daten-
+      // Durchreichung (REGEL-4, kein Layer-Crossing) — exakt nach
+      // motion_dependent-Vorlage.
+      ...(el.paint_time_variant != null
+        ? { paint_time_variant: el.paint_time_variant }
+        : {}),
+      // §F-AT-7-02 (SK3): internes Quellen-Feld der sichtbaren Farbe durchreichen —
+      // reine Daten-Durchreichung (REGEL-4, kein Layer-Crossing). Die Prosa nutzt
+      // es für Note/Suffix-Unterdrückung; die Warning (COLOR_FROM_STROKE /
+      // MULTIPLE_PAINT_SOURCES) fließt schon via warnings@oben. KEIN Schema-Feld.
+      ...(el.visible_color_source != null
+        ? { visible_color_source: el.visible_color_source }
+        : {}),
+    };
+  });
+
+  // §H10 R11-01: Existenz-Register (css-unsichtbar geskippte Elemente) vom
+  // Renderer durchreichen — reine Daten-Durchreichung (REGEL-4, kein
+  // Layer-Crossing), optional-by-default (leer/fehlend ⇒ Feld fehlt).
+  return {
+    canvas,
+    grid,
+    elements: mappedElements,
+    ...(Array.isArray(resolved.hidden) && resolved.hidden.length > 0
+      ? { hidden: resolved.hidden }
+      : {}),
+  };
+}
+
+function createGrid(canvas) {
+  const cellsX = clamp(Math.round(canvas.width / 50), 4, 16);
+  const cellsY = clamp(Math.round(canvas.height / 50), 4, 16);
+  return {
+    cellsX,
+    cellsY,
+    cellW: canvas.width / cellsX,
+    cellH: canvas.height / cellsY,
+  };
+}
+
+function cellOverlapRatio(bbox, col, row, grid, vbX, vbY) {
+  const cellX = vbX + col * grid.cellW;
+  const cellY = vbY + row * grid.cellH;
+  const overlapX = Math.max(
+    0,
+    Math.min(bbox.x + bbox.w, cellX + grid.cellW) - Math.max(bbox.x, cellX),
+  );
+  const overlapY = Math.max(
+    0,
+    Math.min(bbox.y + bbox.h, cellY + grid.cellH) - Math.max(bbox.y, cellY),
+  );
+  const area = overlapX * overlapY;
+  const bboxArea = bbox.w * bbox.h;
+  return bboxArea > 0 ? area / bboxArea : 0;
+}
+
+function getDirection(x, y) {
+  const dx = x < 0.25 ? 'LINKS' : x > 0.75 ? 'RECHTS' : null;
+  const dy = y < 0.25 ? 'OBEN' : y > 0.75 ? 'UNTEN' : null;
+  if (!dx && !dy) return 'MITTE';
+  if (dx && dy)
+    return `ECKE-${dy === 'OBEN' ? 'O' : 'U'}${dx === 'LINKS' ? 'L' : 'R'}`;
+  return dx ? `${dx}ER RAND` : `${dy}ER RAND`;
+}
+
+// §H10 R11-04 (O1): die bbox ist das HALBOFFENE Intervall [x, x+w). Der End-
+// Index ist end-exklusiv (ceil(end/cellW) - 1) statt der früheren "-1px"-
+// Pixel-Heuristik, die w>=1 voraussetzte und für Sub-Pixel-Elemente auf/nahe
+// Grid-Linien invertierte Ranges erzeugte ("C3-B2", Ende vor Anfang — Boden-
+// Wahrheit probe_R11-04). Das Math.max(sCol, …) ist Teil der exakten
+// Mathematik (degeneriertes Intervall w=0 → Zelle des Punktes), kein Guard:
+// START<=END ist damit Theorem, nicht Hoffnung. Exakt-auf-Grenze-Verhalten
+// bleibt erhalten (x=0, w=25, cellW=25 → nur Zelle A); <1px-Grenzkreuzer
+// (x=24.9, w=0.3) melden neu ehrlich beide Zellen.
+function computeSpan(bbox, grid, vbX, vbY) {
+  const sCol = clamp(
+    Math.floor((bbox.x - vbX) / grid.cellW),
+    0,
+    grid.cellsX - 1,
+  );
+  const sRow = clamp(
+    Math.floor((bbox.y - vbY) / grid.cellH),
+    0,
+    grid.cellsY - 1,
+  );
+  const eCol = clamp(
+    Math.max(sCol, Math.ceil((bbox.x + bbox.w - vbX) / grid.cellW) - 1),
+    0,
+    grid.cellsX - 1,
+  );
+  const eRow = clamp(
+    Math.max(sRow, Math.ceil((bbox.y + bbox.h - vbY) / grid.cellH) - 1),
+    0,
+    grid.cellsY - 1,
+  );
+  if (sCol === eCol && sRow === eRow) return null;
+  return `${String.fromCharCode(65 + sCol)}${sRow + 1}-${String.fromCharCode(65 + eCol)}${eRow + 1}`;
+}
+
+function clamp(v, min, max) {
+  return Math.max(min, Math.min(max, v));
+}