style: collapse multi-line comments to single lines

Author: xuanruli

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

@@ -1233,10 +1233,7 @@
       const mapped = point.matrixTransform(matrix);
       return { x: mapped.x, y: mapped.y };
     };
-    // getPointAtLength can still throw on a degenerate/malformed path even after
-    // getTotalLength succeeded. This sampler runs once PER seeked frame, so one
-    // bad path must degrade to "no endpoints" (skip this path), not abort the
-    // whole check for every remaining path and frame.
+    // 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)),
@@ -1743,34 +1740,20 @@
     return samples;
   };
 
-  // connector_motion_detached sampling. Per seeked frame, report every diagram
-  // connector's two screen-space endpoints AND every plausible node/box bbox.
-  // Node accumulates these across the grid and flags an endpoint that stays
-  // anchored to a node while the other endpoint sits in empty space on the held
-  // frames — a connector whose coordinates were frozen (wrong rotation pivot, or
-  // measured once at build) while its target kept moving. Icon-sized SVGs and
-  // short strokes are filtered out so only real diagram connectors count.
+  // 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, not node-to-node
-  // connectors — a separate (gauge) check owns them. Skip by id/class of the line
-  // or any group ancestor up to the SVG.
+  // 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.
   const CONNECTOR_INDICATOR_NAME = /needle|pointer|gauge|tick|indicator/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;
-  // A stroke-drawn dial/hub ring may be an <path> arc (M...A...), not a <circle>.
-  // Recognize near-circular stroke paths as ring nodes so connectors attaching
-  // to them aren't false-flagged as detached, and so the gauge-indicator geometry
-  // exclusion (which keys on ring nodes) can see arc-drawn dials too.
+  // 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 real ring/hub's fitted diameter tracks its bounding
-  // box (full circle 1x, quarter arc ~2x). A shallow-curvature arc fits an
-  // enormous circle with a tiny normalized residual, so the diameter runs many×
-  // the box — reject beyond this factor.
+  // 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) {
@@ -1799,13 +1782,7 @@
     };
   }
 
-  // Node/box candidates a connector could anchor to: sized, opaque or text-
-  // bearing HTML elements plus SVG hub/ring/dot shapes. A shape drawn stroke-only
-  // (fill:none) is a ring — the connector attaches to its stroke, so it is marked
-  // `ring` and matched by perimeter, not hollow interior (see pointToNodeGap).
-  // A near-circular stroke <path> read as a ring/hub node. Returns a node box
-  // (ring flag from fill) or null when the path is not a resolvable circular hub.
-  // getPointAtLength is guarded — one malformed path must not abort the sampler.
+  // 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;
@@ -1830,18 +1807,12 @@
     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: normalized residual is small at
-    // any radius, so a nearly-straight arc masquerades as a huge ring. The
-    // fitted diameter must stay within a sane factor of the drawn bounding box.
+    // 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;
     }
-    // Scoped-known seams (left as-is — narrow and not phantom-radius): a short
-    // genuine partial arc under-samples its parent circle's box so a real hub
-    // drawn as a sliver can still miss the span gate; and a curved connector
-    // that is itself near-circular can be read as its own ring node. Both are
-    // rare vs. the shallow-curvature false ring this gate closes.
+    // 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;

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

