feat(lint): add connector_motion_detached layout check

packages/cli/src/commands/check.test.ts

@@ -153,6 +153,7 @@ function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver
     collectLayoutGeometry: vi.fn(async () => `geometry-${geometryCallCount++}`),
     collectRotationSample: vi.fn(async (_time: number) => []),
     collectOffPivotRotationSample: vi.fn(async (time: number) => ({ time, samples: [] })),
+    collectConnectorSample: vi.fn(async (time: number) => ({ time, connectors: [], nodes: [] })),
     collectGeometryCandidates: vi.fn(async () => []),
     collectMotionFrame: vi.fn(async (time: number) => ({ time, data: {}, liveness: {} })),
     anchorMotionIssues: vi.fn(async (issues: LayoutIssue[]) =>

packages/cli/src/commands/layout-audit.browser.js

@@ -198,7 +198,9 @@
       return false;
     }
     const rect = element.getBoundingClientRect();
-    if (rect.width <= 0.5 || rect.height <= 0.5) return false;
+    // Stroke is excluded from an SVG shape's client rect, so axis-aligned geometry measures 0 on one axis.
+    const stroke = typeof element.getBBox === "function" ? parseFloat(style.strokeWidth) || 0 : 0;
+    if (rect.width + stroke <= 0.5 || rect.height + stroke <= 0.5) return false;
     return probeClipPath === false || !isClippedAway(element);
   }
 
@@ -1233,10 +1235,15 @@
       const mapped = point.matrixTransform(matrix);
       return { x: mapped.x, y: mapped.y };
     };
-    return {
-      start: toScreen(path.getPointAtLength(0)),
-      end: toScreen(path.getPointAtLength(total)),
-    };
+    // getPointAtLength can throw on a degenerate path even after getTotalLength; skip that path instead of aborting the whole per-frame check.
+    try {
+      return {
+        start: toScreen(path.getPointAtLength(0)),
+        end: toScreen(path.getPointAtLength(total)),
+      };
+    } catch {
+      return null;
+    }
   }
 
   function distanceToRect(point, rect) {
@@ -1266,6 +1273,16 @@
     return { compact, painted };
   }
 
+  /** Connector naming for the motion sampler, tolerant of camelCase ids the word-bounded name test would miss. */
+  function isMotionConnectorCandidate(svg, path) {
+    if (isConnectorPath(svg, path)) return true;
+    const spaced = `${connectorNameFor(svg)} ${connectorNameFor(path)}`.replace(
+      /([a-z])([A-Z0-9])/g,
+      "$1 $2",
+    );
+    return CONNECTOR_NAME.test(spaced);
+  }
+
   function isConnectorPath(svg, path) {
     if (path.hasAttribute("marker-start") || path.hasAttribute("marker-end")) return true;
     return (
@@ -1734,4 +1751,174 @@
     }
     return samples;
   };
