@litfamily/lithermes 1.0.8 → 1.0.9

package/assets/lithermes-plugin/skills/lit-diagram-drawer/scripts/diagram_geometry.py

@@ -0,0 +1,130 @@
+"""Standard-library parsing and geometry assembly for inline SVG diagrams."""
+
+from __future__ import annotations
+
+import re
+from math import isfinite
+from types import MappingProxyType
+from typing import assert_never
+
+from diagram_records import (
+    Boundary, Marker, ParsedSvg, Rect, Route, Shape, TextBox,
+    _PATH_TOKEN_RE, _clean, _number, _path_segments, attributes, glyph_width,
+)
+
+_SVG_RE = re.compile(r"<svg\b([^>]*)>([\s\S]*?)</svg\s*>", re.IGNORECASE)
+_TAG_RE = re.compile(r"<(rect|circle|line|path|text|polygon)\b([^>]*)>([\s\S]*?)</\1\s*>|<(rect|circle|line|path|polygon)\b([^>]*)/?>", re.IGNORECASE)
+
+def _parse_shape(kind: str, raw_attrs: str, body: str = "") -> Shape | TextBox | None:
+    attrs = attributes(raw_attrs)
+    if kind.lower() == "text":
+        label = _clean(body)
+        if not label:
+            return None
+        size = _number(attrs.get("font-size"), 16)
+        width = glyph_width(label, size)
+        anchor = attrs.get("text-anchor", "start")
+        x = _number(attrs.get("x")) - (width / 2 if anchor == "middle" else width if anchor == "end" else 0)
+        y = _number(attrs.get("y")) - size * 0.82
+        return TextBox(
+            label=label,
+            bounds=Rect(x, y, width, size * 1.22),
+            anchor=(_number(attrs.get("x")), _number(attrs.get("y"))),
+            font_size=size,
+            fill=attrs.get("fill", "#000000"),
+            role=attrs.get("data-role", ""),
+            edge_for=attrs.get("data-edge-for", ""),
+            boundary_for=attrs.get("data-boundary-for", attrs.get("data-group-for", "")),
+        )
+    kind = kind.lower()
+    if kind == "rect":
+        rect = Rect(_number(attrs.get("x")), _number(attrs.get("y")), _number(attrs.get("width")), _number(attrs.get("height")))
+    elif kind == "circle":
+        radius = _number(attrs.get("r"))
+        center_x, center_y = _number(attrs.get("cx")), _number(attrs.get("cy"))
+        rect = Rect(center_x - radius, center_y - radius, radius * 2, radius * 2)
+    else:
+        return None
+    if rect.w <= 2 or rect.h <= 2:
+        return None
+    return Shape(kind, rect, attrs.get("fill", ""), attrs)
+
+
+def _marker_points(body: str) -> tuple[tuple[float, float], ...]:
+    points: list[tuple[float, float]] = []
+    for match in re.finditer(r"<(path|polygon)\b([^>]*)>", body, re.IGNORECASE):
+        attrs = attributes(match.group(2))
+        if match.group(1).lower() == "polygon":
+            values = [float(value) for value in _PATH_TOKEN_RE.findall(attrs.get("points", "")) if not value.isalpha()]
+            points.extend((values[i], values[i + 1]) for i in range(0, len(values) - 1, 2))
+        else:
+            for segment in _path_segments(attrs.get("d", "")):
+                if not points:
+                    points.append((segment[0], segment[1]))
+                points.append((segment[2], segment[3]))
+    return tuple(points)
+
+
+def parse_svg(source: str) -> ParsedSvg:
+    """Parse SVG tags and geometric metadata without invoking a renderer."""
+    matches = tuple(_SVG_RE.finditer(source))
+    svg = "\n".join(match.group(0) for match in matches)
+    first_attrs = attributes(matches[0].group(1)) if matches else MappingProxyType({})
+    try:
+        view_values = [float(value) for value in re.split(r"[\s,]+", first_attrs.get("viewBox", "").strip()) if value]
+    except ValueError:
+        view_values = []
+    view_box = Rect(*view_values) if len(view_values) == 4 else None
+    shapes: list[Shape] = []
+    texts: list[TextBox] = []
+    routes: list[Route] = []
+    line_segments: list[Segment] = []
+    boundaries: list[Boundary] = []
+    for match in _TAG_RE.finditer(svg):
+        kind = match.group(1) or match.group(4)
+        raw_attrs = match.group(2) if match.group(1) else match.group(5) or ""
+        body = match.group(3) or ""
+        if kind is None:
+            continue
+        attrs = attributes(raw_attrs)
+        parsed = _parse_shape(kind, raw_attrs, body)
+        match parsed:
+            case TextBox():
+                texts.append(parsed)
+            case Shape():
+                shapes.append(parsed)
+            case None:
+                pass
+            case unreachable:
+                assert_never(unreachable)
+        if kind.lower() == "line":
+            points = tuple(_number(attrs.get(key), float("nan")) for key in ("x1", "y1", "x2", "y2"))
+            if all(isfinite(value) for value in points):
+                segment = (points[0], points[1], points[2], points[3])
+                if "data-lifeline-for" not in attrs:
+                    line_segments.append(segment)
+                if attrs.get("data-from") and attrs.get("data-to"):
+                    routes.append(Route(attrs["data-from"], attrs["data-to"], attrs.get("data-label", ""), (segment,), attrs.get("marker-start", ""), attrs.get("marker-end", ""), _number(attrs.get("stroke-width"), 1)))
+        if kind.lower() == "rect" and "data-from" in attrs and "data-to" in attrs:
+            continue
+        if kind.lower() == "path" and attrs.get("data-from") and attrs.get("data-to"):
+            segments = _path_segments(attrs.get("d", ""), curve_steps=16)
+            if segments:
+                routes.append(Route(attrs["data-from"], attrs["data-to"], attrs.get("data-label", ""), segments, attrs.get("marker-start", ""), attrs.get("marker-end", ""), _number(attrs.get("stroke-width"), 1)))
+    for shape in shapes:
+        attrs = shape.attributes
+        marker_keys = ("data-trust-boundary", "data-boundary", "data-boundary-name", "data-group-boundary", "data-group-name", "data-group-label", "data-group-id")
+        class_marker = re.search(r"\b(?:boundary|group)(?:[-_][\w-]+)?\b", attrs.get("class", ""), re.IGNORECASE)
+        if shape.kind != "rect" or not any(key in attrs for key in marker_keys) and not class_marker:
+            continue
+        labels = tuple(attrs[key] for key in ("data-trust-boundary", "data-boundary-name", "data-group-boundary", "data-group-name", "data-group-label") if attrs.get(key) and attrs[key] != "true")
+        name = attrs.get("data-group-id", attrs.get("id", labels[0] if labels else "outline"))
+        boundaries.append(Boundary(name, labels, shape.rect, _number(attrs.get("stroke-width"), 1)))
+    markers: dict[str, Marker] = {}
+    for match in re.finditer(r"<marker\b([^>]*)>([\s\S]*?)</marker\s*>", svg, re.IGNORECASE):
+        attrs = attributes(match.group(1))
+        name = attrs.get("id", "")
+        if name:
+            body = match.group(2)
+            markers[name] = Marker(name, _number(attrs.get("refX")), _number(attrs.get("refY")), attrs.get("markerUnits", "strokeWidth"), _marker_points(body), bool(re.search(r"\bz\b|<polygon\b", body, re.IGNORECASE)))
+    return ParsedSvg(source, svg, first_attrs, view_box, tuple(shapes), tuple(texts), tuple(routes), tuple(line_segments), tuple(boundaries), MappingProxyType(markers))