@@ -887,9 +887,7 @@ describe("layout-audit.browser coordinate-frame findings", () => {
         </svg>
       </div>
     `;
-    // A near-full circle (diameter tracks its bbox) vs a shallow arc on a huge
-    // circle: the arc's Kåsa residual normalized by its enormous radius is tiny
-    // (passes the residual gate) yet its fitted diameter is ~10x its drawn box.
+    // 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(
@@ -2053,8 +2051,7 @@ function arcBBox(spec: ArcSpec): DOMRect {
   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 samples the given circular arc in local user units.
+// 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}`);

packages/cli/src/utils/checkPipeline.connectorMotionDetached.test.ts

@@ -30,8 +30,7 @@ function frame(
   return { time, connectors: [connector], nodes };
 }
 
-/** A dangling connector: end A stays on the hub, end B sits ~180px from every
- * node across all held frames — the half-attached signature (fuzz011). */
+/** A dangling connector: end A stays on the hub, end B sits ~180px from every node across held frames — the half-attached signature (fuzz011). */
 function danglingFrames(): ConnectorFrame[] {
   return [0, 2, 4, 6, 8].map((time) =>
     frame(time, { selector: "#spoke", ax: 500, ay: 500, bx: 640, by: 500 }, [HUB, SATELLITE]),
@@ -88,10 +87,7 @@ describe("detectConnectorMotionDetached", () => {
   });
 
   it("flags a loose end that only touches a node in ONE held frame then detaches the rest", () => {
-    // End A stays pinned to the hub; end B lands on the satellite for a single
-    // held frame (t=4) then dangles ~120px away for the rest of the held window.
-    // A lone graze is NOT sustained attachment, so B must read as dangling and
-    // the connector must be flagged — not cleared by the single touch.
+    // A lone graze (B touches the satellite once at t=4, dangles the rest) is not sustained attachment, so B must still read as dangling and the connector be flagged.
     const held: ConnectorFrame[] = [0, 2, 4, 5, 6, 7, 8].map((time) => {
       const bx = time === 4 ? 820 : 640; // on satellite once, dangling otherwise
       return frame(time, { selector: "#spoke", ax: 500, ay: 500, bx, by: 500 }, [HUB, SATELLITE]);
@@ -102,9 +98,7 @@ describe("detectConnectorMotionDetached", () => {
   });
 
   it("keeps an endpoint anchored when it stays within tolerance across the held window", () => {
-    // The mirror case: B sits on the satellite for every held frame but one — a
-    // single-frame graze OFF a node does not turn a sustained anchor into a
-    // dangle, so nothing fires.
+    // Mirror case: a single-frame graze OFF a node doesn't turn a sustained anchor into a dangle, so nothing fires.
     const held: ConnectorFrame[] = [0, 2, 4, 5, 6, 7, 8].map((time) => {
       const bx = time === 6 ? 640 : 820; // off-node once, on the satellite otherwise
       return frame(time, { selector: "#spoke", ax: 500, ay: 500, bx, by: 500 }, [HUB, SATELLITE]);
@@ -131,8 +125,7 @@ describe("detectConnectorMotionDetached", () => {
   });
 
   it("does not fire on a gauge needle: anchored at the arc centre, loose end radially outward", () => {
-    // Arc ring centred at 900,500; needle base on the hub near centre, tip out
-    // past the arc — a pointer, not a broken connector.
+    // Arc ring at 900,500 with the needle base near centre and tip past the arc — a pointer, not a broken connector.
     const hub: ConnectorNodeBox = {
       selector: "#hub",
       left: 890,
@@ -156,8 +149,7 @@ describe("detectConnectorMotionDetached", () => {
   });
 
   it("still fires on a radial connector drifting toward the centre (not outward)", () => {
-    // Anchored on a peripheral node; loose end drifts inward to empty space near
-    // a ring centre — the fuzz011 shape, opposite of a gauge pointer.
+    // Anchored on a peripheral node with the loose end drifting inward to empty space near a ring centre — the fuzz011 shape, opposite of a gauge pointer.
     const peripheral: ConnectorNodeBox = {
       selector: "#panel",
       left: 120,

packages/cli/src/utils/checkPipeline.ts

@@ -201,8 +201,7 @@ interface GridSamples {
    * material-point geometry + dial hub per layout sample; flattened by selector
    * to detect off_pivot_rotation. */
   indicatorFrames: OffPivotFrame[];
-  /** Connector endpoints + node boxes at each layout sample; correlated after
-   * the run to detect connector_motion_detached. */
+  /** Connector endpoints + node boxes per layout sample; correlated after the run to detect connector_motion_detached. */
   connectorFrames: ConnectorFrame[];
 }
 
@@ -985,27 +984,19 @@ export function detectOffPivotRotation(frames: OffPivotFrame[]): AnchoredLayoutI
   return selectHubFindings(candidates);
 }
 
-// connector_motion_detached thresholds. Corpus timings: entrances settle by
-// ~2s of a 7-8s composition, so held/steady state starts well before half.
+// connector_motion_detached thresholds.
 const CONNECTOR_MIN_FRAMES = 4;
 // An endpoint within this of a node counts as anchored (well under a node's size).
 const CONNECTOR_ATTACH_PX = 24;
-// The dangling end must clear this to flag. Set high, and measured against a
-// dense node-candidate set, so only an endpoint sitting in genuinely empty space
-// fires — a slow drift that still lands near a box, or a snug residual gap, does
-// not. Corpus: fuzz011's detached spokes dangle ~185-190px from every node;
-// legitimate lead-lines to a nearby label stay well under this.
+// Detach floor: set high and measured against a dense node set, so only an endpoint in genuinely empty space fires (not a snug gap or lead-line).
 const CONNECTOR_DETACH_FLOOR_PX = 80;
 const CONNECTOR_DETACH_VIEWPORT_FRACTION = 0.06;
 // Held/steady frames begin at this fraction of the timeline (past entrances).
 const CONNECTOR_HELD_START_FRAC = 0.45;
 const CONNECTOR_MIN_HELD_FRAMES = 2;
 // Fraction of held frames on which the loose end must be detached to flag.
 const CONNECTOR_HELD_DETACH_FRAC = 0.8;
-// Fraction of held frames an endpoint must stay within attach tolerance to
-// count as ANCHORED. A single-frame graze is not attachment: a genuinely
-// detached endpoint that merely touches a node once must not read as anchored
-// (else its dangling partner escapes the finding). Sustained, not instantaneous.
+// Fraction of held frames within attach tolerance to count as anchored — sustained, so a single-frame graze doesn't let a dangling partner escape.
 const CONNECTOR_HELD_ATTACH_FRAC = 0.8;
 
 interface ConnectorObservation {
@@ -1021,8 +1012,7 @@ function pointToNodeGap(x: number, y: number, node: ConnectorNodeBox): number {
   const dx = Math.max(node.left - x, 0, x - node.right);
   const dy = Math.max(node.top - y, 0, y - node.bottom);
   if (dx > 0 || dy > 0) return Math.hypot(dx, dy);
-  // Inside the bbox: a solid node anchors anywhere; a hollow ring only near its
-  // stroke, so measure distance to the bbox perimeter (its hole is not attached).
+  // Inside the bbox: a solid node anchors anywhere; a hollow ring only near its stroke, so measure distance to the perimeter.
   if (!node.ring) return 0;
   return Math.min(x - node.left, node.right - x, y - node.top, node.bottom - y);
 }
@@ -1033,9 +1023,7 @@ function nearestNodeGap(x: number, y: number, nodes: ConnectorNodeBox[]): number
   return min;
 }
 
-/** Group observations by connector selector, dropping any selector that maps to
- * more than one connector in a single frame — those endpoints can't be tracked
- * across seeks without aliasing (the false-association risk). */
+/** Group observations by connector selector, dropping any selector that aliases multiple connectors in one frame (untrackable across seeks). */
 function groupConnectorsBySelector(frames: ConnectorFrame[]): Map<string, ConnectorObservation[]> {
   const bySelector = new Map<string, ConnectorObservation[]>();
   const ambiguous = new Set<string>();
@@ -1067,10 +1055,7 @@ interface EndpointHeldGaps {
   danglingGap: number;
 }
 
-/** Per-endpoint held-frame gap summary: the fraction of held frames it sits
- * within attach tolerance of a node (sustained attachment, not a lone graze),
- * the fraction it sits beyond the detach threshold, and the gap it settles at
- * when detached. */
+/** Per-endpoint held-frame gap summary: fractions within attach tolerance and beyond the detach threshold, plus the settled dangling gap. */
 function endpointHeldGaps(
   group: ConnectorObservation[],
   pick: (o: ConnectorObservation) => { x: number; y: number },
@@ -1101,11 +1086,7 @@ function isDangling(gaps: EndpointHeldGaps): boolean {
   return gaps.detachedFraction >= CONNECTOR_HELD_DETACH_FRAC;
 }
 
-// Gauge-indicator geometry: the anchored end pivots near a ring/arc centre and
-// the loose end extends radially outward. That is a needle/pointer (owned by a
-// separate gauge check), not a broken node connector. A defective radial
-// connector points the other way — anchored on a peripheral node, loose end
-// drifting toward the centre — so this only excludes true centre-pivot pointers.
+// Gauge indicator: anchored end pivots near a ring centre, loose end extends outward — a needle (owned by a separate gauge check), so exclude only true centre-pivot pointers.
 const GAUGE_HUB_CENTRE_FRACTION = 0.25;
 
 function isGaugeIndicator(
@@ -1154,32 +1135,14 @@ function connectorDetachFinding(
   };
 }
 
-/**
- * connector_motion_detached: a connector (SVG <line>/<path>) that stays anchored
- * to a node at ONE endpoint while its OTHER endpoint sits in empty space — far
- * from every node — across the held (steady) frames. This is the sibling of the
- * per-frame `connector_detached` check, which requires BOTH endpoints far from
- * anchors on a single frame and so deliberately ignores the half-attached case.
- * But that half-attached case is the dominant real failure under motion: a
- * spoke/edge whose one end stays pinned (e.g. at a hub) while the other drifts
- * off a node that kept moving — rotated about a wrong pivot, or with a path
- * measured once at build then never updated as the target animated.
- *
- * FP-guarded, deliberately strict: one endpoint must be genuinely anchored
- * (structural, not a name match); the loose end must clear a high detach
- * threshold on ~all held frames (measured against a dense node-candidate set, so
- * only an endpoint in truly empty space fires — snug residual gaps and lead
- * lines to a nearby label do not); and a selector that aliases multiple
- * connectors in one frame is dropped.
- */
+/** connector_motion_detached: the half-attached case connector_detached ignores — one endpoint pinned while the other drifts into empty space across held frames (wrong pivot, or coords measured once at build). Strict + FP-guarded. */
 interface DanglePick {
   anchored: { x: number; y: number };
   dangling: { x: number; y: number };
   gap: number;
 }
 
-/** If exactly one endpoint is anchored and the other persistently dangles, name
- * the anchored/dangling points and the dangling gap; else null. */
+/** If exactly one endpoint is anchored and the other persistently dangles, name the anchored/dangling points and the gap; else null. */
 function danglingEndpoint(
   last: ConnectorObservation,
   gapsA: EndpointHeldGaps,
@@ -1196,9 +1159,7 @@ function danglingEndpoint(
   return null;
 }
 
-/** One connector's held trajectory → a finding, or null. A finding needs one
- * endpoint anchored to a node and the other persistently in empty space, and is
- * suppressed for gauge-indicator geometry (see isGaugeIndicator). */
+/** One connector's held trajectory → a finding, or null; needs one anchored endpoint and one persistently in empty space, suppressed for gauge-indicator geometry. */
 function connectorGroupFinding(
   selector: string,
   group: ConnectorObservation[],

packages/cli/src/utils/checkTypes.ts

@@ -170,8 +170,7 @@ export interface ConnectorLineSample {
   by: number;
 }
 
-/** Screen bbox of one plausible node/box a connector could anchor to. `ring`
- * marks a stroke-only SVG shape matched by perimeter, not hollow interior. */
+/** Screen bbox of a node a connector could anchor to; `ring` marks a stroke-only SVG shape matched by perimeter, not hollow interior. */
 export interface ConnectorNodeBox {
   selector: string;
   left: number;
@@ -181,9 +180,7 @@ export interface ConnectorNodeBox {
   ring: boolean;
 }
 
-/** All connectors + node boxes at one seeked sample, produced by
- * `__hyperframesConnectorSample` and accumulated across the grid to detect
- * `connector_motion_detached`. */
+/** All connectors + node boxes at one seeked sample, accumulated across the grid to detect connector_motion_detached. */
 export interface ConnectorFrame {
   time: number;
   connectors: ConnectorLineSample[];
@@ -218,8 +215,7 @@ export interface CheckAuditDriver {
    * geometry + resolved dial hub at the current seeked state, as a time-hoisted
    * frame envelope. */
   collectOffPivotRotationSample(time: number): Promise<OffPivotFrame>;
-  /** connector_motion_detached: every connector's endpoints + every node bbox
-   * at the current seeked state. Accumulated across the grid — see checkPipeline. */
+  /** connector_motion_detached: every connector's endpoints + every node bbox at the current seeked state, accumulated across the grid. */
   collectConnectorSample(time: number): Promise<ConnectorFrame>;
   collectGeometryCandidates(
     time: number,