+
+  // connector_motion_detached sampling: per frame, report each connector's screen endpoints and every node bbox; icon-sized SVGs and short strokes are filtered out.
+  const CONNECTOR_MIN_SVG_PX = 100;
+  const CONNECTOR_MIN_LEN_PX = 60;
+  // Gauge needles/pointers/ticks are one-end-anchored indicators owned by a separate check; skip by id/class of the line or any group ancestor.
+  // Word-bounded so `sticky`/`ticker` do not match, and pointer-events is excluded: a Tailwind utility must not mute a whole subtree.
+  const CONNECTOR_INDICATOR_NAME = /\b(needle|pointer(?!-events)|gauge|tick|indicator)\b/i;
+  const CONNECTOR_NODE_MIN_AREA = 400;
+  // SVG dots/markers are small; keep the floor low but above sub-pixel decoration.
+  const CONNECTOR_NODE_MIN_DOT_AREA = 16;
+  const CONNECTOR_NODE_CAP = 300;
+  // Recognize near-circular stroke <path> arcs as ring nodes so connectors attaching to them aren't false-flagged and the gauge exclusion sees arc-drawn dials.
+  const CONNECTOR_RING_MIN_LEN = 120;
+  const CONNECTOR_RING_MIN_RADIUS = 20;
+  const CONNECTOR_RING_MAX_RESIDUAL_FRAC = 0.15;
+  // Phantom-radius guard: a shallow arc fits an enormous circle with a tiny residual, so reject when the fitted diameter runs past this factor of the bbox.
+  const CONNECTOR_RING_MAX_DIAMETER_BBOX_FRAC = 3;
+
+  function isIndicatorConnector(line, svg) {
+    for (let node = line; node && node !== svg.parentElement; node = node.parentElement) {
+      if (CONNECTOR_INDICATOR_NAME.test(connectorNameFor(node))) return true;
+    }
+    return false;
+  }
+
+  function lineScreenEndpoints(svg, line) {
+    if (typeof line.getScreenCTM !== "function" || typeof svg.createSVGPoint !== "function") {
+      return null;
+    }
+    const matrix = line.getScreenCTM();
+    if (!matrix) return null;
+    const map = (x, y) => {
+      const point = svg.createSVGPoint();
+      point.x = x;
+      point.y = y;
+      const mapped = point.matrixTransform(matrix);
+      return { x: mapped.x, y: mapped.y };
+    };
+    return {
+      start: map(line.x1.baseVal.value, line.y1.baseVal.value),
+      end: map(line.x2.baseVal.value, line.y2.baseVal.value),
+    };
+  }
+
+  // Read a near-circular stroke <path> as a ring/hub node box (ring flag from fill), or null if not a resolvable hub; getPointAtLength is guarded so one bad path can't abort the sampler.
+  function ringPathBox(path, rootRect) {
+    if (typeof path.getTotalLength !== "function" || typeof path.getPointAtLength !== "function") {
+      return null;
+    }
+    let total;
+    try {
+      total = path.getTotalLength();
+    } catch {
+      return null;
+    }
+    if (!Number.isFinite(total) || total < CONNECTOR_RING_MIN_LEN) return null;
+    const points = [];
+    try {
+      for (let i = 0; i < 16; i++) {
+        const local = path.getPointAtLength((total * i) / 16);
+        points.push({ x: local.x, y: local.y });
+      }
+    } catch {
+      return null;
+    }
+    const fit = fitCirclePoints(points);
+    if (!fit || fit.radius < CONNECTOR_RING_MIN_RADIUS) return null;
+    if (fit.residual > CONNECTOR_RING_MAX_RESIDUAL_FRAC * fit.radius) return null;
+    const rect = toRect(path.getBoundingClientRect());
+    // Reject the shallow-curvature phantom fit: a nearly-straight arc masquerades as a huge ring, so the fitted diameter must stay within a sane factor of the bbox.
+    const bboxSpan = Math.max(rect.width, rect.height);
+    if (bboxSpan <= 0 || fit.radius * 2 > CONNECTOR_RING_MAX_DIAMETER_BBOX_FRAC * bboxSpan) {
+      return null;
+    }
+    // Known narrow seams left as-is: a sliver partial arc can miss the span gate, and a near-circular connector can read as its own ring node — both rare vs. the false ring this gate closes.
+    const area = rectArea(rect);
+    if (area < CONNECTOR_NODE_MIN_DOT_AREA || area >= rectArea(rootRect) * 0.5) return null;
+    const fill = getComputedStyle(path).fill;
+    return {
+      selector: selectorFor(path),
+      left: rect.left,
+      top: rect.top,
+      right: rect.right,
+      bottom: rect.bottom,
+      ring: fill === "none" || fill === "transparent" || path.getAttribute("fill") === "none",
+    };
+  }
+
+  function connectorNodeBoxes(root, rootRect) {
+    const boxes = [];
+    const rootArea = rectArea(rootRect);
+    for (const element of Array.from(root.querySelectorAll("*"))) {
+      if (boxes.length >= CONNECTOR_NODE_CAP) break;
+      if (element.closest("svg") || !isVisibleElement(element, 0.05)) continue;
+      const opaque =
+        RASTER_TAGS.has(element.tagName) || hasOpaqueBackground(getComputedStyle(element));
+      if (!opaque && !textContentFor(element)) continue;
+      const rect = toRect(element.getBoundingClientRect());
+      const area = rectArea(rect);
+      if (area < CONNECTOR_NODE_MIN_AREA || area >= rootArea * 0.5) continue;
+      boxes.push({
+        selector: selectorFor(element),
+        left: rect.left,
+        top: rect.top,
+        right: rect.right,
+        bottom: rect.bottom,
+        ring: false,
+      });
+    }
+    for (const shape of Array.from(root.querySelectorAll("circle, ellipse, rect"))) {
+      if (boxes.length >= CONNECTOR_NODE_CAP) break;
+      if (!isVisibleElement(shape, 0.05)) continue;
+      const rect = toRect(shape.getBoundingClientRect());
+      const area = rectArea(rect);
+      if (area < CONNECTOR_NODE_MIN_DOT_AREA || area >= rootArea * 0.5) continue;
+      const fill = getComputedStyle(shape).fill;
+      boxes.push({
+        selector: selectorFor(shape),
+        left: rect.left,
+        top: rect.top,
+        right: rect.right,
+        bottom: rect.bottom,
+        ring: fill === "none" || fill === "transparent" || shape.getAttribute("fill") === "none",
+      });
+    }
+    for (const path of Array.from(root.querySelectorAll("path"))) {
+      if (boxes.length >= CONNECTOR_NODE_CAP) break;
+      if (path.closest(CONNECTOR_SKIP_CONTAINERS)) continue;
+      if (!isVisibleElement(path, 0.05)) continue;
+      const box = ringPathBox(path, rootRect);
+      if (box) boxes.push(box);
+    }
+    return boxes;
+  }
+
+  window.__hyperframesConnectorSample = function collectConnectorSample() {
+    const root =
+      document.querySelector("[data-composition-id][data-width][data-height]") ||
+      document.querySelector("[data-composition-id]") ||
+      document.body;
+    const rootRect = rootRectFor(root);
+    const connectors = [];
+    for (const svg of Array.from(root.querySelectorAll("svg"))) {
+      if (!isVisibleElement(svg, 0.05) || hasAllowOverflowFlag(svg)) continue;
+      const svgRect = svg.getBoundingClientRect();
+      if (svgRect.width < CONNECTOR_MIN_SVG_PX || svgRect.height < CONNECTOR_MIN_SVG_PX) continue;
+      for (const line of Array.from(svg.querySelectorAll("line, path, polyline"))) {
+        if (line.closest(CONNECTOR_SKIP_CONTAINERS)) continue;
+        // Stroke-inflated: an axis-aligned line has a zero-height/width client rect, so the plain visibility gate drops it.
+        if (!isVisibleElement(line, 0.05)) continue;
+        if (isIndicatorConnector(line, svg)) continue;
+        if (!isMotionConnectorCandidate(svg, line)) continue;
+        const ends =
+          line.tagName.toLowerCase() === "line"
+            ? lineScreenEndpoints(svg, line)
+            : pathScreenEndpoints(svg, line);
+        if (!ends) continue;
+        const len = Math.hypot(ends.end.x - ends.start.x, ends.end.y - ends.start.y);
+        if (len < CONNECTOR_MIN_LEN_PX) continue;
+        connectors.push({
+          selector: selectorFor(line),
+          ax: round(ends.start.x),
+          ay: round(ends.start.y),
+          bx: round(ends.end.x),
+          by: round(ends.end.y),
+        });
+      }
+    }
+    return { connectors, nodes: connectorNodeBoxes(root, rootRect) };
+  };
 })();

