@cyber-dash-tech/revela 0.17.0 → 0.17.1

package/lib/narrative-state/render-plan.ts

@@ -1,4 +1,4 @@
-import { deckPlanHash, upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec } from "../decks-state"
+import { deckPlanHash, upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec, type VisualBrief } from "../decks-state"
 import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
 import { getClaimSlideRefs } from "./queries"
 import { computeNarrativeHash } from "./hash"
@@ -35,6 +35,16 @@ export interface DeckPlanQualityCheck {
   message: string
 }
 
+type VisualIntentKind = "hero" | "toc" | "metric-stat" | "evidence-table" | "comparison-grid" | "risk-matrix" | "steps" | "text-only"
+
+interface VisualIntent {
+  kind: VisualIntentKind
+  component: string
+  rationale: string
+  dataSignals: string[]
+  evidenceBindingIds: string[]
+}
+
 export function compileDeckPlanFromNarrative(state: DecksState, options: CompileDeckPlanOptions = {}): { state: DecksState; result: CompileDeckPlanResult } {
   const narrative = normalizeNarrativeState(state)
   const narrativeHash = computeNarrativeHash(narrative)
@@ -168,6 +178,7 @@ function buildDeckPlan(narrative: NarrativeStateV1): { slides: SlideSpec[]; chap
 }
 
 function coverSlide(index: number, narrative: NarrativeStateV1): SlideSpec {
+  const visualIntent = visualIntentForStructuralSlide("hero", "Use a hero frame to anchor the decision context and belief shift before evidence detail.")
   return {
     index,
     title: "Decision Context",
@@ -183,13 +194,16 @@ function coverSlide(index: number, narrative: NarrativeStateV1): SlideSpec {
         narrative.audience.beliefAfter ? `After: ${narrative.audience.beliefAfter}` : "After belief needs confirmation.",
       ],
       bullets: narrative.decision.action ? [`Decision: ${narrative.decision.action}`] : [],
+      data: { visualIntent },
     },
+    visuals: visualBriefs(index, visualIntent),
     evidence: [],
     status: "planned",
   }
 }
 
 function tocSlide(index: number, chapters: DeckPlanChapter[]): SlideSpec {
+  const visualIntent = visualIntentForStructuralSlide("toc", "Render the chapter sequence as a visual table of contents instead of a bullet-only agenda.")
   return {
     index,
     title: "Storyline",
@@ -201,14 +215,16 @@ function tocSlide(index: number, chapters: DeckPlanChapter[]): SlideSpec {
     content: {
       headline: "How the decision story is organized",
       bullets: chapters.map((chapter) => chapter.title),
-      data: { chapters: chapters.map((chapter) => ({ title: chapter.title, role: chapter.role })) },
+      data: { chapters: chapters.map((chapter) => ({ title: chapter.title, role: chapter.role })), visualIntent },
     },
+    visuals: visualBriefs(index, visualIntent),
     evidence: [],
     status: "planned",
   }
 }
 
 function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): SlideSpec {
+  const visualIntent = visualIntentForClaim(claim, bindings)
   return {
     index,
     title: titleFromClaim(claim),
@@ -216,21 +232,24 @@ function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvi
     narrativeRole: claim.kind === "risk" || claim.kind === "assumption" ? "risk" : claim.kind === "ask" ? "ask" : claim.kind === "recommendation" ? "recommendation" : "evidence",
     layout: "two-col",
     qa: true,
-    components: claimComponents(claim, bindings),
+    components: claimComponents(claim, bindings, visualIntent),
     claimIds: [claim.id],
     claimRefs: [{ claimId: claim.id, role: "primary", note: claimBoundaryNote(claim) }],
     evidenceBindingIds: bindings.map((binding) => binding.id),
     content: {
       headline: claim.text,
       bullets: claimBullets(claim, bindings),
+      data: { visualIntent },
     },
     evidence: bindings.map(evidenceRefFromBinding),
+    visuals: visualBriefs(index, visualIntent),
     status: "planned",
   }
 }
 
 function supportingLogicSlide(index: number, claims: NarrativeClaim[], evidenceByClaim: Map<string, NarrativeEvidenceBinding[]>): SlideSpec {
   const supportingBindings = claims.flatMap((claim) => evidenceByClaim.get(claim.id) ?? [])
+  const visualIntent = visualIntentForSupportingLogic(claims, supportingBindings)
   return {
     index,
     title: "Supporting Logic",
@@ -238,15 +257,17 @@ function supportingLogicSlide(index: number, claims: NarrativeClaim[], evidenceB
     narrativeRole: "evidence",
     layout: "card-grid",
     qa: true,
-    components: ["box", "text-panel"],
+    components: componentsForVisualIntent(["box", "text-panel"], visualIntent),
     claimIds: claims.map((claim) => claim.id),
     claimRefs: claims.map((claim) => ({ claimId: claim.id, role: "supporting" as const, note: claimBoundaryNote(claim) })),
     evidenceBindingIds: supportingBindings.map((binding) => binding.id),
     content: {
       headline: "Supporting claims and boundaries",
       bullets: claims.slice(0, 5).flatMap((claim) => [claim.text, ...claimBoundaryBullets(claim), evidenceGapBullet(claim, evidenceByClaim.get(claim.id) ?? [])]).filter((item): item is string => Boolean(item)).slice(0, 8),
+      data: { visualIntent },
     },
     evidence: supportingBindings.map(evidenceRefFromBinding),
+    visuals: visualBriefs(index, visualIntent),
     status: "planned",
   }
 }
@@ -258,6 +279,7 @@ function riskObjectionSlide(index: number, narrative: NarrativeStateV1, evidence
   ]
   const challengedClaimIds = [...new Set(challengedClaimRefs.map((ref) => ref.claimId))]
   const challengedBindings = challengedClaimIds.flatMap((claimId) => evidenceByClaim.get(claimId) ?? [])
+  const visualIntent = visualIntentForRiskObjection(narrative, challengedBindings)
   return {
     index,
     title: "Risks And Objections",
@@ -265,7 +287,7 @@ function riskObjectionSlide(index: number, narrative: NarrativeStateV1, evidence
     narrativeRole: "risk",
     layout: "two-col",
     qa: true,
-    components: ["box", "text-panel"],
+    components: componentsForVisualIntent(["box", "text-panel"], visualIntent),
     claimIds: challengedClaimIds,
     claimRefs: dedupeClaimRefs(challengedClaimRefs),
     evidenceBindingIds: challengedBindings.map((binding) => binding.id),
@@ -275,14 +297,17 @@ function riskObjectionSlide(index: number, narrative: NarrativeStateV1, evidence
         ...narrative.risks.slice(0, 3).map((risk) => risk.mitigation ? `${risk.text} Mitigation: ${risk.mitigation}` : risk.text),
         ...narrative.objections.slice(0, 3).map((objection) => objection.response ? `${objection.text} Response: ${objection.response}` : objection.text),
       ],
+      data: { visualIntent },
     },
     evidence: challengedBindings.map(evidenceRefFromBinding),
+    visuals: visualBriefs(index, visualIntent),
     status: "planned",
   }
 }
 
 function decisionAskSlide(index: number, narrative: NarrativeStateV1): SlideSpec {
   const askClaims = orderedClaims(narrative, (claim) => claim.kind === "ask" || claim.kind === "recommendation")
+  const visualIntent = visualIntentForStructuralSlide("steps", "Show the requested decision, owner, deadline, and consequence as an action sequence rather than a dense closing paragraph.")
   return {
     index,
     title: "Decision Ask",
@@ -300,8 +325,10 @@ function decisionAskSlide(index: number, narrative: NarrativeStateV1): SlideSpec
         narrative.decision.deadline ? `Deadline: ${narrative.decision.deadline}` : undefined,
         narrative.decision.consequenceOfNoDecision ? `If no decision: ${narrative.decision.consequenceOfNoDecision}` : undefined,
       ].filter((item): item is string => Boolean(item)),
+      data: { visualIntent },
     },
     evidence: [],
