@cyber-dash-tech/revela 0.1.1 → 0.1.3

package/lib/qa/checks.ts

@@ -1,29 +1,30 @@
 /**
  * lib/qa/checks.ts
  *
- * Pure geometry-based layout checks — no class-name dependency.
+ * Geometry-based layout quality checks — four orthogonal visual dimensions.
+ *
+ * Dimension 1: Overflow   — elements exceed canvas bounds (correctness)
+ * Dimension 2: Balance    — content centroid & distribution (fill, sparsity)
+ * Dimension 3: Symmetry   — side-by-side element consistency (height, density)
+ * Dimension 4: Rhythm     — spacing regularity & internal whitespace
  *
  * All checks operate on SlideMetrics produced by measure.ts.
- * The checks are designed to be design-system-agnostic: they detect
- * structural layout problems regardless of CSS class names or component types.
+ * Design-system-agnostic: no CSS class-name assumptions.
  */
 
 import type { SlideMetrics, ElementInfo, Rect } from "./measure"
 import { CANVAS_W, CANVAS_H } from "./measure"
 
-// ── Types ────────────────────────────────────────────────────────────────────
+// ── Types ─────────────────────────────────────────────────────────────────────
 
 export type IssueSeverity = "error" | "warning" | "info"
 
 export interface LayoutIssue {
-  type:
-    | "underfill"        // canvas not filled enough
-    | "bottom_whitespace" // large gap at bottom of slide
-    | "asymmetry"        // side-by-side elements with large height difference
-    | "density_imbalance" // side-by-side columns with very different content density
-    | "overflow"         // element exceeds canvas bounds
-    | "sparse"           // very few visible elements
-    | "card_height_variance" // cards in same row have very different heights
+  type: "overflow" | "balance" | "symmetry" | "rhythm"
+  /** Sub-category within the dimension */
+  sub?: "centroid_offset" | "bottom_gap" | "sparse"
+      | "height_mismatch" | "density_mismatch"
+      | "gap_variance"
   severity: IssueSeverity
   /** Human-readable description for the LLM to act on */
   detail: string
@@ -46,76 +47,36 @@ export interface QAReport {
   summary: string
 }
 
-// ── Slide type registry — single source of truth ─────────────────────────────
-
-/**
- * All valid values for the `data-slide-type` attribute on `<section class="slide">`.
- *
- * This is the single source of truth consumed by:
- *   - QA checks (EXEMPT_TYPES below)
- *   - prompt-builder.ts (injected into SKILL.md via <!-- @slide-types --> placeholder)
- */
-export const SLIDE_TYPES = [
-  "cover",
-  "toc",
-  "content",
-  "summary",
-  "closing",
-  "divider",
-  "thank-you",
-] as const
-
-export type SlideType = (typeof SLIDE_TYPES)[number]
-
-// ── Thresholds (tunable) ─────────────────────────────────────────────────────
-
-/**
- * Slide types that are intentionally sparse, centred, or structurally
- * different from "content" slides. Fill ratio and bottom-whitespace checks
- * are skipped for these types.
- *
- * The AI populates `data-slide-type` on each `<section class="slide">`.
- * When the attribute is absent (old HTML), we fall back to geometry.
- */
-export const EXEMPT_TYPES: ReadonlySet<string> = new Set<SlideType>([
-  "cover",
-  "toc",
-  "closing",
-  "divider",
-  "summary",
-  "thank-you",
-])
+// ── Thresholds ────────────────────────────────────────────────────────────────
 
 const T = {
-  /** Canvas fill ratio below this → underfill warning */
-  FILL_WARN: 0.55,
-  /** Canvas fill ratio below this → underfill error */
-  FILL_ERROR: 0.40,
-  /** Bottom whitespace (px inside 1080-height canvas) above this → warning */
-  BOTTOM_WS_WARN: 200,
-  /** Bottom whitespace above this → error */
-  BOTTOM_WS_ERROR: 350,
-  /** Height asymmetry ratio (shorter/taller) below this → warning */
-  ASYM_WARN: 0.70,
-  /** Height asymmetry ratio below this → error */
-  ASYM_ERROR: 0.50,
-  /** Content density ratio (fewer/more leaf elements) for side-by-side columns → warning */
-  DENSITY_WARN: 0.55,
-  /** Content density ratio below this → error */
-  DENSITY_ERROR: 0.35,
-  /** Min horizontal overlap fraction to consider two elements "in the same row" */
-  ROW_OVERLAP: 0.3,
-  /** Min width of an element to be considered a "column" (not just an icon) */
-  COL_MIN_WIDTH: 200,
-  /** Visible top-level element count below this → sparse */
+  // Balance — centroid offset (fraction of canvas half-dimension)
+  CENTROID_WARN: 0.25,
+  CENTROID_ERROR: 0.35,
+  // Balance — bottom gap (px)
+  BOTTOM_GAP_WARN: 200,
+  BOTTOM_GAP_ERROR: 350,
+  // Balance — sparse: fewer than this many visible top-level elements
   SPARSE_THRESHOLD: 2,
-  /** Card height ratio (min/max in same row) below this → variance warning */
-  CARD_VAR_WARN: 0.65,
+  // Symmetry — min/max ratio for height, content-height, leaf count
+  SYM_WARN: 0.70,
+  SYM_ERROR: 0.50,
+  // Symmetry — min element width to be considered a layout column
+  COL_MIN_WIDTH: 200,
+  // Symmetry — min vertical overlap fraction to consider elements "in the same row"
+  ROW_OVERLAP: 0.30,
+  // Rhythm — gap variance: coefficient of variation threshold
+  GAP_CV_WARN: 0.60,
+  GAP_CV_ERROR: 1.00,
+  // Rhythm — min mean gap (px) to bother checking variance
+  GAP_MIN_MEAN: 10,
+  // Rhythm — min children count to check gap variance
+  GAP_MIN_CHILDREN: 3,
 }
 
-// ── Geometry helpers ─────────────────────────────────────────────────────────
+// ── Geometry helpers ──────────────────────────────────────────────────────────
 
-/** Vertical overlap between two rects [0..1] relative to the shorter one. */
+/** Vertical overlap [0..1] relative to the shorter element. */
 function verticalOverlap(a: Rect, b: Rect): number {
   const overlapTop = Math.max(a.top, b.top)
   const overlapBot = Math.min(a.bottom, b.bottom)
@@ -124,7 +85,7 @@ function verticalOverlap(a: Rect, b: Rect): number {
   return shorter > 0 ? overlap / shorter : 0
 }
 
-/** Horizontal overlap [0..1] relative to the shorter width. */
+/** Horizontal overlap [0..1] relative to the shorter element. */
 function horizontalOverlap(a: Rect, b: Rect): number {
   const ol = Math.max(a.left, b.left)
   const or = Math.min(a.right, b.right)
@@ -134,13 +95,11 @@ function horizontalOverlap(a: Rect, b: Rect): number {
 }
 
 /**
- * Group a list of elements into "rows": elements whose vertical centres are
- * close enough that they appear side-by-side.
- *
- * Returns an array of rows; each row is an array of ElementInfo sorted left→right.
+ * Group elements into rows: elements with significant vertical overlap are
+ * considered side-by-side. Each row is sorted left→right.
+ * Only elements wide enough to be layout columns are considered.
  */
 function groupIntoRows(elements: ElementInfo[]): ElementInfo[][] {
-  // Only consider elements wide enough to be layout columns
   const candidates = elements.filter(
     (e) => e.visible && e.rect.width >= T.COL_MIN_WIDTH
   )
@@ -156,7 +115,6 @@ function groupIntoRows(elements: ElementInfo[]): ElementInfo[][] {
 
     for (let j = i + 1; j < candidates.length; j++) {
       if (assigned.has(j)) continue
-      // Two elements are in the same row if they have significant vertical overlap
       if (verticalOverlap(candidates[i].rect, candidates[j].rect) >= T.ROW_OVERLAP) {
         row.push(candidates[j])
         assigned.add(j)
@@ -171,362 +129,411 @@ function groupIntoRows(elements: ElementInfo[]): ElementInfo[][] {
   return rows
 }
 
-// ── Individual checks ────────────────────────────────────────────────────────
+/** Count all leaf (no-child) descendants. */
+/**
+ * Sum of bounding-box areas of all visible leaf descendants.
+ * More accurate than leaf count for density comparisons — charts and large
+ * containers contribute proportionally to their visual footprint.
+ */
+function leafArea(el: ElementInfo): number {
+  if (el.children.length === 0) {
+    return el.visible ? el.rect.width * el.rect.height : 0
+  }
+  return el.children.reduce((sum, ch) => sum + leafArea(ch), 0)
+}
+
+/**
+ * Actual content height of an element: from topmost child top to bottommost
+ * child bottom. Ignores CSS stretch padding on the container itself.
+ */
+function contentHeight(el: ElementInfo): number {
+  if (el.children.length === 0) return el.rect.height
+  let top = Infinity, bottom = -Infinity
+  function walk(list: ElementInfo[]) {
+    for (const ch of list) {
+      if (!ch.visible) continue
+      top = Math.min(top, ch.rect.top)
+      bottom = Math.max(bottom, ch.rect.bottom)
+      if (ch.children.length > 0) walk(ch.children)
+    }
+  }
+  walk(el.children)
+  return top === Infinity ? el.rect.height : bottom - top
+}
+
+/** Collect all visible leaf elements recursively. */
+function collectLeaves(el: ElementInfo): ElementInfo[] {
+  if (el.children.length === 0) return el.visible ? [el] : []
+  return el.children.flatMap(collectLeaves)
+}
+
+// ── Dimension 1: Overflow ─────────────────────────────────────────────────────
+
+/**
+ * Check 1: Overflow — elements extending beyond canvas boundaries.
+ * Hard correctness check; applies to all slide types.
+ */
+function checkOverflow(metrics: SlideMetrics): LayoutIssue[] {
+  const issues: LayoutIssue[] = []
+  const { canvasRect } = metrics
+  const tol = 2 // 2px sub-pixel tolerance
+
+  function walk(els: ElementInfo[]) {
+    for (const el of els) {
+      if (!el.visible) continue
+      const r = el.rect
+      if (
+        r.left < canvasRect.left - tol ||
+        r.top < canvasRect.top - tol ||
+        r.right > canvasRect.right + tol ||
+        r.bottom > canvasRect.bottom + tol
+      ) {
+        issues.push({
+          type: "overflow",
+          severity: "error",
+          detail: `Element \`${el.selector}\` overflows the canvas: rect(${Math.round(r.left)}, ${Math.round(r.top)}, ${Math.round(r.right)}, ${Math.round(r.bottom)}) vs canvas(${Math.round(canvasRect.left)}, ${Math.round(canvasRect.top)}, ${Math.round(canvasRect.right)}, ${Math.round(canvasRect.bottom)})`,
+        })
+      }
+      if (el.children.length > 0) walk(el.children)
+    }
+  }
+
+  walk(metrics.elements)
+  return issues
+}
+
+// ── Dimension 2: Balance ──────────────────────────────────────────────────────
 
-/** Check 1: Canvas fill ratio (content area / total canvas area) */
-function checkFill(metrics: SlideMetrics): LayoutIssue[] {
+/**
+ * Check 2: Balance — content centroid, bottom gap, sparsity.
+ * Only runs when `metrics.slideQa` is true (content-heavy layouts).
+ * Structural/sparse slides (cover, closing, etc.) set slide-qa="false" and are skipped.
+ *
+ * Sub-checks:
+ *   - centroid_offset: weighted centroid deviates too far from canvas centre
+ *   - bottom_gap: large empty gap at bottom of slide
+ *   - sparse: too few visible top-level elements
+ */
+function checkBalance(metrics: SlideMetrics): LayoutIssue[] {
   const issues: LayoutIssue[] = []
-  const { contentRect, canvasRect, elements } = metrics
+  const { elements, contentRect, canvasRect } = metrics
 
+  // Guard: no content at all
   if (contentRect.width === 0 || contentRect.height === 0) {
     issues.push({
-      type: "sparse",
+      type: "balance",
+      sub: "sparse",
       severity: "error",
       detail: "Slide appears to have no visible content.",
     })
     return issues
   }
 
-  // If the slide has an explicit type, use it — no geometry guessing needed
-  if (metrics.slideType && EXEMPT_TYPES.has(metrics.slideType)) return []
-
-  // Fallback for HTML without data-slide-type: detect cover/title slides by
-  // geometry (single dominant column aligned to the centre of the canvas).
-  const isCoverLike = (() => {
-    const contentCenterX = (contentRect.left + contentRect.right) / 2
-    const canvasCenterX = canvasRect.width / 2
-    const centerOffset = Math.abs(contentCenterX - canvasCenterX) / canvasRect.width
-    const maxElemWidth = Math.max(...elements.map((e) => e.rect.width))
-    const isCentered = centerOffset < 0.15 && maxElemWidth < canvasRect.width * 0.65
-    return isCentered
-  })()
-
-  if (isCoverLike) return [] // Skip fill check for cover/title slides (geometry fallback)
+  // Skip balance checks for structural/sparse slides (slide-qa="false")
+  if (!metrics.slideQa) return []
 
-  // Compute content area relative to canvas dimensions
-  const canvasArea = CANVAS_W * CANVAS_H
-  const contentArea = contentRect.width * contentRect.height
-  const fillRatio = contentArea / canvasArea
-
-  if (fillRatio < T.FILL_ERROR) {
-    issues.push({
-      type: "underfill",
-      severity: "error",
-      detail: `Canvas fill ratio is very low (${Math.round(fillRatio * 100)}%). Content only occupies ${Math.round(contentRect.width)}×${Math.round(contentRect.height)}px of the 1920×1080 canvas.`,
-      data: { fillRatio: Math.round(fillRatio * 100) },
-    })
-  } else if (fillRatio < T.FILL_WARN) {
+  // ── Sub-check: sparse ────────────────────────────────────────────────────
+  const visibleCount = elements.filter((e) => e.visible).length
+  if (visibleCount < T.SPARSE_THRESHOLD) {
     issues.push({
-      type: "underfill",
+      type: "balance",
+      sub: "sparse",
       severity: "warning",
-      detail: `Canvas fill ratio is low (${Math.round(fillRatio * 100)}%). Content area: ${Math.round(contentRect.width)}×${Math.round(contentRect.height)}px. Consider expanding content or reducing whitespace.`,
-      data: { fillRatio: Math.round(fillRatio * 100) },
+      detail: `Slide has only ${visibleCount} visible top-level element(s). This may result in a lot of empty space.`,
+      data: { visibleCount },
     })
   }
 
-  return issues
-}
-
-/** Check 2: Bottom whitespace — gap between last content element and canvas bottom */
-function checkBottomWhitespace(metrics: SlideMetrics): LayoutIssue[] {
-  const issues: LayoutIssue[] = []
-  const { contentRect, canvasRect, elements } = metrics
-
-  if (contentRect.height === 0) return issues
+  // ── Sub-check: centroid offset ───────────────────────────────────────────
+  // Collect all leaf elements and compute area-weighted centroid
+  const leaves = elements.flatMap(collectLeaves)
+  if (leaves.length > 0) {
+    let totalArea = 0
+    let weightedX = 0
+    let weightedY = 0
+
+    for (const leaf of leaves) {
+      const area = leaf.rect.width * leaf.rect.height
+      const cx = (leaf.rect.left + leaf.rect.right) / 2
+      const cy = (leaf.rect.top + leaf.rect.bottom) / 2
+      totalArea += area
+      weightedX += cx * area
+      weightedY += cy * area
+    }
 
-  // If the slide has an explicit type, use it — no geometry guessing needed
-  if (metrics.slideType && EXEMPT_TYPES.has(metrics.slideType)) return []
+    if (totalArea > 0) {
+      const centroidX = weightedX / totalArea
+      const centroidY = weightedY / totalArea
 
-  // Fallback geometry: skip cover/title slides (intentionally centred with bottom space)
-  const isCoverLike = (() => {
-    const contentCenterX = (contentRect.left + contentRect.right) / 2
-    const canvasCenterX = canvasRect.width / 2
-    const centerOffset = Math.abs(contentCenterX - canvasCenterX) / canvasRect.width
-    const maxElemWidth = Math.max(...elements.map((e) => e.rect.width))
-    return centerOffset < 0.15 && maxElemWidth < canvasRect.width * 0.65
-  })()
+      // Normalise offset by half-canvas dimensions so both axes are comparable
+      const offsetX = Math.abs(centroidX - canvasRect.width / 2) / (canvasRect.width / 2)
+      const offsetY = Math.abs(centroidY - canvasRect.height / 2) / (canvasRect.height / 2)
+      const offset = Math.max(offsetX, offsetY)
 
-  if (isCoverLike) return []
+      if (offset > T.CENTROID_ERROR) {
+        issues.push({
+          type: "balance",
+          sub: "centroid_offset",
+          severity: "error",
+          detail: `Content centroid is far off-centre (${Math.round(offset * 100)}% offset). Content is concentrated in one area of the slide — consider distributing it more evenly.`,
+          data: { offsetPct: Math.round(offset * 100), centroidX: Math.round(centroidX), centroidY: Math.round(centroidY) },
+        })
+      } else if (offset > T.CENTROID_WARN) {
+        issues.push({
+          type: "balance",
+          sub: "centroid_offset",
+          severity: "warning",
+          detail: `Content centroid is slightly off-centre (${Math.round(offset * 100)}% offset). Consider balancing the visual weight across the slide.`,
+          data: { offsetPct: Math.round(offset * 100), centroidX: Math.round(centroidX), centroidY: Math.round(centroidY) },
+        })
+      }
+    }
+  }
 
-  // contentRect is in canvas-relative coords; canvasRect.bottom is the canvas height
-  const gap = canvasRect.bottom - contentRect.bottom
+  // ── Sub-check: bottom gap ────────────────────────────────────────────────
+  const bottomGap = canvasRect.bottom - contentRect.bottom
 
-  if (gap > T.BOTTOM_WS_ERROR) {
+  if (bottomGap > T.BOTTOM_GAP_ERROR) {
     issues.push({
-      type: "bottom_whitespace",
+      type: "balance",
+      sub: "bottom_gap",
       severity: "error",
-      detail: `${Math.round(gap)}px of empty space at the bottom of the slide (canvas bottom: ${Math.round(canvasRect.bottom)}px, last content: ${Math.round(contentRect.bottom)}px). The slide looks notably under-filled.`,
-      data: { gapPx: Math.round(gap) },
+      detail: `${Math.round(bottomGap)}px of empty space at the bottom of the slide (last content at ${Math.round(contentRect.bottom)}px, canvas bottom at ${Math.round(canvasRect.bottom)}px). The slide looks notably under-filled.`,
+      data: { gapPx: Math.round(bottomGap) },
     })
-  } else if (gap > T.BOTTOM_WS_WARN) {
+  } else if (bottomGap > T.BOTTOM_GAP_WARN) {
     issues.push({
-      type: "bottom_whitespace",
+      type: "balance",
+      sub: "bottom_gap",
       severity: "warning",
-      detail: `${Math.round(gap)}px empty gap at the bottom of the slide. Consider adding content, increasing padding, or using flex-grow to distribute space.`,
-      data: { gapPx: Math.round(gap) },
+      detail: `${Math.round(bottomGap)}px empty gap at the bottom of the slide. Consider adding content, increasing padding, or using flex-grow to distribute vertical space.`,
+      data: { gapPx: Math.round(bottomGap) },
     })
   }
 
   return issues
 }
 
-/** Check 3: Overflow — elements extending beyond the canvas boundaries */
-function checkOverflow(metrics: SlideMetrics): LayoutIssue[] {
-  const issues: LayoutIssue[] = []
-  const { canvasRect } = metrics
+// ── Dimension 3: Symmetry ─────────────────────────────────────────────────────
 
-  function walkElements(els: ElementInfo[]) {
-    for (const el of els) {
-      if (!el.visible) continue
-      const r = el.rect
-      // Allow a small tolerance (2px) for sub-pixel rendering
-      const tol = 2
-      if (
-        r.left < canvasRect.left - tol ||
-        r.top < canvasRect.top - tol ||
-        r.right > canvasRect.right + tol ||
-        r.bottom > canvasRect.bottom + tol
-      ) {
-        issues.push({
-          type: "overflow",
-          severity: "error",
-          detail: `Element \`${el.selector}\` overflows the canvas: rect(${Math.round(r.left)}, ${Math.round(r.top)}, ${Math.round(r.right)}, ${Math.round(r.bottom)}) vs canvas(${Math.round(canvasRect.left)}, ${Math.round(canvasRect.top)}, ${Math.round(canvasRect.right)}, ${Math.round(canvasRect.bottom)})`,
-        })
-      }
-      if (el.children.length > 0) walkElements(el.children)
-    }
-  }
+/**
+ * Check 3: Symmetry — side-by-side elements should be visually balanced.
+ *
+ * For each row of side-by-side columns, checks three sub-metrics and reports
+ * the most severe finding:
+ *   - height_mismatch:   rendered height ratio
+ *   - density_mismatch:  actual content height ratio (strips CSS stretch)
+ *   - leaf count ratio:  proxy for content density imbalance
+ *
+ * Applies at top-level and one level deep (nested rows inside columns).
+ */
+function checkSymmetry(metrics: SlideMetrics): LayoutIssue[] {
+  const issues: LayoutIssue[] = []
 
-  walkElements(metrics.elements)
-  return issues
-}
+  function checkRow(row: ElementInfo[], parentSelector?: string) {
+    if (row.length < 2) return
 
-/** Check 4: Asymmetry — side-by-side elements with large height difference */
-function checkAsymmetry(metrics: SlideMetrics): LayoutIssue[] {
-  const issues: LayoutIssue[] = []
+    const heights     = row.map((e) => e.rect.height)
+    const contHeights = row.map(contentHeight)
+    const areas       = row.map(leafArea)
 
-  // Check at the top level of .slide-canvas children
-  const rows = groupIntoRows(metrics.elements)
+    const minH  = Math.min(...heights),    maxH  = Math.max(...heights)
+    const minCH = Math.min(...contHeights), maxCH = Math.max(...contHeights)
+    const minA  = Math.min(...areas),       maxA  = Math.max(...areas)
 
-  for (const row of rows) {
-    if (row.length < 2) continue
+    const hRatio  = maxH  > 0 ? minH  / maxH  : 1
+    const chRatio = maxCH > 50 ? minCH / maxCH : 1  // skip tiny containers
+    const aRatio  = maxA  > 0 ? minA  / maxA  : 1
 
-    const heights = row.map((e) => e.rect.height)
-    const minH = Math.min(...heights)
-    const maxH = Math.max(...heights)
+    // Height mismatch (rendered boxes)
+    if (hRatio < T.SYM_ERROR) {
+      issues.push({
+        type: "symmetry",
+        sub: "height_mismatch",
+        severity: "error",
+        detail: `${parentSelector ? `Columns inside \`${parentSelector}\`` : "Side-by-side columns"} have a severe height mismatch: [${heights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(hRatio * 100)}%). The shorter column looks nearly empty.`,
+        data: { ratio: Math.round(hRatio * 100), minH: Math.round(minH), maxH: Math.round(maxH) },
+      })
+    } else if (hRatio < T.SYM_WARN) {
+      issues.push({
+        type: "symmetry",
+        sub: "height_mismatch",
+        severity: "warning",
+        detail: `${parentSelector ? `Columns inside \`${parentSelector}\`` : "Side-by-side columns"} have unequal heights: [${heights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(hRatio * 100)}%). Consider equalising content density.`,
+        data: { ratio: Math.round(hRatio * 100), minH: Math.round(minH), maxH: Math.round(maxH) },
+      })
+    }
 
-    if (maxH === 0) continue
-    const ratio = minH / maxH
+    // Density mismatch (actual content height, ignores CSS stretch)
+    if (maxCH > 50 && chRatio < T.SYM_ERROR) {
+      issues.push({
+        type: "symmetry",
+        sub: "density_mismatch",
+        severity: "error",
+        detail: `${parentSelector ? `Columns inside \`${parentSelector}\`` : "Side-by-side columns"} have very different actual content heights: [${contHeights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(chRatio * 100)}%). CSS stretch hides this — the sparser column will have large internal whitespace.`,
+        data: { ratio: Math.round(chRatio * 100), contentHeights: contHeights.map(Math.round).join(",") },
+      })
+    } else if (maxCH > 50 && chRatio < T.SYM_WARN) {
+      issues.push({
+        type: "symmetry",
+        sub: "density_mismatch",
+        severity: "warning",
+        detail: `${parentSelector ? `Columns inside \`${parentSelector}\`` : "Side-by-side columns"} have different actual content heights: [${contHeights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(chRatio * 100)}%). Consider equalising content density.`,
+        data: { ratio: Math.round(chRatio * 100), contentHeights: contHeights.map(Math.round).join(",") },
+      })
+    }
 
-    if (ratio < T.ASYM_ERROR) {
+    // Area imbalance (sum of leaf bounding-box areas — robust to chart containers)
+    if (maxA > 0 && aRatio < T.SYM_ERROR) {
       issues.push({
-        type: "asymmetry",
+        type: "symmetry",
+        sub: "density_mismatch",
         severity: "error",
-        detail: `Side-by-side columns have a severe height mismatch: [${heights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(ratio * 100)}%). The shorter column appears nearly empty next to the taller one.`,
-        data: { ratio: Math.round(ratio * 100), minH: Math.round(minH), maxH: Math.round(maxH) },
+        detail: `${parentSelector ? `Columns inside \`${parentSelector}\`` : "Side-by-side columns"} have very unequal content area: [${areas.map((a) => Math.round(a / 1000) + "k").join(" vs ")}]px² (ratio ${Math.round(aRatio * 100)}%). The sparse column may feel nearly empty.`,
+        data: { ratio: Math.round(aRatio * 100), areas: areas.map((a) => Math.round(a / 1000)).join(",") },
       })
-    } else if (ratio < T.ASYM_WARN) {
+    } else if (maxA > 0 && aRatio < T.SYM_WARN) {
       issues.push({
-        type: "asymmetry",
+        type: "symmetry",
+        sub: "density_mismatch",
         severity: "warning",
-        detail: `Side-by-side columns have unequal heights: [${heights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(ratio * 100)}%). Consider equalising content density or using align-items: stretch with matching visual weight.`,
-        data: { ratio: Math.round(ratio * 100), minH: Math.round(minH), maxH: Math.round(maxH) },
+        detail: `${parentSelector ? `Columns inside \`${parentSelector}\`` : "Side-by-side columns"} have unequal content area: [${areas.map((a) => Math.round(a / 1000) + "k").join(" vs ")}]px² (ratio ${Math.round(aRatio * 100)}%). Consider balancing content between columns.`,
+        data: { ratio: Math.round(aRatio * 100), areas: areas.map((a) => Math.round(a / 1000)).join(",") },
       })
     }
+  }
 
-    // Also recursively check inside each column for nested rows
+  // Top-level rows (elements that are side-by-side at the top level)
+  const topRows = groupIntoRows(metrics.elements)
+  for (const row of topRows) {
+    checkRow(row)
+    // One level deep: check nested rows inside each column
     for (const col of row) {
       if (col.children.length >= 2) {
         const nestedRows = groupIntoRows(col.children)
         for (const nestedRow of nestedRows) {
-          if (nestedRow.length < 2) continue
-          const nh = nestedRow.map((e) => e.rect.height)
-          const nMin = Math.min(...nh)
-          const nMax = Math.max(...nh)
-          if (nMax === 0) continue
-          const nRatio = nMin / nMax
-          if (nRatio < T.CARD_VAR_WARN) {
-            issues.push({
-              type: "card_height_variance",
-              severity: "warning",
-              detail: `Nested row inside \`${col.selector}\` has card height variance: [${nh.map((h) => Math.round(h) + "px").join(", ")}] (min/max ratio ${Math.round(nRatio * 100)}%). Cards in the same row should be visually balanced.`,
-              data: { ratio: Math.round(nRatio * 100) },
-            })
-          }
+          checkRow(nestedRow, col.selector)
         }
       }
     }
   }
 
-  return issues
-}
-
-/** Check 5: Sparse slide — very few top-level elements */
-function checkSparse(metrics: SlideMetrics): LayoutIssue[] {
-  const issues: LayoutIssue[] = []
-
-  // Exempt structural slides — they are intentionally minimal
-  if (metrics.slideType && EXEMPT_TYPES.has(metrics.slideType)) return []
-
-  const visibleCount = metrics.elements.filter((e) => e.visible).length
-
-  if (visibleCount < T.SPARSE_THRESHOLD) {
-    issues.push({
-      type: "sparse",
-      severity: "warning",
-      detail: `Slide has only ${visibleCount} visible top-level element(s). This may result in a lot of empty space.`,
-      data: { visibleCount },
-    })
+  // Also check children of every top-level element that is NOT itself part of a row.
+  // This catches containers like .two-col whose children are side-by-side columns,
+  // even when the container itself is stacked vertically (no top-level sibling to pair with).
+  const inTopRow = new Set(topRows.flat().map((e) => e.selector))
+  for (const el of metrics.elements) {
+    if (!el.visible || inTopRow.has(el.selector)) continue
+    if (el.children.length >= 2) {
+      const childRows = groupIntoRows(el.children)
+      for (const row of childRows) {
+        checkRow(row, el.selector)
+      }
+    }
   }
 
   return issues
 }
 
-/**
- * Count all leaf (no-child) descendants of an ElementInfo tree.
- */
-function countLeaves(el: ElementInfo): number {
-  if (el.children.length === 0) return 1
-  return el.children.reduce((sum, ch) => sum + countLeaves(ch), 0)
-}
+// ── Dimension 4: Rhythm ───────────────────────────────────────────────────────
 
 /**
- * Compute the actual content height of an element: from its topmost child's top
- * to its bottommost child's bottom (ignoring CSS stretch padding).
+ * Coefficient of variation: stddev / mean. Returns 0 if mean is 0.
  */
-function contentHeight(el: ElementInfo): number {
-  if (el.children.length === 0) return el.rect.height
-  let top = Infinity, bottom = -Infinity
-  function walk(list: ElementInfo[]) {
-    for (const ch of list) {
-      if (!ch.visible) continue
-      top = Math.min(top, ch.rect.top)
-      bottom = Math.max(bottom, ch.rect.bottom)
-      if (ch.children.length > 0) walk(ch.children)
-    }
-  }
-  walk(el.children)
-  return top === Infinity ? el.rect.height : bottom - top
+function cv(values: number[]): number {
+  if (values.length < 2) return 0
+  const mean = values.reduce((s, v) => s + v, 0) / values.length
+  if (mean === 0) return 0
+  const variance = values.reduce((s, v) => s + (v - mean) ** 2, 0) / values.length
+  return Math.sqrt(variance) / mean
 }
 
 /**
- * Check 6: Content density imbalance in side-by-side columns.
+ * Check 4: Rhythm — spacing regularity between stacked siblings.
  *
- * CSS `align-items: stretch` makes all columns the same height visually, so
- * a pure height asymmetry check won't catch imbalanced content density.
- * This check counts leaf elements and actual content height in each column.
+ * Sub-checks:
+ *   - gap_variance: vertical gaps between stacked siblings are uneven
  */
-function checkDensityImbalance(metrics: SlideMetrics): LayoutIssue[] {
+function checkRhythm(metrics: SlideMetrics): LayoutIssue[] {
   const issues: LayoutIssue[] = []
 
-  // Find rows at the top level
-  const rows = groupIntoRows(metrics.elements)
+  // Skip rhythm checks for structural/sparse slides (slide-qa="false")
+  if (!metrics.slideQa) return []
 
-  for (const row of rows) {
-    if (row.length < 2) continue
+  function checkContainer(els: ElementInfo[], containerSelector?: string) {
+    if (els.length < 2) return
 
-    const leafCounts = row.map(countLeaves)
-    const contentHeights = row.map(contentHeight)
+    // Identify vertically-stacked children (high horizontal overlap, low vertical overlap)
+    const visibleEls = els.filter((e) => e.visible).sort((a, b) => a.rect.top - b.rect.top)
+    if (visibleEls.length < T.GAP_MIN_CHILDREN) return
 
-    // Check leaf count ratio
-    const minLeaves = Math.min(...leafCounts)
-    const maxLeaves = Math.max(...leafCounts)
-    if (maxLeaves > 0) {
-      const ratio = minLeaves / maxLeaves
-      if (ratio < T.DENSITY_ERROR) {
-        issues.push({
-          type: "density_imbalance",
-          severity: "error",
-          detail: `Side-by-side columns have very unequal content density: [${leafCounts.join(" vs ")}] elements. The sparse column may feel nearly empty. Add more content to the lighter column or reduce content in the heavier one.`,
-          data: { ratio: Math.round(ratio * 100), leafCounts: leafCounts.join(",") },
-        })
-      } else if (ratio < T.DENSITY_WARN) {
-        issues.push({
-          type: "density_imbalance",
-          severity: "warning",
-          detail: `Side-by-side columns have unequal content density: [${leafCounts.join(" vs ")}] elements. Consider balancing content between columns.`,
-          data: { ratio: Math.round(ratio * 100), leafCounts: leafCounts.join(",") },
-        })
-      }
+    // Check if elements are mostly stacked (not side-by-side)
+    // Heuristic: average horizontal overlap > 0.5 among adjacent pairs
+    let hOverlapSum = 0
+    for (let i = 0; i < visibleEls.length - 1; i++) {
+      hOverlapSum += horizontalOverlap(visibleEls[i].rect, visibleEls[i + 1].rect)
+    }
+    const avgHOverlap = hOverlapSum / (visibleEls.length - 1)
+    if (avgHOverlap < 0.5) return // Side-by-side layout, not stacked
+
+    // Compute gaps between adjacent stacked elements
+    const gaps: number[] = []
+    for (let i = 0; i < visibleEls.length - 1; i++) {
+      const gap = visibleEls[i + 1].rect.top - visibleEls[i].rect.bottom
+      if (gap >= 0) gaps.push(gap) // negative gap = overlapping, skip
     }
+    if (gaps.length < 2) return
 
-    // Check actual content height ratio (ignoring CSS stretch)
-    const minCH = Math.min(...contentHeights)
-    const maxCH = Math.max(...contentHeights)
-    if (maxCH > 50) { // only check if columns have meaningful content
-      const chRatio = minCH / maxCH
-      if (chRatio < T.ASYM_ERROR) {
-        issues.push({
-          type: "density_imbalance",
-          severity: "error",
-          detail: `Side-by-side columns have very different actual content heights: [${contentHeights.map((h) => Math.round(h) + "px").join(" vs ")}] (CSS stretch hides this — ratio ${Math.round(chRatio * 100)}%). The column with less content will have large internal whitespace.`,
-          data: { ratio: Math.round(chRatio * 100), contentHeights: contentHeights.map(Math.round).join(",") },
-        })
-      } else if (chRatio < T.ASYM_WARN) {
-        issues.push({
-          type: "density_imbalance",
-          severity: "warning",
-          detail: `Side-by-side columns have different actual content heights: [${contentHeights.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(chRatio * 100)}%). Consider equalising content density.`,
-          data: { ratio: Math.round(chRatio * 100), contentHeights: contentHeights.map(Math.round).join(",") },
-        })
-      }
+    const meanGap = gaps.reduce((s, g) => s + g, 0) / gaps.length
+    if (meanGap < T.GAP_MIN_MEAN) return
+
+    const gapCV = cv(gaps)
+    const label = containerSelector ? `inside \`${containerSelector}\`` : "in slide"
+
+    if (gapCV > T.GAP_CV_ERROR) {
+      issues.push({
+        type: "rhythm",
+        sub: "gap_variance",
+        severity: "error",
+        detail: `Gaps between stacked elements ${label} are highly irregular (CV=${Math.round(gapCV * 100)}%, gaps=[${gaps.map(Math.round).join(", ")}]px). Use consistent gap or padding values.`,
+        data: { cv: Math.round(gapCV * 100), gaps: gaps.map(Math.round).join(",") },
+      })
+    } else if (gapCV > T.GAP_CV_WARN) {
+      issues.push({
+        type: "rhythm",
+        sub: "gap_variance",
+        severity: "warning",
+        detail: `Gaps between stacked elements ${label} are uneven (CV=${Math.round(gapCV * 100)}%, gaps=[${gaps.map(Math.round).join(", ")}]px). Consider using a consistent gap or flex spacing.`,
+        data: { cv: Math.round(gapCV * 100), gaps: gaps.map(Math.round).join(",") },
+      })
     }
   }
 
-  // Also check one level deep (containers that hold two-column layouts)
+  // Check at top-level and one level deep
+  checkContainer(metrics.elements)
   for (const el of metrics.elements) {
-    if (el.children.length >= 2) {
-      const nestedRows = groupIntoRows(el.children)
-      for (const nestedRow of nestedRows) {
-        if (nestedRow.length < 2) continue
-        const nLeaves = nestedRow.map(countLeaves)
-        const nCH = nestedRow.map(contentHeight)
-        const minNL = Math.min(...nLeaves)
-        const maxNL = Math.max(...nLeaves)
-        const minNCH = Math.min(...nCH)
-        const maxNCH = Math.max(...nCH)
-
-        if (maxNL > 0 && minNL / maxNL < T.DENSITY_WARN) {
-          const ratio = minNL / maxNL
-          issues.push({
-            type: "density_imbalance",
-            severity: ratio < T.DENSITY_ERROR ? "error" : "warning",
-            detail: `Nested side-by-side columns inside \`${el.selector}\` have unequal content: [${nLeaves.join(" vs ")}] elements (ratio ${Math.round(ratio * 100)}%).`,
-            data: { ratio: Math.round(ratio * 100) },
-          })
-        }
-        if (maxNCH > 50 && minNCH / maxNCH < T.ASYM_WARN) {
-          const chRatio = minNCH / maxNCH
-          issues.push({
-            type: "density_imbalance",
-            severity: chRatio < T.ASYM_ERROR ? "error" : "warning",
-            detail: `Nested columns inside \`${el.selector}\` have different actual content heights: [${nCH.map((h) => Math.round(h) + "px").join(" vs ")}] (ratio ${Math.round(chRatio * 100)}%).`,
-            data: { ratio: Math.round(chRatio * 100) },
-          })
-        }
-      }
+    if (el.children.length > 0) {
+      checkContainer(el.children, el.selector)
     }
   }
 
   return issues
 }
 
-// ── Main export ──────────────────────────────────────────────────────────────
+// ── Main export ───────────────────────────────────────────────────────────────
 
 /**
- * Run all checks on a set of slide metrics and produce a QA report.
+ * Run all four dimension checks on a set of slide metrics and produce a QA report.
  */
 export function runChecks(filePath: string, allMetrics: SlideMetrics[]): QAReport {
   const slides: SlideReport[] = []
 
   for (const metrics of allMetrics) {
     const issues: LayoutIssue[] = [
-      ...checkFill(metrics),
-      ...checkBottomWhitespace(metrics),
       ...checkOverflow(metrics),
-      ...checkAsymmetry(metrics),
-      ...checkSparse(metrics),
-      ...checkDensityImbalance(metrics),
+      ...checkBalance(metrics),
+      ...checkSymmetry(metrics),
+      ...checkRhythm(metrics),
     ]
 
     slides.push({ index: metrics.index, title: metrics.title, issues })
@@ -550,7 +557,7 @@ export function runChecks(filePath: string, allMetrics: SlideMetrics[]): QARepor
   return { file: filePath, slides, totalIssues, errorCount, warningCount, summary }
 }
 
-// ── Report formatter ─────────────────────────────────────────────────────────
+// ── Report formatter ──────────────────────────────────────────────────────────
 
 /**
  * Format a QAReport into a markdown string suitable for the LLM to read.
@@ -573,7 +580,8 @@ export function formatReport(report: QAReport): string {
     lines.push(`### Slide ${slide.index + 1}: ${slide.title}`)
     for (const issue of slide.issues) {
       const icon = issue.severity === "error" ? "🔴" : "🟡"
-      lines.push(`- ${icon} **${issue.type}**: ${issue.detail}`)
+      const label = issue.sub ? `${issue.type}/${issue.sub}` : issue.type
+      lines.push(`- ${icon} **${label}**: ${issue.detail}`)
     }
     lines.push("")
   }
@@ -581,13 +589,14 @@ export function formatReport(report: QAReport): string {
   lines.push(
     `### Action Required`,
     ``,
-    `Please fix the above layout issues in the HTML file. For each issue:`,
-    `- **underfill / bottom_whitespace**: expand content to fill the slide, use \`flex: 1\` on containers, add more content blocks, or reduce top padding.`,
-    `- **asymmetry**: ensure side-by-side columns have matching visual weight — equalise item count, use \`align-items: stretch\`, or adjust heights explicitly.`,
-    `- **density_imbalance**: add more items to the sparse column, reduce items in the dense column, or switch to a single-column layout. CSS stretch hides height differences but not visual emptiness.`,
+    `Please fix the above layout issues in the HTML file. For each issue type:`,
     `- **overflow**: reduce font size, padding, or content amount for the affected element.`,
-    `- **card_height_variance**: ensure cards in the same row have similar content density, or use \`align-items: stretch\` on the grid.`,
-    `- **sparse**: add more content components, increase font sizes, or use a layout with fewer columns.`,
+    `- **balance/centroid_offset**: redistribute content so the visual weight is centred — avoid concentrating everything in one corner or side.`,
+    `- **balance/bottom_gap**: expand content to fill the slide, use \`flex: 1\` on containers, add more content blocks, or reduce top padding.`,
+    `- **balance/sparse**: add more content components, increase font sizes, or use a layout with fewer columns.`,
+    `- **symmetry/height_mismatch**: equalise side-by-side column heights — use \`align-items: stretch\` or match content density.`,
+    `- **symmetry/density_mismatch**: balance content between columns — add items to the sparse column or reduce items in the dense one.`,
+    `- **rhythm/gap_variance**: use consistent \`gap\` or \`margin\` values between stacked elements instead of mixing sizes.`,
   )
 
   return lines.join("\n")