package/assets/lithermes-plugin/skills/lit-diagram-drawer/scripts/diagram_metrics.py

@@ -0,0 +1,166 @@
+"""Dependency-free SVG text, clipping, contrast, and accessibility metrics."""
+
+from __future__ import annotations
+
+from html import unescape
+import math
+from pathlib import Path
+import re
+from typing import TypedDict
+
+from diagram_geometry import ParsedSvg, Rect, parse_svg
+
+
+class ContrastFailure(TypedDict):
+    text: str
+    ratio: float
+
+
+class DiagramMetrics(TypedDict):
+    source: str
+    hasSvg: bool
+    viewBox: Rect | None
+    title: bool
+    desc: bool
+    roleImage: bool
+    ariaLinked: bool
+    textCount: int
+    textOverlaps: int
+    objectOverlaps: int
+    offCanvas: int
+    offCanvasLabels: list[str]
+    arrowCrossings: int
+    contrastFailures: list[ContrastFailure]
+    colors: int
+    largeRadius: int
+    hasShadow: bool
+    fontFamilyPresent: bool
+    localFont: bool
+    fontFileValid: bool
+    visibleText: str
+    type: str
+    sourceBytes: int
+
+
+def _intersects(first: Rect, second: Rect) -> bool:
+    return first.x < second.right - 1 and first.right > second.x + 1 and first.y < second.bottom - 1 and first.bottom > second.y + 1
+
+
+def _contains(first: Rect, second: Rect) -> bool:
+    return first.x <= second.x + 1 and first.y <= second.y + 1 and first.right >= second.right - 1 and first.bottom >= second.bottom - 1
+
+
+def _luminance(color: str) -> float | None:
+    if not re.fullmatch(r"#[0-9a-f]{3}(?:[0-9a-f]{3})?", color, re.IGNORECASE):
+        return None
+    digits = color[1:]
+    if len(digits) == 3:
+        digits = "".join(character * 2 for character in digits)
+    channels = [int(digits[index:index + 2], 16) / 255 for index in (0, 2, 4)]
+    linear = [channel / 12.92 if channel <= 0.04045 else ((channel + 0.055) / 1.055) ** 2.4 for channel in channels]
+    return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2]
+
+
+def contrast_ratio(foreground: str, background: str) -> float | None:
+    """Return WCAG contrast for literal hex colors; unresolved CSS stays unscored."""
+    first, second = _luminance(foreground), _luminance(background)
+    if first is None or second is None:
+        return None
+    return (max(first, second) + 0.05) / (min(first, second) + 0.05)
+
+
+def _visible_text(source: str, parsed: ParsedSvg) -> str:
+    from_svg = "\n".join(re.sub(r"\s+", " ", unescape(re.sub(r"<[^>]*>", " ", match.group(1)))).strip() for match in re.finditer(r"<(?:text|title|desc)\b[^>]*>([\s\S]*?)</(?:text|title|desc)\s*>", parsed.svg, re.IGNORECASE))
+    document = re.sub(r"<head\b[^>]*>[\s\S]*?</head\s*>|<style\b[^>]*>[\s\S]*?</style\s*>|<script\b[^>]*>[\s\S]*?</script\s*>|<svg\b[^>]*>[\s\S]*?</svg\s*>", " ", source, flags=re.IGNORECASE)
+    html_text = re.sub(r"<[^>]*>", " ", unescape(document))
+    html_text = re.sub(r"\s+", " ", html_text).strip()
+    return "\n".join(value for value in (from_svg, html_text) if value)
+
+
+def _line_crossings(parsed: ParsedSvg) -> int:
+    segments = list(dict.fromkeys([*parsed.line_segments, *(segment for route in parsed.routes for segment in route.segments)]))
+    crossings = 0
+    for index, first in enumerate(segments):
+        for second in segments[index + 1:]:
+            a = (first[0], first[1])
+            b = (first[2], first[3])
+            c = (second[0], second[1])
+            d = (second[2], second[3])
+            shared = any(math.hypot(point[0] - other[0], point[1] - other[1]) < 2 for point in (a, b) for other in (c, d))
+            if not shared and _orientation(a, b, c) * _orientation(a, b, d) < 0 and _orientation(c, d, a) * _orientation(c, d, b) < 0:
+                crossings += 1
+    return crossings
+
+
+def _orientation(first: tuple[float, float], second: tuple[float, float], third: tuple[float, float]) -> float:
+    return (second[0] - first[0]) * (third[1] - first[1]) - (second[1] - first[1]) * (third[0] - first[0])
+
+
+def source_metrics(source: str, source_path: str = "<stdin>") -> DiagramMetrics:
+    """Measure accessible text and geometric warning conditions in an SVG document."""
+    parsed = parse_svg(source)
+    view = parsed.view_box
+    geometry = [shape.rect for shape in parsed.shapes] + [text.bounds for text in parsed.texts]
+    off_canvas: list[str] = []
+    if view is not None:
+        for index, rect in enumerate(geometry):
+            if rect.x < view.x - 1 or rect.y < view.y - 1 or rect.right > view.right + 1 or rect.bottom > view.bottom + 1:
+                off_canvas.append(parsed.texts[index - len(parsed.shapes)].label if index >= len(parsed.shapes) else parsed.shapes[index].kind)
+    text_overlaps = sum(_intersects(first.bounds, second.bounds) for index, first in enumerate(parsed.texts) for second in parsed.texts[index + 1:])
+    visible_shapes = [shape for shape in parsed.shapes if not (view is not None and shape.rect.w >= view.w - 2 and shape.rect.h >= view.h - 2)]
+    venn = re.search(r"diagram-venn-(?:light|dark|full)", parsed.attributes.get("id", "")) is not None
+    object_overlaps = 0
+    for index, first in enumerate(visible_shapes):
+        for second in visible_shapes[index + 1:]:
+            venn_pair = venn and first.kind == "circle" and second.kind == "circle"
+            if not venn_pair and _intersects(first.rect, second.rect) and not _contains(first.rect, second.rect) and not _contains(second.rect, first.rect):
+                object_overlaps += 1
+    visible_rects = [shape for shape in parsed.shapes if shape.kind == "rect" and shape.fill.lower() not in {"none", "transparent"}]
+    paper = "#ffffff"
+    if visible_rects:
+        visible_rects.sort(key=lambda shape: (bool(view and shape.rect.x <= view.x + 1 and shape.rect.y <= view.y + 1 and shape.rect.w >= view.w - 2 and shape.rect.h >= view.h - 2), shape.rect.w * shape.rect.h), reverse=True)
+        paper = visible_rects[0].fill or paper
+    failures: list[ContrastFailure] = []
+    for label in parsed.texts:
+        ratio = contrast_ratio(label.fill, paper)
+        if ratio is not None and ratio < 4.5:
+            failures.append({"text": label.label, "ratio": round(ratio, 2)})
+    colors = {
+        match.group(1).lower()
+        for match in re.finditer(r"\b(?:fill|stroke)\s*=\s*['\"](#[0-9a-f]{3,8})['\"]", parsed.svg, re.IGNORECASE)
+    }
+    family_present = bool(re.search(r"Pretendard", parsed.svg, re.IGNORECASE) and re.search(r"Pretendard", source, re.IGNORECASE))
+    font_urls = [unescape(match.group(1).strip()) for match in re.finditer(r"@font-face\b[\s\S]{0,250}?url\(\s*['\"]?([^'\")]+)['\"]?\)", source, re.IGNORECASE)]
+    local_font = any(url.lower().startswith("data:font/") or not re.match(r"https?://", url, re.IGNORECASE) and re.search(r"\.(?:woff2?|ttf|otf)(?:[?#].*)?$", url, re.IGNORECASE) for url in font_urls)
+    font_file_valid = any(
+        url.lower().startswith("data:font/")
+        or not re.match(r"https?://", url, re.IGNORECASE)
+        and source_path != "<stdin>"
+        and (Path(source_path).resolve().parent / re.split(r"[?#]", url, maxsplit=1)[0]).is_file()
+        for url in font_urls
+    )
+    return {
+        "source": source_path,
+        "hasSvg": bool(parsed.svg),
+        "viewBox": view,
+        "title": bool(re.search(r"<title\b[^>]*>[\s\S]*?</title\s*>", parsed.svg, re.IGNORECASE)),
+        "desc": bool(re.search(r"<desc\b[^>]*>[\s\S]*?</desc\s*>", parsed.svg, re.IGNORECASE)),
+        "roleImage": bool(re.search(r"\brole\s*=\s*['\"]img['\"]", parsed.svg, re.IGNORECASE)),
+        "ariaLinked": bool(parsed.attributes.get("aria-labelledby")),
+        "textCount": len(parsed.texts),
+        "textOverlaps": text_overlaps,
+        "objectOverlaps": object_overlaps,
+        "offCanvas": len(off_canvas),
+        "offCanvasLabels": off_canvas[:12],
+        "arrowCrossings": _line_crossings(parsed),
+        "contrastFailures": failures,
+        "colors": len(colors),
+        "largeRadius": sum(float(shape.attributes.get("rx", "0") or 0) > 8 for shape in parsed.shapes if shape.kind == "rect"),
+        "hasShadow": bool(re.search(r"\bbox-shadow\s*:|filter\s*=\s*['\"]url\(#", source, re.IGNORECASE)),
+        "fontFamilyPresent": family_present,
+        "localFont": local_font,
+        "fontFileValid": font_file_valid,
+        "visibleText": _visible_text(source, parsed),
+        "type": parsed.attributes.get("id", ""),
+        "sourceBytes": len(source.encode("utf-8")),
+    }