+    visuals: visualBriefs(index, visualIntent),
     status: "planned",
   }
 }
@@ -377,10 +404,99 @@ function hasClaimKind(claims: NarrativeClaim[], kinds: NarrativeClaim["kind"][])
   return claims.some((claim) => kinds.includes(claim.kind))
 }
 
-function claimComponents(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): string[] {
-  if (bindings.some((binding) => binding.quote?.trim())) return ["box", "text-panel", "quote"]
-  if (claim.kind === "recommendation" || claim.kind === "ask") return ["box", "text-panel", "steps"]
-  return ["box", "text-panel"]
+function claimComponents(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[], visualIntent: VisualIntent): string[] {
+  const base = bindings.some((binding) => binding.quote?.trim()) ? ["box", "text-panel", "quote"] : ["box", "text-panel"]
+  if ((claim.kind === "recommendation" || claim.kind === "ask") && visualIntent.kind === "text-only") return ["box", "text-panel", "steps"]
+  return componentsForVisualIntent(base, visualIntent)
+}
+
+function visualIntentForClaim(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): VisualIntent {
+  const evidenceBindingIds = bindings.map((binding) => binding.id)
+  const dataSignals = dataSignalsFromBindings(bindings)
+  if (bindings.length >= 2) {
+    return {
+      kind: "evidence-table",
+      component: "data-table",
+      rationale: "Compare multiple evidence bindings with source, support scope, and caveat columns so the slide is not a bullet stack.",
+      dataSignals,
+      evidenceBindingIds,
+    }
+  }
+  if (dataSignals.length > 0) {
+    return {
+      kind: "metric-stat",
+      component: "stat-card",
+      rationale: "Promote the strongest quantitative evidence signal into a metric card, with the source quote retained for traceability.",
+      dataSignals,
+      evidenceBindingIds,
+    }
+  }
+  if (claim.kind === "recommendation" || claim.kind === "ask") {
+    return {
+      kind: "steps",
+      component: "steps",
+      rationale: "Show the recommendation as phased actions or decision gates rather than a paragraph.",
+      dataSignals,
+      evidenceBindingIds,
+    }
+  }
+  return {
+    kind: "text-only",
+    component: "box",
+    rationale: "No quantified or multi-source visual signal is available; use semantic evidence boxes and keep boundaries explicit.",
+    dataSignals,
+    evidenceBindingIds,
+  }
+}
+
+function visualIntentForSupportingLogic(claims: NarrativeClaim[], bindings: NarrativeEvidenceBinding[]): VisualIntent {
+  const dataSignals = dataSignalsFromBindings(bindings)
+  return {
+    kind: claims.length >= 3 || bindings.length >= 2 ? "comparison-grid" : "evidence-table",
+    component: "data-table",
+    rationale: "Organize supporting claims as a comparison grid with evidence status and boundaries, avoiding a long undifferentiated bullet list.",
+    dataSignals,
+    evidenceBindingIds: bindings.map((binding) => binding.id),
+  }
+}
+
+function visualIntentForRiskObjection(narrative: NarrativeStateV1, bindings: NarrativeEvidenceBinding[]): VisualIntent {
+  return {
+    kind: "risk-matrix",
+    component: "data-table",
+    rationale: "Pair each risk or objection with mitigation or response in a compact matrix so caveats stay visible without becoming prose-heavy.",
+    dataSignals: [...narrative.risks.map((risk) => risk.severity), ...narrative.objections.map((objection) => objection.priority)].filter(Boolean),
+    evidenceBindingIds: bindings.map((binding) => binding.id),
+  }
+}
+
+function visualIntentForStructuralSlide(kind: Extract<VisualIntentKind, "hero" | "toc" | "steps">, rationale: string): VisualIntent {
+  return { kind, component: kind === "toc" ? "toc" : kind === "steps" ? "steps" : "hero", rationale, dataSignals: [], evidenceBindingIds: [] }
+}
+
+function componentsForVisualIntent(base: string[], visualIntent: VisualIntent): string[] {
+  const next = [...base]
+  if (visualIntent.component && !next.includes(visualIntent.component)) next.push(visualIntent.component)
+  return next
+}
+
+function visualBriefs(slideIndex: number, visualIntent: VisualIntent): VisualBrief[] {
+  return [{
+    id: `visual:${slideIndex}:${visualIntent.kind}`,
+    purpose: visualIntent.kind,
+    brief: `${visualIntent.rationale} Use ${visualIntent.component} and preserve cited evidence boundaries${visualIntent.dataSignals.length > 0 ? `; visible signals: ${visualIntent.dataSignals.slice(0, 4).join(", ")}.` : "."}`,
+  }]
+}
+
+function dataSignalsFromBindings(bindings: NarrativeEvidenceBinding[]): string[] {
+  const signals = bindings.flatMap((binding) => numericSignals([binding.quote, binding.supportScope, binding.source, binding.location].filter(Boolean).join(" ")))
+  return [...new Set(signals)].slice(0, 6)
+}
+
+function numericSignals(text: string): string[] {
+  return [...text.matchAll(/(?:[$€£¥]\s*)?\d+(?:\.\d+)?\s*(?:%|bps|x|k|m|bn|billion|million|year|years|yr|yrs)?/gi)]
+    .map((match) => match[0].trim())
+    .filter(Boolean)
 }
 
 function claimBullets(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): string[] {

package/lib/qa/checks.ts

@@ -23,9 +23,10 @@ import { CANVAS_W, CANVAS_H } from "./measure"
 export type IssueSeverity = "error" | "warning" | "info"
 
 export interface LayoutIssue {
-  type: "canvas" | "scrollbar" | "overflow" | "text_overflow" | "density" | "balance" | "symmetry" | "rhythm" | "compliance" | "asset"
+  type: "canvas" | "scrollbar" | "navigation" | "overflow" | "text_overflow" | "overlap" | "density" | "balance" | "symmetry" | "rhythm" | "compliance" | "asset"
   /** Sub-category within the dimension */
-  sub?: "size_mismatch" | "page_scroll" | "text_clipped" | "thin_content"
+  sub?: "size_mismatch" | "page_scroll" | "fixed_overlay_slides" | "hidden_paging" | "unreachable_slides" | "text_clipped" | "thin_content"
+      | "element_collision" | "major_overlap" | "possible_overlay"
       | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
@@ -81,6 +82,12 @@ const T = {
   CANVAS_TOLERANCE: 1,
   DENSITY_MIN_TEXT_POINTS: 70,
   DENSITY_MIN_UNITS: 2,
+  OVERLAP_MIN_AREA: 1600,
+  OVERLAP_MIN_ELEMENT_AREA: 5000,
+  OVERLAP_WARN_RATIO: 0.08,
+  OVERLAP_ERROR_RATIO: 0.18,
+  OVERLAP_TEXT_WARN_RATIO: 0.05,
+  OVERLAP_TEXT_ERROR_RATIO: 0.12,
 }
 
 // ── Geometry helpers ──────────────────────────────────────────────────────────
@@ -205,15 +212,78 @@ function checkCanvas(metrics: SlideMetrics): LayoutIssue[] {
 }
 
 function checkScrollbars(metrics: SlideMetrics): LayoutIssue[] {
-  if (!metrics.hasScrollbars) return []
+  const scrollbars = metrics.scrollbars
+  const totalSlides = metrics.navigation?.totalSlides ?? 1
+  const hasAllowedMultiSlideVerticalScroll = totalSlides > 1
+
+  if (scrollbars) {
+    const hasBlockingScrollbars =
+      scrollbars.documentHorizontal ||
+      scrollbars.bodyHorizontal ||
+      scrollbars.slideHorizontal ||
+      scrollbars.slideVertical ||
+      (!hasAllowedMultiSlideVerticalScroll && (scrollbars.documentVertical || scrollbars.bodyVertical))
+
+    if (!hasBlockingScrollbars) return []
+  } else if (!metrics.hasScrollbars) {
+    return []
+  }
+
   return [{
     type: "scrollbar",
     sub: "page_scroll",
     severity: "error",
-    detail: "Rendered slide/page has scrollbars at 1920x1080. Deck slides must fit the fixed canvas without document, body, or slide scrolling.",
+    detail: "Rendered slide/page has blocking scrollbars at 1920x1080. Normal vertical document scroll is allowed for multi-slide navigation, but horizontal document/body scroll and slide-internal scroll must be removed.",
   }]
 }
 
+function checkNavigationModel(allMetrics: SlideMetrics[]): LayoutIssue[] {
+  if (allMetrics.length <= 1) return []
+
+  const nav = allMetrics.map((metrics) => metrics.navigation).filter((item): item is NonNullable<SlideMetrics["navigation"]> => Boolean(item))
+  if (nav.length <= 1) return []
+
+  const positioned = nav.filter((item) => item.position === "fixed" || item.position === "absolute")
+  const hiddenByAria = nav.filter((item) => item.ariaHidden === "true" || item.visibility === "hidden" || item.display === "none")
+  const uniqueTops = new Set(nav.map((item) => Math.round(item.initialTop)))
+  const stacked = uniqueTops.size <= 1
+  const documentCanScroll = nav[0].documentScrollHeight > nav[0].viewportHeight + 2
+  const overflowHidden = nav[0].bodyOverflowY === "hidden" || nav[0].documentOverflowY === "hidden"
+
+  const issues: LayoutIssue[] = []
+  if (positioned.length === nav.length && stacked) {
+    issues.push({
+      type: "navigation",
+      sub: "fixed_overlay_slides",
+      severity: "error",
+      detail: "Slides are stacked with fixed/absolute positioning. Revela decks must keep each .slide in normal document flow so scrollIntoView and keyboard navigation can reach every slide.",
+      data: { slideCount: nav.length, positionedSlides: positioned.length },
+    })
+  }
+
+  if (positioned.length === nav.length && hiddenByAria.length > 0) {
+    issues.push({
+      type: "navigation",
+      sub: "hidden_paging",
+      severity: "error",
+      detail: "Slides use aria-hidden/visibility toggles with fixed overlay pagination. Do not make slide visibility depend on aria-hidden; keep slides visible in normal flow and navigate with scrollIntoView.",
+      data: { hiddenSlides: hiddenByAria.length, slideCount: nav.length },
+    })
+  }
+
+  if (!documentCanScroll && overflowHidden && allMetrics.length > 1) {
+    issues.push({
+      type: "navigation",
+      sub: "unreachable_slides",
+      severity: "error",
+      detail: "Multi-slide deck disables document vertical scrolling. Normal slide flow needs enough document height for all slides; fix slide overflow locally instead of hiding body/html overflow.",
+      data: { slideCount: nav.length, documentScrollHeight: nav[0].documentScrollHeight, viewportHeight: nav[0].viewportHeight },
+    })
+  }
+
+  return issues
+}
+
 /**
  * Check 1: Overflow — elements extending beyond canvas boundaries.
  * Hard correctness check; applies to all slide types.
@@ -270,6 +340,132 @@ function checkTextOverflow(metrics: SlideMetrics): LayoutIssue[] {
   return issues
 }
 
+const SEMANTIC_COMPONENT_CLASSES = [
+  "box",
+  "text-panel",
+  "media",
+  "echart-panel",
+  "data-table",
+  "stat-card",
+  "quote",
+  "hero",
+  "toc",
+  "steps",
+  "roadmap-horizontal",
+  "roadmap-vertical",
+]
+
+const DECORATIVE_CLASSES = [
+  "page-number",
+  "brand-watermark",
+  "watermark",
+  "background",
+  "decorative",
+  "motif",
+]
+
+function checkElementOverlap(metrics: SlideMetrics): LayoutIssue[] {
+  const candidates = overlapCandidates(metrics.elements)
+  const issues: LayoutIssue[] = []
+
+  for (let i = 0; i < candidates.length; i++) {
+    for (let j = i + 1; j < candidates.length; j++) {
+      const a = candidates[i]
+      const b = candidates[j]
+      if (isIntentionalOverlayPair(a, b)) continue
+
+      const overlap = intersection(a.rect, b.rect)
+      if (!overlap) continue
+
+      const intersectionArea = overlap.width * overlap.height
+      if (intersectionArea < T.OVERLAP_MIN_AREA) continue
+
+      const minArea = Math.min(area(a.rect), area(b.rect))
+      if (minArea <= 0) continue
+
+      const ratio = intersectionArea / minArea
+      const textSensitive = hasText(a) || hasText(b)
+      const errorRatio = textSensitive ? T.OVERLAP_TEXT_ERROR_RATIO : T.OVERLAP_ERROR_RATIO
+      const warnRatio = textSensitive ? T.OVERLAP_TEXT_WARN_RATIO : T.OVERLAP_WARN_RATIO
+      if (ratio < warnRatio) continue
+
+      const severity: IssueSeverity = ratio >= errorRatio ? "error" : "warning"
+      issues.push({
+        type: "overlap",
+        sub: severity === "error" ? "element_collision" : "possible_overlay",
+        severity,
+        detail: `Elements \`${a.selector}\` and \`${b.selector}\` overlap by ${Math.round(ratio * 100)}% of the smaller element (${Math.round(intersectionArea)}px²). Separate the components, reduce content, or choose a layout with more space.`,
+        data: {
+          elementA: a.selector,
+          elementB: b.selector,
+          overlapRatioPct: Math.round(ratio * 100),
+          intersectionArea: Math.round(intersectionArea),
+          rectA: rectData(a.rect),
+          rectB: rectData(b.rect),
+        },
+      })
+    }
+  }
+
+  return issues
+}
+
+function overlapCandidates(elements: ElementInfo[]): ElementInfo[] {
+  const semantic = elements.flatMap((element) => semanticDescendants(element))
+  const base = semantic.length > 1 ? semantic : elements.filter((element) => element.visible)
+  return base.filter((element) => {
+    if (!element.visible) return false
+    if (area(element.rect) < T.OVERLAP_MIN_ELEMENT_AREA) return false
+    if (isDecorative(element)) return false
+    return true
+  })
+}
+
+function semanticDescendants(element: ElementInfo): ElementInfo[] {
+  if (!element.visible || isDecorative(element)) return []
+  if (isSemanticComponent(element)) return [element]
+  return element.children.flatMap((child) => semanticDescendants(child))
+}
+
+function isSemanticComponent(element: ElementInfo): boolean {
+  return element.classList.some((className) =>
+    SEMANTIC_COMPONENT_CLASSES.includes(className) || className.startsWith("roadmap-")
+  )
+}
+
+function isDecorative(element: ElementInfo): boolean {
+  return element.classList.some((className) =>
+    DECORATIVE_CLASSES.includes(className) || className.startsWith("decorative-") || className.startsWith("background-")
+  )
+}
+
+function isIntentionalOverlayPair(a: ElementInfo, b: ElementInfo): boolean {
+  const classes = new Set([...a.classList, ...b.classList])
+  return classes.has("hero") && (classes.has("media") || classes.has("text-panel"))
+}
+
+function intersection(a: Rect, b: Rect): Rect | undefined {
+  const left = Math.max(a.left, b.left)
+  const top = Math.max(a.top, b.top)
+  const right = Math.min(a.right, b.right)
+  const bottom = Math.min(a.bottom, b.bottom)
+  if (right <= left || bottom <= top) return undefined
+  return { left, top, right, bottom, width: right - left, height: bottom - top }
+}
+
+function area(rect: Rect): number {
+  return Math.max(0, rect.width) * Math.max(0, rect.height)
+}
+
+function hasText(element: ElementInfo): boolean {
+  if (element.text?.trim()) return true
+  return element.children.some(hasText)
+}
+
+function rectData(rect: Rect): string {
+  return `${Math.round(rect.left)},${Math.round(rect.top)},${Math.round(rect.right)},${Math.round(rect.bottom)}`
+}
+
 function checkContentDensity(metrics: SlideMetrics): LayoutIssue[] {
   if (!metrics.slideQa) return []
   const { bodyTextPoints, contentUnits, supportReferences } = metrics.contentStats
@@ -621,13 +817,16 @@ export function runChecks(
   _options?: RunChecksOptions,
 ): QAReport {
   const slides: SlideReport[] = []
+  const navigationIssues = checkNavigationModel(allMetrics)
 
   for (const metrics of allMetrics) {
     const issues: LayoutIssue[] = [
+      ...(metrics.index === 0 ? navigationIssues : []),
       ...checkCanvas(metrics),
       ...checkScrollbars(metrics),
       ...checkOverflow(metrics),
       ...checkTextOverflow(metrics),
+      ...checkElementOverlap(metrics),
       ...checkContentDensity(metrics),
     ]
 
@@ -693,9 +892,11 @@ export function formatReport(report: QAReport): string {
     ``,
     `Please fix the above hard-error issues in the HTML file. For each issue type:`,
     `- **canvas**: ensure each slide and .slide-canvas render exactly 1920x1080px, not merely any 16:9 size.`,
-    `- **scrollbar**: remove document/body/slide scrolling; content must fit inside the fixed 1920x1080 canvas.`,
+    `- **scrollbar**: remove horizontal document/body scrolling and slide-internal scrolling. Multi-slide decks may use normal vertical document scroll for navigation.`,
+    `- **navigation**: keep every .slide in normal document flow; do not stack slides with fixed/absolute positioning or rely on aria-hidden/visibility toggles for pagination. Use scrollIntoView-based navigation.`,
     `- **overflow**: reduce font size, padding, or content amount for the affected element.`,
     `- **text_overflow**: increase the text container size, reduce copy, or adjust font/line-height so text is not clipped.`,
+    `- **overlap**: separate overlapping components, reduce copy, resize media/table/chart blocks, or use a layout with more space.`,
     `- **density/thin_content**: add concrete claim/evidence points, metrics, chart/table support, or source/caveat text. This is a warning for content substance, not a blank-space failure.`,
     `- **compliance/unknown_class**: an HTML element uses a CSS class not defined in the active design. Replace it with a class from the Component Index or Layout Index. Fetch the component/layout details with the \`revela-designs\` tool if needed.`,
     `- **compliance/novel_css_rule**: \`<style>\` defines a CSS class that is not part of the active design. Remove the custom rule and use the design's existing component styles. For minor spacing/sizing adjustments, use inline \`style=""\` instead.`,

package/lib/qa/measure.ts

@@ -64,6 +64,29 @@ export interface SlideContentStats {
   supportReferences: number
 }
 
+export interface ScrollbarMetrics {
+  documentHorizontal: boolean
+  documentVertical: boolean
+  bodyHorizontal: boolean
+  bodyVertical: boolean
+  slideHorizontal: boolean
+  slideVertical: boolean
+}
+
+export interface SlideNavigationMetrics {
+  totalSlides: number
+  initialTop: number
+  initialLeft: number
+  position: string
+  visibility: string
+  display: string
+  ariaHidden: string | null
+  bodyOverflowY: string
+  documentOverflowY: string
+  documentScrollHeight: number
+  viewportHeight: number
+}
+
 export interface SlideMetrics {
   /** 0-based slide index */
   index: number
@@ -82,6 +105,10 @@ export interface SlideMetrics {
   slideRect: Rect
   /** whether document/body/slide has scrollbars at 1920x1080 */
   hasScrollbars: boolean
+  /** detailed scrollbar source signals for document/body/slide */
+  scrollbars?: ScrollbarMetrics
+  /** deck navigation model signals captured before per-slide scrolling */
+  navigation?: SlideNavigationMetrics
   /** top-level visible children of .slide-canvas */
   elements: ElementInfo[]
   /** union bounding box of all visible leaf elements */
@@ -163,6 +190,31 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
       () => document.querySelectorAll(".slide").length
     )
 
+    const navigationData = await page.evaluate(() => {
+      const doc = document.documentElement
+      const body = document.body
+      const docStyle = window.getComputedStyle(doc)
+      const bodyStyle = window.getComputedStyle(body)
+      const slides = Array.from(document.querySelectorAll(".slide")) as HTMLElement[]
+      return slides.map((slide) => {
+        const rect = slide.getBoundingClientRect()
+        const style = window.getComputedStyle(slide)
+        return {
+          totalSlides: slides.length,
+          initialTop: rect.top,
+          initialLeft: rect.left,
+          position: style.position,
+          visibility: style.visibility,
+          display: style.display,
+          ariaHidden: slide.getAttribute("aria-hidden"),
+          bodyOverflowY: bodyStyle.overflowY,
+          documentOverflowY: docStyle.overflowY,
+          documentScrollHeight: doc.scrollHeight,
+          viewportHeight: window.innerHeight,
+        }
+      })
+    })
+
     const metrics: SlideMetrics[] = []
 
     for (let idx = 0; idx < slideCount; idx++) {
@@ -370,6 +422,15 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             slideEl.scrollWidth > slideEl.clientWidth + 2 ||
             slideEl.scrollHeight > slideEl.clientHeight + 2
 
+          const scrollbars = {
+            documentHorizontal: doc.scrollWidth > window.innerWidth + 2,
+            documentVertical: doc.scrollHeight > window.innerHeight + 2,
+            bodyHorizontal: body.scrollWidth > window.innerWidth + 2,
+            bodyVertical: body.scrollHeight > window.innerHeight + 2,
+            slideHorizontal: slideEl.scrollWidth > slideEl.clientWidth + 2,
+            slideVertical: slideEl.scrollHeight > slideEl.clientHeight + 2,
+          }
+
           const titleEl = canvas.querySelector("h1, h2")
           const title = titleEl
             ? (titleEl.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80)
@@ -382,6 +443,7 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             canvasRect,
             slideRect,
             hasScrollbars,
+            scrollbars,
             elements,
             contentRect: unionRect(elements),
             contentStats: { bodyTextPoints, contentUnits, supportReferences },
@@ -390,7 +452,7 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
         idx
       )
 
-      if (slideData) metrics.push(slideData as SlideMetrics)
+      if (slideData) metrics.push({ ...(slideData as SlideMetrics), navigation: navigationData[idx] })
     }
 
     // Extract all CSS class names defined in <style> blocks.