packages/cli/src/commands/layout-audit.browser.test.ts

@@ -877,6 +877,44 @@ describe("layout-audit.browser coordinate-frame findings", () => {
     // "knowledge-overflow" contains conn-family substrings only across word boundaries — no match.
     expect(runAudit().filter((issue) => issue.code === "connector_detached")).toEqual([]);
   });
+
+  it("rejects a shallow-curvature arc as a phantom ring node but keeps a genuine near-circular arc", () => {
+    document.body.innerHTML = `
+      <div id="root" data-composition-id="main" data-width="1920" data-height="1080">
+        <svg id="dial-svg">
+          <path id="genuine-ring" fill="none" d="ring" />
+          <path id="shallow-arc" fill="none" d="arc" />
+        </svg>
+      </div>
+    `;
+    // Shallow arc on a huge circle passes the residual gate yet its fitted diameter is ~10x its drawn box — the phantom-radius case, vs a genuine near-full circle.
+    const genuine = { cx: 500, cy: 500, radius: 100, startDeg: 0, endDeg: 360 };
+    const shallow = { cx: 500, cy: 2500, radius: 2000, startDeg: 264, endDeg: 276 };
+    installGeometry(
+      {
+        root: rect({ left: 0, top: 0, width: 1920, height: 1080 }),
+        "dial-svg": rect({ left: 200, top: 200, width: 700, height: 700 }),
+        "genuine-ring": arcBBox(genuine),
+        "shallow-arc": arcBBox(shallow),
+      },
+      {
+        "genuine-ring": { fill: "none" },
+        "shallow-arc": { fill: "none" },
+      },
+    );
+    installArcSampling("genuine-ring", genuine);
+    installArcSampling("shallow-arc", shallow);
+    installAuditScript();
+
+    const sample = (
+      window as unknown as {
+        __hyperframesConnectorSample: () => { nodes: Array<{ selector: string }> };
+      }
+    ).__hyperframesConnectorSample();
+    const nodeSelectors = sample.nodes.map((node) => node.selector);
+    expect(nodeSelectors).toContain("#genuine-ring");
+    expect(nodeSelectors).not.toContain("#shallow-arc");
+  });
 });
 
 describe("layout-audit.browser content overlap", () => {
@@ -1979,6 +2017,52 @@ function installConnectorGeometry(translate: CtmTranslate): void {
   }
 }
 
+interface ArcSpec {
+  cx: number;
+  cy: number;
+  radius: number;
+  startDeg: number;
+  endDeg: number;
+}
+
+// The point ringPathBox reads at arc-length `length` (local SVG user units).
+function arcPointAt(spec: ArcSpec, length: number, total: number): { x: number; y: number } {
+  const frac = total === 0 ? 0 : length / total;
+  const rad = ((spec.startDeg + (spec.endDeg - spec.startDeg) * frac) * Math.PI) / 180;
+  return { x: spec.cx + spec.radius * Math.cos(rad), y: spec.cy + spec.radius * Math.sin(rad) };
+}
+
+function arcTotalLength(spec: ArcSpec): number {
+  return (spec.radius * Math.abs(spec.endDeg - spec.startDeg) * Math.PI) / 180;
+}
+
+// The bounding box of the 16 samples ringPathBox takes (i/16 of total, i=0..15).
+function arcBBox(spec: ArcSpec): DOMRect {
+  const total = arcTotalLength(spec);
+  const xs: number[] = [];
+  const ys: number[] = [];
+  for (let i = 0; i < 16; i++) {
+    const point = arcPointAt(spec, (total * i) / 16, total);
+    xs.push(point.x);
+    ys.push(point.y);
+  }
+  const left = Math.min(...xs);
+  const top = Math.min(...ys);
+  return rect({ left, top, width: Math.max(...xs) - left, height: Math.max(...ys) - top });
+}
+
+// happy-dom has no SVG path geometry: mock getTotalLength/getPointAtLength so ringPathBox can sample the given arc.
+function installArcSampling(pathId: string, spec: ArcSpec): void {
+  const path = document.getElementById(pathId);
+  if (!path) throw new Error(`no path #${pathId}`);
+  const total = arcTotalLength(spec);
+  Object.defineProperty(path, "getTotalLength", { value: () => total, configurable: true });
+  Object.defineProperty(path, "getPointAtLength", {
+    value: (length: number) => arcPointAt(spec, length, total),
+    configurable: true,
+  });
+}
+
 function installAuditScript(): void {
   window.eval(script);
 }

packages/cli/src/utils/checkBrowser.ts

@@ -39,6 +39,9 @@ import type {
   CheckGeometryCandidate,
   CheckOptions,
   CheckSeverity,
+  ConnectorFrame,
+  ConnectorLineSample,
+  ConnectorNodeBox,
   ContrastAuditEntry,
   ContrastCapture,
   GeometryCandidateRequest,
@@ -358,6 +361,7 @@ function createPageDriver(page: Page, setTime: (time: number) => void): CheckAud
     collectLayoutGeometry: () => collectLayoutGeometry(page),
     collectRotationSample: (time) => collectRotationSample(page, time),
     collectOffPivotRotationSample: (time) => collectOffPivotRotationSample(page, time),
+    collectConnectorSample: (time) => collectConnectorSample(page, time),
     collectGeometryCandidates: (time, request) => collectGeometryCandidates(page, time, request),
     collectMotionFrame: (time, selectors, scopes) =>
       collectMotionFrame(page, time, selectors, scopes),
@@ -568,6 +572,44 @@ function parseOffPivotRotationSample(value: unknown): OffPivotRotationSample[] {
   ];
 }
 
+async function collectConnectorSample(page: Page, time: number): Promise<ConnectorFrame> {
+  const raw = await page.evaluate(() => {
+    const sample = Reflect.get(window, "__hyperframesConnectorSample");
+    if (typeof sample !== "function") return null;
+    return Reflect.apply(sample, window, []);
+  });
+  if (!isRecord(raw)) return { time, connectors: [], nodes: [] };
+  const connectors = Array.isArray(raw.connectors) ? raw.connectors : [];
+  const nodes = Array.isArray(raw.nodes) ? raw.nodes : [];
+  return {
+    time,
+    connectors: connectors.flatMap(parseConnectorLine),
+    nodes: nodes.flatMap(parseConnectorNode),
+  };
+}
+
+function parseConnectorLine(value: unknown): ConnectorLineSample[] {
+  if (!isRecord(value)) return [];
+  const selector = stringValue(value, "selector");
+  const ax = numberValue(value, "ax");
+  const ay = numberValue(value, "ay");
+  const bx = numberValue(value, "bx");
+  const by = numberValue(value, "by");
+  if (!selector || ax === null || ay === null || bx === null || by === null) return [];
+  return [{ selector, ax, ay, bx, by }];
+}
+
+function parseConnectorNode(value: unknown): ConnectorNodeBox[] {
+  if (!isRecord(value)) return [];
+  const selector = stringValue(value, "selector");
+  const left = numberValue(value, "left");
+  const top = numberValue(value, "top");
+  const right = numberValue(value, "right");
+  const bottom = numberValue(value, "bottom");
+  if (!selector || left === null || top === null || right === null || bottom === null) return [];
+  return [{ selector, left, top, right, bottom, ring: value.ring === true }];
+}
+
 async function collectGeometryCandidates(
   page: Page,
   time: number,
@@ -1151,6 +1193,7 @@ const LAYOUT_ISSUE_CODES: readonly LayoutIssueCode[] = [
   "escaped_container",
   "panel_out_of_canvas",
   "connector_detached",
+  "connector_motion_detached",
   "rotation_pivot_drift",
   "off_pivot_rotation",
   "motion_appears_late",