@lovehlmmm/primekit 1.0.0

package/skills/preview/references/vendor/diagram-design-scripts/PROVENANCE.md

@@ -0,0 +1,27 @@
+# Vendored from cathrynlavery/diagram-design
+
+**Pinned commit:** `09df49d8d1a1c7fb2efdfcdc7a2a0713534350a6`
+**Upstream:** https://github.com/cathrynlavery/diagram-design
+**License:** MIT — see `UPSTREAM-LICENSE`
+
+## Files
+
+| File | Upstream path | Purpose |
+|---|---|---|
+| `self_check.py` | `skills/diagram-design/scripts/self_check.py` | Overall self-lint on a diagram-design HTML artifact |
+| `verify-geometry.py` | `scripts/verify-geometry.py` | Enforces the 6 connector rules (right-angle, dot junctions, arrowhead style, etc.) |
+| `verify-motion.py` | `scripts/verify-motion.py` | Verifies motion tier declarations match CSS and honor `prefers-reduced-motion` |
+| `run-validators.sh` | PrimeKit-authored | Graceful wrapper; skips silently when python3 is absent (v1 advisory-only) |
+
+## Advisory contract (v1)
+
+All three scripts are **advisory-only**. They warn on stderr and never block artifact delivery. Callers use `run-validators.sh` (which exits 0 unconditionally) rather than the raw Python scripts.
+
+## Update procedure
+
+1. Bump the pinned commit above.
+2. Re-copy the three scripts from the same paths.
+3. Re-copy `UPSTREAM-LICENSE`.
+4. Note behavior changes in the release notes.
+
+Do **not** shim, patch, or modify the vendored scripts — that would fragment upstream. Instead, wrap or configure via `run-validators.sh`.

package/skills/preview/references/vendor/diagram-design-scripts/UPSTREAM-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cathryn Lavery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/preview/references/vendor/diagram-design-scripts/run-validators.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Advisory-only validator wrapper for diagram-design artifacts.
+# Graceful skip when python3 is absent (v1 must never block artifact rendering).
+set -u
+ARTIFACT="${1:-}"
+if [ -z "$ARTIFACT" ]; then
+  echo "usage: run-validators.sh <artifact.html>" >&2
+  exit 2
+fi
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[diagram-design] python3 not found, skipping validators (advisory-only in v1)"
+  exit 0
+fi
+DIR="$(cd "$(dirname "$0")" && pwd)"
+STATUS=0
+for script in self_check.py verify-geometry.py verify-motion.py; do
+  if [ -f "$DIR/$script" ]; then
+    python3 "$DIR/$script" "$ARTIFACT" || {
+      rc=$?
+      echo "[diagram-design] $script exited $rc (advisory — artifact not blocked)"
+      STATUS=1
+    }
+  fi
+done
+exit 0  # advisory-only: never propagate validator failure to the caller

package/skills/preview/references/vendor/diagram-design-scripts/self_check.py