package/assets/lithermes-plugin/skills/lit-diagram-drawer/scripts/diagram_quality.py

@@ -0,0 +1,293 @@
+"""Accessibility, routing, spacing, boundary, and canvas checks for SVG."""
+
+from __future__ import annotations
+
+import math
+import re
+import colorsys
+
+from diagram_geometry import parse_svg
+from diagram_metrics import DiagramMetrics, source_metrics
+from diagram_quality_geometry import (
+    distance_to_rect_boundary, marker_length, marker_overlaps_rect, marker_scale,
+    marker_tip, rectangle_gap, route_bends, route_crosses_boundary,
+    route_crossings, route_distance, route_length, route_manhattan_distance,
+    routes_overlap_collinearly, segment_along_boundary, segment_hits_rect,
+    segment_hits_text, text_overlaps_node,
+)
+from diagram_records import Boundary, ParsedSvg, Route, Shape, TextBox
+from diagram_sequence import sequence_issues
+
+_CONTAMINATION = (
+    re.compile(r"\blitfamily\b", re.IGNORECASE),
+    re.compile(r"\b(?:generator|generated by|template|prototype)\b", re.IGNORECASE),
+    re.compile(r"\bsource\s*:", re.IGNORECASE),
+    re.compile(r"\bnotes?\s*:", re.IGNORECASE),
+    re.compile(r"\bstatic\s+first\b", re.IGNORECASE),
+    re.compile(r"\baccessible\s+labels\b", re.IGNORECASE),
+    re.compile(r"\bone\s+accent\b", re.IGNORECASE),
+    re.compile(r"\bfocal\b", re.IGNORECASE),
+    re.compile(r"\b(?:light|dark|full)\s*[·|/]\s*static\b", re.IGNORECASE),
+    re.compile(r"\bdesign\s+rules?\b", re.IGNORECASE),
+    re.compile(r"^\s*show\b", re.IGNORECASE),
+)
+
+OFFICE_RULES = {
+    "group_ratio": 2, "accent_saturation": .12, "accent_light_min": .12,
+    "accent_light_max": .93, "accent_hue_family_deg": 20,
+    "accent_medium_count": 3, "accent_high_count": 4,
+    "latin_share": .80, "title_case_share": .60,
+    "label_inset_px": 4,
+}
+
+
+def _office_craft_issues(parsed: ParsedSvg, nodes: tuple[Shape, ...]) -> list[str]:
+    issues: list[str] = []
+    if len(parsed.boundaries) >= 2:
+        def group(shape: Shape) -> str:
+            center = (shape.rect.x + shape.rect.w / 2, shape.rect.y + shape.rect.h / 2)
+            for boundary in parsed.boundaries:
+                if boundary.rect.x <= center[0] <= boundary.rect.right and boundary.rect.y <= center[1] <= boundary.rect.bottom:
+                    return boundary.name
+            return "unbounded"
+
+        within, between = [], []
+        for index, first in enumerate(nodes):
+            for second in nodes[index + 1:]:
+                gap = rectangle_gap(first.rect, second.rect)
+                (within if group(first) == group(second) else between).append(gap)
+        if within and between and min(between) < OFFICE_RULES["group_ratio"] * max(within):
+            issues.append(f"OF-201 group ratio {min(between) / max(within):.2f} below {OFFICE_RULES['group_ratio']}")
+
+    hues: list[float] = []
+    for node in nodes:
+        if node.attributes.get("display") == "none" or not re.fullmatch(r"#[0-9a-fA-F]{6}", node.fill):
+            continue
+        rgb = tuple(int(node.fill[index:index + 2], 16) / 255 for index in (1, 3, 5))
+        hue, lightness, saturation = colorsys.rgb_to_hls(*rgb)
+        hue *= 360
+        if saturation < OFFICE_RULES["accent_saturation"] or not OFFICE_RULES["accent_light_min"] <= lightness <= OFFICE_RULES["accent_light_max"]:
+            continue
+        if not any(min(abs(hue - prior), 360 - abs(hue - prior)) <= OFFICE_RULES["accent_hue_family_deg"] for prior in hues):
+            hues.append(hue)
+    if len(hues) >= OFFICE_RULES["accent_medium_count"]:
+        level = "HIGH" if len(hues) >= OFFICE_RULES["accent_high_count"] else "MEDIUM"
+        issues.append(f"OF-202 {level} accent families={len(hues)}")
+
+    for text in parsed.texts:
+        label = text.label.strip()
+        latin = sum(character.isascii() and character.isalnum() for character in label)
+        if label and latin / len(label) >= OFFICE_RULES["latin_share"] and label != label.upper():
+            words = re.findall(r"[A-Za-z]{4,}", label)
+            capitals = sum(bool(re.fullmatch(r"[A-Z][a-z]+", word)) for word in words)
+            function_word = re.search(r"\b(?:Of|And|The|To|For|In)\b", label)
+            if len(words) >= 2 and capitals / len(words) > OFFICE_RULES["title_case_share"] and function_word:
+                issues.append(f"OF-203 MEDIUM title-case label={label}")
+        if text.edge_for:
+            continue  # Edge labels have no stable inner box in this parser.
+        box = next((boundary.rect for boundary in parsed.boundaries if boundary.name == text.boundary_for), None) if text.boundary_for else None
+        if box is None and text.role == "node":
+            box = next((node.rect for node in nodes if node.rect.x <= text.anchor[0] <= node.rect.right and
+                        node.rect.y <= text.anchor[1] <= node.rect.bottom), None)
+        if box is not None and text.bounds.w > box.w - OFFICE_RULES["label_inset_px"]:
+            issues.append(f"OF-204 label {label} width={text.bounds.w:.1f}px exceeds {box.w - OFFICE_RULES['label_inset_px']:.1f}px")
+    return issues
+
+
+def _node_shapes(parsed: ParsedSvg) -> tuple[Shape, ...]:
+    return tuple(shape for shape in parsed.shapes if shape.attributes.get("data-node-id"))
+
+
+def _node_by_id(nodes: tuple[Shape, ...], name: str) -> Shape | None:
+    return next((node for node in nodes if node.attributes.get("data-node-id") == name), None)
+
+
+def _boundary_label(text: TextBox, outlines: tuple[Boundary, ...]) -> bool:
+    return text.role == "boundary" or bool(text.boundary_for) or any(text.label in boundary.labels or text.boundary_for == boundary.name for boundary in outlines)
+
+
+def _boundary_edges(boundary: Boundary) -> tuple[tuple[float, float, float, float], ...]:
+    rect = boundary.rect
+    return ((rect.x, rect.y, rect.right, rect.y), (rect.right, rect.y, rect.right, rect.bottom), (rect.right, rect.bottom, rect.x, rect.bottom), (rect.x, rect.bottom, rect.x, rect.y))
+
+
+def _marker_id(value: str) -> str:
+    match = re.search(r"url\(\s*['\"]?#([^\s)'\"`]+)['\"]?\s*\)", value, re.IGNORECASE)
+    return match.group(1) if match else ""
+
+
+def _aligned_route(route: Route, nodes: tuple[Shape, ...]) -> str:
+    origin, target = _node_by_id(nodes, route.from_id), _node_by_id(nodes, route.to_id)
+    if origin is None or target is None or not route.segments:
+        return ""
+    same_row = abs(origin.rect.y + origin.rect.h / 2 - target.rect.y - target.rect.h / 2) <= 1
+    same_column = abs(origin.rect.x + origin.rect.w / 2 - target.rect.x - target.rect.w / 2) <= 1
+    horizontal = all(abs(y1 - y2) <= 1 for _, y1, _, y2 in route.segments)
+    vertical = all(abs(x1 - x2) <= 1 for x1, _, x2, _ in route.segments)
+    origin_x, target_x = origin.rect.x + origin.rect.w / 2, target.rect.x + target.rect.w / 2
+    origin_y, target_y = origin.rect.y + origin.rect.h / 2, target.rect.y + target.rect.h / 2
+    row_clear = all(
+        node is origin or node is target
+        or abs(node.rect.y + node.rect.h / 2 - origin_y) > 1
+        or node.rect.x + node.rect.w / 2 <= min(origin_x, target_x)
+        or node.rect.x + node.rect.w / 2 >= max(origin_x, target_x)
+        for node in nodes
+    )
+    column_clear = all(
+        node is origin or node is target
+        or abs(node.rect.x + node.rect.w / 2 - origin_x) > 1
+        or node.rect.y + node.rect.h / 2 <= min(origin_y, target_y)
+        or node.rect.y + node.rect.h / 2 >= max(origin_y, target_y)
+        for node in nodes
+    )
+    if same_row and row_clear and not horizontal:
+        return "same-row"
+    if same_column and column_clear and not vertical:
+        return "same-column"
+    return ""
+
+
+def _decision_issues(nodes: tuple[Shape, ...], routes: tuple[Route, ...]) -> list[str]:
+    issues: list[str] = []
+    for node in nodes:
+        if node.attributes.get("data-node-type") != "decision":
+            continue
+        name = node.attributes["data-node-id"]
+        outcomes = [value.strip() for value in node.attributes.get("data-outcomes", "").split("|") if value.strip()]
+        if len(outcomes) < 2:
+            issues.append(f"DECISION_OUTCOMES_MISSING {name} must name at least two outcomes")
+            continue
+        labels = {route.label for route in routes if route.from_id == name and route.label}
+        issues.extend(f"DECISION_OUTCOME_MISSING {name} {outcome}" for outcome in outcomes if outcome not in labels)
+        issues.extend(f"DECISION_OUTCOME_UNDECLARED {name} {label}" for label in labels if label not in outcomes)
+    return issues
+
+
+def _route_issues(parsed: ParsedSvg, metrics: DiagramMetrics, nodes: tuple[Shape, ...]) -> list[str]:
+    issues: list[str] = []
+    sequence = bool(re.search(r"\bdata-type\s*=\s*['\"]sequence(?:-oauth)?['\"]", parsed.source, re.IGNORECASE))
+    for text in parsed.texts:
+        if text.role != "edge" and not text.edge_for:
+            continue
+        matches = [route for route in parsed.routes if f"{route.from_id}|{route.to_id}" == text.edge_for and (not route.label or route.label == text.label)]
+        if not text.edge_for or len(matches) != 1:
+            issues.append(f"EDGE_LABEL_UNBOUND {text.edge_for or text.label}")
+            continue
+        route = matches[0]
+        own = route_distance(text.anchor, route)
+        other = min((route_distance(text.anchor, item) for item in parsed.routes if item is not route), default=math.inf)
+        if own > 24:
+            issues.append(f"EDGE_LABEL_TOO_FAR {text.label} own={own:.1f}px max=24px")
+        if math.isfinite(other) and own >= other:
+            issues.append(f"EDGE_LABEL_NEAREST_PATH {text.label} own={own:.1f}px other={other:.1f}px")
+        for node in nodes:
+            if text_overlaps_node(text, node.rect):
+                issues.append(f"EDGE_LABEL_NODE_COLLISION {text.label} overlaps {node.attributes['data-node-id']}")
+    for route in parsed.routes:
+        distance = route_manhattan_distance(route)
+        ratio = route_length(route) / distance if distance else 1
+        if ratio > 1.4:
+            issues.append(f"ROUTE_DETOUR {route.from_id}->{route.to_id} ratio={ratio:.2f} max=1.40")
+        aligned = _aligned_route(route, nodes)
+        if aligned:
+            issues.append(f"ROUTE_ALIGNED_PATH {route.from_id}->{route.to_id} {aligned} neighbors require one straight segment")
+        crosses = any(route_crosses_boundary(route, boundary) for boundary in parsed.boundaries)
+        limit = 3 if crosses else 2
+        bends = route_bends(route)
+        if bends > limit:
+            issues.append(f"ROUTE_BENDS {route.from_id}->{route.to_id} bends={bends} max={limit}")
+        if route.marker_start and route.marker_end:
+            issues.append(f"ROUTE_OPPOSED_HEADS {route.from_id}->{route.to_id}")
+        for text in parsed.texts:
+            if any(segment_hits_text(segment, text) for segment in route.segments):
+                issues.append(f"EDGE_TEXT_COLLISION {route.from_id}->{route.to_id}: {text.label}")
+                break
+        for node in nodes:
+            if node.attributes.get("data-node-id") not in {route.from_id, route.to_id} and any(segment_hits_rect(segment, node.rect, 8) for segment in route.segments):
+                issues.append(f"ROUTE_THROUGH_NODE {route.from_id}->{route.to_id} via {node.attributes['data-node-id']}")
+        if any(segment_along_boundary(segment, boundary) for boundary in parsed.boundaries for segment in route.segments):
+            issues.append(f"ROUTE_ALONG_BOUNDARY {route.from_id}->{route.to_id}")
+        target = _node_by_id(nodes, route.to_id)
+        if route.marker_end:
+            marker = parsed.markers.get(_marker_id(route.marker_end))
+            minimum = max(5 * route.stroke_width, (metrics["viewBox"].w if metrics["viewBox"] else 1080) * 12 / 1080)
+            if marker is None:
+                issues.append(f"ARROWHEAD_GEOMETRY_MISSING {route.from_id}->{route.to_id} end")
+            elif marker_length(marker) * marker_scale(marker, route) + 0.01 < minimum:
+                issues.append(f"ARROWHEAD_SIZE_FLOOR {route.from_id}->{route.to_id} end min={minimum:.1f}px")
+            if marker is not None and target is not None and not sequence:
+                tip = marker_tip(route, marker, "end")
+                if tip is not None and distance_to_rect_boundary(tip, target.rect) > 2:
+                    issues.append(f"ARROWHEAD_TIP_MISSED_TARGET {route.from_id}->{route.to_id}")
+            if marker is not None and target is not None and marker_overlaps_rect(route, target.rect, marker):
+                issues.append(f"ARROWHEAD_TARGET_OVERLAP {route.from_id}->{route.to_id} marker intersects target {route.to_id}")
+    for index, first in enumerate(parsed.routes):
+        for second in parsed.routes[index + 1:]:
+            if routes_overlap_collinearly(first, second):
+                issues.append(f"ROUTE_COLLINEAR_OVERLAP {first.from_id}->{first.to_id} / {second.from_id}->{second.to_id} shared within 12px")
+            for x, y in route_crossings(first, second):
+                issues.append(f"ROUTE_CROSSING {first.from_id}->{first.to_id} / {second.from_id}->{second.to_id} at {x:.1f},{y:.1f}")
+    return issues
+
+
+def quality_issues(source: str, *, enforce_canvas: bool = False, scale: float | None = None) -> list[str]:
+    """Return stable issue codes for geometry, readability, and accessibility defects."""
+    parsed = parse_svg(source)
+    metrics = source_metrics(source)
+    nodes = _node_shapes(parsed)
+    issues: list[str] = []
+    contaminated = list(dict.fromkeys(text.label for text in parsed.texts if any(rule.search(text.label) for rule in _CONTAMINATION)))
+    if contaminated:
+        issues.append("PROCESS_TEXT " + " | ".join(contaminated))
+    if not metrics["hasSvg"]:
+        issues.append("SVG_MISSING")
+        return issues
+    for key, code in (("title", "SVG_TITLE_MISSING"), ("desc", "SVG_DESC_MISSING"), ("roleImage", "SVG_ROLE_IMAGE_MISSING"), ("ariaLinked", "SVG_ARIA_LINK_MISSING")):
+        if not metrics[key]:
+            issues.append(code)
+    if metrics["offCanvas"]:
+        issues.append("OFF_CANVAS " + " | ".join(metrics["offCanvasLabels"]))
+    if metrics["textOverlaps"]:
+        issues.append(f"TEXT_OVERLAP count={metrics['textOverlaps']}")
+    if metrics["objectOverlaps"]:
+        issues.append(f"OBJECT_OVERLAP count={metrics['objectOverlaps']}")
+    for failure in metrics["contrastFailures"]:
+        issues.append(f"CONTRAST_FLOOR {failure['text']}={failure['ratio']}:1")
+    issues.extend(_route_issues(parsed, metrics, nodes))
+    issues.extend(_decision_issues(nodes, parsed.routes))
+    issues.extend(sequence_issues(source, parsed, nodes))
+    for text in parsed.texts:
+        for boundary in parsed.boundaries:
+            if any(segment_hits_text(edge, text, boundary.stroke_width / 2 + 0.5) for edge in _boundary_edges(boundary)):
+                issues.append(f"OUTLINE_TEXT_COLLISION {text.label} crosses {boundary.name}")
+                break
+    boundary_failures = {failure["text"] for failure in metrics["contrastFailures"]}
+    for text in parsed.texts:
+        if _boundary_label(text, parsed.boundaries) and text.label in boundary_failures:
+            issues.append(f"BOUNDARY_CONTRAST_FLOOR {text.label} below 4.5:1")
+    for index, first in enumerate(nodes):
+        for second in nodes[index + 1:]:
+            if rectangle_gap(first.rect, second.rect) < 12:
+                issues.append(f"NODE_GAP {first.attributes['data-node-id']}/{second.attributes['data-node-id']} below 12px")
+    issues.extend(_office_craft_issues(parsed, nodes))
+    if enforce_canvas:
+        ratio = scale if scale is not None else min(metrics["viewBox"].w / 1080, metrics["viewBox"].h / 640) if metrics["viewBox"] else 1
+        if not any(text.role == "title" for text in parsed.texts):
+            issues.append('TITLE_ROLE_MISSING visible title must use data-role="title"')
+        for text in parsed.texts:
+            boundary_text = _boundary_label(text, parsed.boundaries)
+            minimum = 28 if text.role == "title" else 13 if text.role == "edge" or boundary_text else 15 if text.role == "node" else 0
+            if minimum and text.font_size + 0.01 < minimum * ratio:
+                detail = f"{text.role or 'boundary'}:{text.label}={text.font_size}px (min {minimum * ratio:.1f}px)"
+                issues.append(f"BOUNDARY_FONT_FLOOR {detail}" if boundary_text else "FONT_FLOOR " + detail)
+        points = [(node.rect.x, node.rect.y) for node in nodes] + [(node.rect.right, node.rect.bottom) for node in nodes]
+        points.extend(point for route in parsed.routes for segment in route.segments for point in ((segment[0], segment[1]), (segment[2], segment[3])))
+        if nodes and metrics["viewBox"] and points:
+            left, top = min(point[0] for point in points), min(point[1] for point in points)
+            right, bottom = max(point[0] for point in points), max(point[1] for point in points)
+            width, height = (right - left) / (metrics["viewBox"].w * 0.90), (bottom - top) / (metrics["viewBox"].h * 0.74)
+            if width < 0.75 or height < 0.54:
+                issues.append(f"CONTENT_FILL safe-area-width={width:.3f} safe-area-height={height:.3f} minimum=.75/.54")
+        if not nodes:
+            issues.append("CONTENT_NODES_MISSING")
+    return list(dict.fromkeys(issues))