@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""Self-check a generated diagram HTML file, with no third-party deps.
+
+Ships inside the skill so an installed agent can verify its own output:
+
+    python3 <skill-dir>/scripts/self_check.py my-diagram.html
+
+Checks the accessible-SVG contract, the single-file safety rules (no remote
+assets beyond the approved Google Fonts stylesheet, no executable attributes,
+no scripts other than the one canonical motion controller), and — when motion
+markup is present — the structural motion contract. This is a distilled
+subset of the repository gates (`lint-skin.py`, `verify-motion.py`), which
+remain the authority for contributions to the repository itself.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections import Counter
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urlparse
+
+SKILL_DIR = Path(__file__).resolve().parent.parent
+MOTION_TEMPLATE = SKILL_DIR / "assets" / "template-motion.html"
+MODES = {"none", "reveal", "step", "loop"}
+ACTIONS = {"play", "pause", "replay", "prev", "next"}
+ASCII_DECIMAL_RE = re.compile(r"^[0-9]+$")
+REFERENCE_ATTRS = {"src", "href", "xlink:href", "poster", "srcset", "action", "formaction"}
+
+
+class DiagramParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.roots: list[dict[str, str]] = []
+        self.items: list[dict[str, str]] = []
+        self.actions: set[str] = set()
+        self.controls = 0
+        self.statuses: list[dict[str, str]] = []
+        self.statuses_in_controls = 0
+        self.scripts: list[dict[str, object]] = []
+        self.styles: list[str] = []
+        self.svgs: list[dict[str, object]] = []
+        self.unsafe: list[str] = []
+        self.references: list[tuple[str, str, str]] = []
+        self._svg_depth = 0
+        self._current_svg: dict[str, object] | None = None
+        self._capture: str | None = None
+        self._current_script: dict[str, object] | None = None
+        self._in_style = False
+        self._element_stack: list[str] = []
+        self._motion_root_depth: int | None = None
+        self._controls_depth: int | None = None
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.casefold()
+        normalized_attrs = [(key.casefold(), value or "") for key, value in attrs]
+        data = {key: value for key, value in normalized_attrs}
+        if tag in {"base", "embed", "object", "iframe"}:
+            self.unsafe.append(f"<{tag}> is not allowed in a diagram file")
+        for key, value in normalized_attrs:
+            if key.startswith("on"):
+                self.unsafe.append(f"executable attribute {key} on <{tag}>")
+            if key == "srcdoc":
+                self.unsafe.append(f"srcdoc attribute on <{tag}>")
+            if key in REFERENCE_ATTRS:
+                self.references.append((tag, data.get("rel", ""), value))
+        if "data-motion-root" in data:
+            self.roots.append(data)
+            if self._motion_root_depth is None:
+                self._motion_root_depth = len(self._element_stack)
+        if self._motion_root_depth is not None:
+            if "data-motion-item" in data:
+                self.items.append(data)
+            if "data-motion-action" in data:
+                self.actions.add(data["data-motion-action"])
+            if "data-motion-controls" in data:
+                self.controls += 1
+                if self._controls_depth is None:
+                    self._controls_depth = len(self._element_stack)
+            if "data-motion-status" in data:
+                self.statuses.append(data)
+                if self._controls_depth is not None:
+                    self.statuses_in_controls += 1
+        if tag == "script":
+            self._current_script = {
+                "attrs": data,
+                "attr_names": [name for name, _value in normalized_attrs],
+                "body": [],
+                "closed": False,
+            }
+            self.scripts.append(self._current_script)
+        if tag == "style":
+            self._in_style = True
+        self._element_stack.append(tag)
+        if tag == "svg" and self._svg_depth == 0:
+            self._svg_depth = 1
+            self._current_svg = {"attrs": data, "first": None, "title": {}, "desc": {}}
+            self.svgs.append(self._current_svg)
+            return
+        if self._svg_depth:
+            self._svg_depth += 1
+            assert self._current_svg is not None
+            if self._svg_depth == 2 and self._current_svg["first"] is None:
+                self._current_svg["first"] = tag
+            if self._svg_depth == 2 and tag in {"title", "desc"}:
+                self._current_svg[tag] = {"attrs": data, "text": ""}
+                self._capture = tag
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.casefold()
+        if tag == "script" and self._current_script is not None:
+            self._current_script["closed"] = True
+            self._current_script = None
+        if tag == "style":
+            self._in_style = False
+        if self._svg_depth:
+            if tag in {"title", "desc"}:
+                self._capture = None
+            self._svg_depth -= 1
+            if self._svg_depth == 0:
+                self._current_svg = None
+        for index in range(len(self._element_stack) - 1, -1, -1):
+            if self._element_stack[index] == tag:
+                del self._element_stack[index:]
+                break
+        if (
+            self._motion_root_depth is not None
+            and len(self._element_stack) <= self._motion_root_depth
+        ):
+            self._motion_root_depth = None
+        if (
+            self._controls_depth is not None
+            and len(self._element_stack) <= self._controls_depth
+        ):
+            self._controls_depth = None
+
+    def handle_data(self, data: str) -> None:
+        if self._current_script is not None:
+            body = self._current_script["body"]
+            assert isinstance(body, list)
+            body.append(data)
+        if self._in_style:
+            self.styles.append(data)
+        if self._capture and self._current_svg:
+            node = self._current_svg[self._capture]
+            assert isinstance(node, dict)
+            node["text"] = str(node.get("text", "")) + data
+
+
+def normalized_controller(body: str) -> str:
+    return body.replace("\r\n", "\n").replace("\r", "\n").strip()
+
+
+def parsed_document(source: str) -> DiagramParser:
+    parser = DiagramParser()
+    parser.feed(source)
+    parser.close()
+    return parser
+
+
+def is_approved_google_fonts_stylesheet(value: str) -> bool:
+    try:
+        parsed = urlparse(value)
+    except ValueError:
+        return False
+    return (
+        parsed.scheme == "https"
+        and parsed.hostname is not None
+        and parsed.hostname.casefold() == "fonts.googleapis.com"
+        and parsed.port is None
+        and parsed.path == "/css2"
+        and not parsed.fragment
+    )
+
+
+def reference_error(tag: str, rel: str, value: str) -> str | None:
+    stripped = value.strip()
+    lowered = stripped.casefold()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if lowered.startswith("javascript:") or lowered.startswith("data:text/html"):
+        return f"executable URL on <{tag}>: {stripped[:80]}"
+    remote = lowered.startswith(("http://", "https://", "//")) or (
+        ":" in stripped.split("/", 1)[0] and not lowered.startswith("data:")
+    )
+    if not remote:
+        if lowered.startswith("data:") and not lowered.startswith("data:image/"):
+            return f"non-image data URL on <{tag}>: {stripped[:80]}"
+        return None
+    if tag == "link" and "stylesheet" in rel.casefold().split():
+        if is_approved_google_fonts_stylesheet(stripped):
+            return None
+        return f"remote stylesheet is not the approved Google Fonts /css2 URL: {stripped[:80]}"
+    return f"remote reference on <{tag}>: {stripped[:80]}"
+
+
+def canonical_controller() -> str:
+    if not MOTION_TEMPLATE.is_file():
+        raise RuntimeError(
+            f"cannot find the canonical controller at {MOTION_TEMPLATE}; "
+            "run self_check.py from its shipped location inside the skill"
+        )
+    parser = parsed_document(MOTION_TEMPLATE.read_text(encoding="utf-8"))
+    if len(parser.scripts) != 1 or not parser.scripts[0]["closed"]:
+        raise RuntimeError("template-motion.html must contain one closed controller")
+    body = parser.scripts[0]["body"]
+    assert isinstance(body, list)
+    return normalized_controller("".join(body))
+
+
+def check_svgs(parser: DiagramParser, errors: list[str]) -> None:
+    checkable = [
+        svg
+        for svg in parser.svgs
+        if isinstance(svg["attrs"], dict)
+        and str(svg["attrs"].get("aria-hidden", "")).casefold() != "true"
+    ]
+    if not checkable:
+        errors.append("diagram file needs at least one accessible (non-aria-hidden) SVG")
+    for number, svg in enumerate(checkable, 1):
+        attrs = svg["attrs"]
+        assert isinstance(attrs, dict)
+        if attrs.get("role") != "img":
+            errors.append(f"svg {number} needs role=img")
+        labelled = attrs.get("aria-labelledby", "").split()
+        title = svg["title"]
+        desc = svg["desc"]
+        assert isinstance(title, dict) and isinstance(desc, dict)
+        title_attrs = title.get("attrs", {})
+        desc_attrs = desc.get("attrs", {})
+        assert isinstance(title_attrs, dict) and isinstance(desc_attrs, dict)
+        if svg["first"] != "title":
+            errors.append(f"svg {number} title must be its first child")
+        if not str(title.get("text", "")).strip() or not str(desc.get("text", "")).strip():
+            errors.append(f"svg {number} needs non-empty title and desc")
+        title_id = title_attrs.get("id", "")
+        desc_id = desc_attrs.get("id", "")
+        if title_id in {"", "title"} or desc_id in {"", "desc"}:
+            errors.append(f"svg {number} title/desc IDs must be diagram-prefixed, never bare")
+        if labelled != [title_id, desc_id]:
+            errors.append(f"svg {number} aria-labelledby must name title then desc")
+
+
+def check_scripts(parser: DiagramParser, errors: list[str]) -> None:
+    if not parser.scripts:
+        return
+    if len(parser.scripts) > 1:
+        errors.append(f"at most one script is allowed; found {len(parser.scripts)}")
+    for number, script in enumerate(parser.scripts, 1):
+        attrs = script["attrs"]
+        attr_names = script["attr_names"]
+        body = script["body"]
+        assert isinstance(attrs, dict) and isinstance(attr_names, list) and isinstance(body, list)
+        if not script["closed"]:
+            errors.append(f"script {number} must have a closing script tag")
+        if attr_names != ["data-diagram-controls"] or attrs.get("data-diagram-controls") != "":
+            errors.append(f"script {number} must carry only the canonical data-diagram-controls attribute")
+            continue
+        try:
+            if normalized_controller("".join(body)) != canonical_controller():
+                errors.append(f"script {number} must exactly match the controller in template-motion.html")
+        except RuntimeError as exc:
+            errors.append(str(exc))
+
+
+def check_motion(parser: DiagramParser, source: str, errors: list[str]) -> None:
+    has_motion_markup = bool(parser.roots or parser.items or parser.scripts)
+    if not has_motion_markup:
+        return
+    if len(parser.roots) != 1:
+        errors.append(f"expected exactly one data-motion-root; found {len(parser.roots)}")
+        return
+    root = parser.roots[0]
+    mode = root.get("data-motion-mode", "")
+    if mode not in MODES:
+        errors.append(f"data-motion-mode must be one of {sorted(MODES)}; got {mode!r}")
+    raw_count = root.get("data-step-count", "")
+    if not ASCII_DECIMAL_RE.fullmatch(raw_count):
+        count = -1
+        errors.append("data-step-count must be an ASCII decimal integer")
+    else:
+        count = int(raw_count)
+    minimum_count = 0 if mode == "none" else 1
+    if count < minimum_count or count > 8:
+        errors.append(f"semantic step count must be {minimum_count}..8; got {count}")
+
+    if len(parser.items) > 12:
+        errors.append(f"motion item budget is 12; found {len(parser.items)}")
+    semantic_steps: list[int] = []
+    for index, item in enumerate(parser.items, 1):
+        raw_step = item.get("data-step", "")
+        if not ASCII_DECIMAL_RE.fullmatch(raw_step):
+            errors.append(f"motion item {index} has a non-ASCII-decimal data-step")
+            continue
+        step = int(raw_step)
+        decorative = "data-motion-decorative" in item
+        if not decorative:
+            semantic_steps.append(step)
+            if not item.get("aria-label", "").strip():
+                errors.append(f"semantic motion item {index} needs a non-color aria-label")
+        elif item.get("aria-hidden") != "true" or item.get("focusable") != "false":
+            errors.append(f"decorative motion item {index} needs aria-hidden=true and focusable=false")
+        inline = item.get("style", "").replace(" ", "").lower()
+        if any(token in inline for token in ("display:none", "visibility:hidden", "opacity:0")):
+            errors.append(f"motion item {index} is hidden in source; the fallback must be visible")
+
+    expected = set(range(1, count + 1)) if count > 0 else set()
+    if set(semantic_steps) != expected:
+        errors.append(f"semantic steps must be contiguous 1..{count}; found {sorted(set(semantic_steps))}")
+    crowded = {step: n for step, n in Counter(semantic_steps).items() if n > 2}
+    if crowded:
+        errors.append(f"no more than two semantic items may share a step; found {crowded}")
+
+    if mode in {"none", "loop"} and parser.scripts:
+        errors.append(f"{mode} mode must be script-free")
+    if mode in {"none", "loop"} and (parser.controls or parser.actions or parser.statuses):
+        errors.append(f"{mode} mode must not expose playback controls or live status")
+    controlled = mode == "step" or (mode == "reveal" and bool(parser.scripts))
+    if controlled:
+        if parser.controls != 1:
+            errors.append(f"controlled mode needs one in-root control group; found {parser.controls}")
+        missing = ACTIONS - parser.actions
+        if missing:
+            errors.append(f"controlled mode is missing actions: {', '.join(sorted(missing))}")
+        if not parser.statuses:
+            errors.append("controlled mode needs data-motion-status")
+        else:
+            status = parser.statuses[0]
+            if (
+                status.get("role") != "status"
+                or status.get("aria-live") != "polite"
+                or status.get("aria-atomic") != "true"
+            ):
+                errors.append("motion status needs role=status, aria-live=polite, aria-atomic=true")
+            if parser.statuses_in_controls:
+                errors.append("motion status must sit outside data-motion-controls")
+        if not parser.scripts:
+            errors.append("controlled mode needs the scoped control script")
+
+    style_source = "".join(parser.styles)
+    if parser.scripts:
+        if re.search(r"prefers-reduced-motion\s*:\s*reduce", style_source, re.IGNORECASE) is None:
+            errors.append("missing reduced-motion CSS fallback (prefers-reduced-motion)")
+        if re.search(r"@media\s+print\b", style_source, re.IGNORECASE) is None:
+            errors.append("missing print CSS fallback (@media print)")
+        if "<noscript" not in source.casefold():
+            errors.append("motion file needs a <noscript> explanation of the complete static frame")
+
+
+def verify(path: Path) -> list[str]:
+    source = path.read_text(encoding="utf-8")
+    parser = parsed_document(source)
+    errors: list[str] = []
+    errors.extend(parser.unsafe)
+    for tag, rel, value in parser.references:
+        finding = reference_error(tag, rel, value)
+        if finding:
+            errors.append(finding)
+    check_svgs(parser, errors)
+    check_scripts(parser, errors)
+    check_motion(parser, source, errors)
+    return errors
+
+
+def main() -> int:
+    argument_parser = argparse.ArgumentParser(description=__doc__)
+    argument_parser.add_argument("files", nargs="+", type=Path)
+    args = argument_parser.parse_args()
+    failed = False
+    for path in args.files:
+        try:
+            errors = verify(path)
+        except (OSError, UnicodeError) as exc:
+            errors = [str(exc)]
+        if errors:
+            failed = True
+            print(f"FAIL {path}")
+            for error in errors:
+                print(f"  - {error}")
+        else:
+            print(f"OK {path}")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/preview/references/vendor/diagram-design-scripts/verify-geometry.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Verify no diagram label mask is clipped by a node painted after it.
+
+SKILL.md §6 keeps an arrow label 6-10px clear of its connector, and §5 fixes the
+paint order as background -> zones -> arrows -> labels -> nodes. Nothing keeps a
+label mask off a *node*, so a label whose mask lands partly inside a node
+rectangle that is painted later gets covered by the node fill: the text renders
+as a fragment sitting on the node border.
+
+Paint order is what makes this a defect rather than a stylistic choice:
+
+* A mask overlapping a zone container is fine - zones are painted before labels,
+  so the label stays on top. Zone eyebrows rely on this.
+* A mask overlapping a node declared *later* in the document is clipped by that
+  node. That is the failure this check reports.
+
+Shape heuristics follow the shipped templates:
+
+* A node is a `<rect>` at least 60x40 - large enough for a title and sublabel.
+* A label mask is a `<rect>` 20-120 wide and 8-14 tall - the masking plate that
+  SKILL.md prescribes for arrow labels and zone eyebrows.
+* A mask fully contained in a node is a badge chip (`EXT`, `EDGE`, `ORIG`) and
+  is legal.
+
+Usage:
+    python3 scripts/verify-geometry.py --all
+    python3 scripts/verify-geometry.py skills/diagram-design/assets/example-x.html
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+ASSET_DIR = ROOT / "skills/diagram-design/assets"
+
+RECT_RE = re.compile(
+    r"<rect\b[^>]*?"
+    r'\bx="(?P<x>-?[\d.]+)"\s+'
+    r'y="(?P<y>-?[\d.]+)"\s+'
+    r'width="(?P<w>[\d.]+)"\s+'
+    r'height="(?P<h>[\d.]+)"',
+    re.IGNORECASE,
+)
+
+NODE_MIN_W = 60.0
+NODE_MIN_H = 40.0
+MASK_MIN_W = 20.0
+MASK_MAX_W = 120.0
+MASK_MIN_H = 8.0
+MASK_MAX_H = 14.0
+EPSILON = 0.5
+
+
+class Rect:
+    __slots__ = ("x", "y", "w", "h", "line", "offset")
+
+    def __init__(self, x, y, w, h, line, offset) -> None:
+        self.x, self.y, self.w, self.h = x, y, w, h
+        self.line, self.offset = line, offset
+
+    @property
+    def right(self) -> float:
+        return self.x + self.w
+
+    @property
+    def bottom(self) -> float:
+        return self.y + self.h
+
+    def __repr__(self) -> str:
+        return f"({self.x:g},{self.y:g} {self.w:g}x{self.h:g})"
+
+
+def parse_rects(source: str) -> list[Rect]:
+    rects: list[Rect] = []
+    for match in RECT_RE.finditer(source):
+        rects.append(
+            Rect(
+                float(match.group("x")),
+                float(match.group("y")),
+                float(match.group("w")),
+                float(match.group("h")),
+                source.count("\n", 0, match.start()) + 1,
+                match.start(),
+            )
+        )
+    return rects
+
+
+def overlap(a: Rect, b: Rect) -> tuple[float, float]:
+    return (
+        min(a.right, b.right) - max(a.x, b.x),
+        min(a.bottom, b.bottom) - max(a.y, b.y),
+    )
+
+
+def contained(inner: Rect, outer: Rect) -> bool:
+    return (
+        inner.x >= outer.x - EPSILON
+        and inner.y >= outer.y - EPSILON
+        and inner.right <= outer.right + EPSILON
+        and inner.bottom <= outer.bottom + EPSILON
+    )
+
+
+def check(path: Path) -> list[str]:
+    source = path.read_text(encoding="utf-8")
+    rects = parse_rects(source)
+    nodes = [r for r in rects if r.w >= NODE_MIN_W and r.h >= NODE_MIN_H]
+    masks = [
+        r
+        for r in rects
+        if MASK_MIN_W <= r.w <= MASK_MAX_W and MASK_MIN_H <= r.h <= MASK_MAX_H
+    ]
+
+    findings: list[str] = []
+    for mask in masks:
+        for node in nodes:
+            if node.offset <= mask.offset:
+                continue  # painted before the label; the label stays on top
+            dx, dy = overlap(mask, node)
+            if dx <= 1.0 or dy <= 1.0 or contained(mask, node):
+                continue
+            findings.append(
+                f"{path.name}:{mask.line}: label mask {mask} is clipped by node "
+                f"{node} declared later at line {node.line} (overlap {dx:g}x{dy:g}px)"
+                f" - move the label onto a free segment of its connector"
+            )
+            break
+    return findings
+
+
+def targets(args: argparse.Namespace) -> list[Path]:
+    if args.all:
+        return sorted(ASSET_DIR.glob("*.html"))
+    return [Path(p) for p in args.files]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("files", nargs="*", help="HTML diagrams to check")
+    parser.add_argument("--all", action="store_true", help="check every shipped asset")
+    args = parser.parse_args()
+
+    paths = targets(args)
+    if not paths:
+        parser.error("pass one or more files, or --all")
+
+    findings: list[str] = []
+    for path in paths:
+        if not path.exists():
+            findings.append(f"{path}: file not found")
+            continue
+        findings.extend(check(path))
+
+    for finding in findings:
+        print(finding)
+    print(f"Summary: {len(paths)} file(s) checked, {len(findings)} finding(s).")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())