@cyber-dash-tech/revela 0.18.15 → 0.19.0

package/lib/page-templates/templates/agenda.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const agendaTemplate = templateModule("agenda")
+

package/lib/page-templates/templates/chart-takeaways.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const chartTakeawaysTemplate = templateModule("chart-takeaways")
+

package/lib/page-templates/templates/claim-supporting-visual.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const claimSupportingVisualTemplate = templateModule("claim-supporting-visual")
+

package/lib/page-templates/templates/closing.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const closingTemplate = templateModule("closing")
+

package/lib/page-templates/templates/cover.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const coverTemplate = templateModule("cover")
+

package/lib/page-templates/templates/executive-summary.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const executiveSummaryTemplate = templateModule("executive-summary")
+

package/lib/page-templates/templates/index.ts

@@ -0,0 +1,19 @@
+import { listPageTemplateVocabulary } from "../vocabulary"
+
+export const BUILTIN_PAGE_TEMPLATE_IDS = listPageTemplateVocabulary().map((template) => template.templateId)
+
+export * from "./agenda"
+export * from "./chart-takeaways"
+export * from "./claim-supporting-visual"
+export * from "./closing"
+export * from "./cover"
+export * from "./executive-summary"
+export * from "./key-message-evidence"
+export * from "./metric-highlight"
+export * from "./problem-context"
+export * from "./process-steps"
+export * from "./recommendation-decision"
+export * from "./risks-tradeoffs"
+export * from "./section-divider"
+export * from "./table-comparison"
+export * from "./timeline-roadmap"

package/lib/page-templates/templates/key-message-evidence.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const keyMessageEvidenceTemplate = templateModule("key-message-evidence")
+

package/lib/page-templates/templates/metric-highlight.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const metricHighlightTemplate = templateModule("metric-highlight")
+

package/lib/page-templates/templates/problem-context.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const problemContextTemplate = templateModule("problem-context")
+

package/lib/page-templates/templates/process-steps.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const processStepsTemplate = templateModule("process-steps")
+

package/lib/page-templates/templates/recommendation-decision.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const recommendationDecisionTemplate = templateModule("recommendation-decision")
+

package/lib/page-templates/templates/risks-tradeoffs.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const risksTradeoffsTemplate = templateModule("risks-tradeoffs")
+

package/lib/page-templates/templates/section-divider.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const sectionDividerTemplate = templateModule("section-divider")
+

package/lib/page-templates/templates/shared.ts

@@ -0,0 +1,11 @@
+import { getPageTemplateFoundation } from "../foundation"
+import { getPageTemplateVocabulary } from "../vocabulary"
+
+export function templateModule(templateId: string) {
+  return {
+    templateId,
+    foundation: () => getPageTemplateFoundation(templateId),
+    vocabulary: () => getPageTemplateVocabulary(templateId),
+  }
+}
+

package/lib/page-templates/templates/table-comparison.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const tableComparisonTemplate = templateModule("table-comparison")
+

package/lib/page-templates/templates/timeline-roadmap.ts

@@ -0,0 +1,4 @@
+import { templateModule } from "./shared"
+
+export const timelineRoadmapTemplate = templateModule("timeline-roadmap")
+

package/lib/page-templates/vocabulary.ts

@@ -0,0 +1,158 @@
+export interface PageTemplateSlotVocabulary {
+  name: string
+  required: boolean
+  editable: boolean
+  replaceable: boolean
+  description: string
+}
+
+export interface PageTemplateVocabulary {
+  templateId: string
+  rootClasses: string[]
+  requiredClasses: string[]
+  optionalClasses: string[]
+  slots: PageTemplateSlotVocabulary[]
+  editableSlots: string[]
+  replaceableSlots: string[]
+  contractNotes: string[]
+}
+
+const sharedClasses = [
+  "template-slide",
+  "template-frame",
+  "template-eyebrow",
+  "template-title",
+  "template-body",
+  "template-grid",
+  "template-chart-layout",
+  "cols-2",
+  "cols-3",
+  "cols-4",
+  "template-card",
+  "template-list",
+  "template-hero",
+  "template-hero-title",
+  "template-hero--cover",
+  "template-hero--section-divider",
+  "template-hero--closing",
+  "template-frame--catalog",
+  "template-page-number",
+  "template-image-card",
+  "template-image-frame",
+  "template-image-caption",
+  "template-visual-placeholder",
+  "template-visual-placeholder-frame",
+  "template-visual-placeholder-label",
+]
+
+export const PAGE_TEMPLATE_VOCABULARY: PageTemplateVocabulary[] = [
+  vocab("cover", ["template-hero"], ["hero"], ["hero"], ["Cover, divider, and closing templates use the hero frame; keep title hierarchy visible."]),
+  vocab("section-divider", ["template-hero"], ["hero"], ["hero"], ["Section divider uses the same hero-safe structure as cover."]),
+  vocab("closing", ["template-hero"], ["hero"], ["hero"], ["Closing uses the same hero-safe structure as cover."]),
+  vocab("agenda", ["template-agenda-panel"], ["agenda", "agenda-list"], ["agenda", "agenda-list"], ["Agenda numbers must remain in DOM order."]),
+  vocab("executive-summary", ["template-card"], ["summary-cards"], ["summary-cards"], ["Cards are editable; visual placeholders are optional and may become image/chart slots."]),
+  vocab("problem-context", ["template-card"], ["context", "supporting-points"], ["context", "supporting-points"], ["Context should stay separate from supporting bullets."]),
+  vocab("key-message-evidence", ["template-key-message-panel", "template-evidence-grid"], ["key-message", "evidence"], ["key-message", "evidence"], ["Key message and evidence regions must remain distinct."]),
+  vocab("claim-supporting-visual", ["template-claim-text-panel", "template-visual-slot-panel"], ["claim", "visual"], ["claim", "visual"], ["Visual slot may be replaced by image, chart, table, or diagram container."]),
+  vocab("metric-highlight", ["template-stat-grid"], ["metrics"], ["metrics", "insight"], ["Metric values should remain visible outside prose."]),
+  vocab("chart-takeaways", ["template-chart-panel", "template-chart-takeaway-panel"], ["visual", "takeaways"], ["visual", "takeaways"], ["Chart/image slot and takeaway text panel must both remain present."]),
+  vocab("table-comparison", ["template-table-wrap", "template-table"], ["table"], ["table", "insight"], ["Table headers and body should remain structured, not prose-only."]),
+  vocab("timeline-roadmap", ["template-timeline", "template-timeline-item", "template-timeline-dot", "template-timeline-copy", "template-insight-icon"], ["timeline"], ["timeline", "insight"], ["Each timeline item must keep dot and copy as sibling anchors inside one item.", "Horizontal timeline cards reuse .template-card; highlight uses the item modifier."]),
+  vocab("process-steps", ["template-steps", "template-step-number"], ["steps"], ["steps"], ["Steps should remain ordered in DOM order."]),
+  vocab("recommendation-decision", ["template-card"], ["recommendation", "rationale", "next-steps"], ["recommendation", "rationale", "next-steps"], ["Keep recommendation, rationale, and next steps separate."]),
+  vocab("risks-tradeoffs", ["template-card"], ["risks"], ["risks"], ["Risk/tradeoff cards should name uncertainty explicitly."]),
+]
+
+const additionalClasses = [
+  "template-key-message-panel",
+  "template-key-message-kicker",
+  "template-evidence-grid",
+  "template-evidence-card",
+  "template-claim-text-panel",
+  "template-claim-text-title",
+  "template-claim-text-body",
+  "template-agenda-panel",
+  "template-agenda-inner",
+  "template-agenda-header",
+  "template-agenda-footer",
+  "template-agenda-list",
+  "template-agenda-item",
+  "template-stat-grid",
+  "template-stat-value",
+  "template-metric-layout",
+  "template-metric-layout--insight-top",
+  "template-metric-layout--insight-bottom",
+  "template-chart-panel",
+  "template-chart-placeholder",
+  "template-visual-slot-panel",
+  "template-visual-slot-label",
+  "template-chart-takeaway-panel",
+  "template-chart-takeaway-list",
+  "template-chart-takeaway-item",
+  "template-bar",
+  "template-table",
+  "template-table-wrap",
+  "template-side-panel",
+  "template-side-panel-title",
+  "template-side-panel-body",
+  "template-side-panel--left",
+  "template-side-panel--right",
+  "template-text-panel",
+  "template-text-panel-title",
+  "template-text-panel-body",
+  "template-insight-panel",
+  "template-insight-title",
+  "template-insight-icon",
+  "template-insight-body",
+  "template-timeline",
+  "template-timeline-layout",
+  "template-timeline-layout--left",
+  "template-timeline-layout--right",
+  "template-timeline--horizontal",
+  "template-timeline--vertical",
+  "template-timeline-item",
+  "template-timeline-item--highlight",
+  "template-timeline-dot",
+  "template-timeline-copy",
+  "template-timeline-date",
+  "template-steps",
+  "template-step-number",
+  "template-catalog-panel",
+  "template-catalog-kicker",
+  "template-catalog-title",
+  "template-catalog-grid",
+  "template-catalog-section",
+  "template-catalog-list",
+]
+
+export const PAGE_TEMPLATE_CLASSES = [...new Set([...sharedClasses, ...additionalClasses])]
+
+export function listPageTemplateVocabulary(): PageTemplateVocabulary[] {
+  return PAGE_TEMPLATE_VOCABULARY
+}
+
+export function getPageTemplateVocabulary(templateId: string): PageTemplateVocabulary {
+  const vocabulary = PAGE_TEMPLATE_VOCABULARY.find((item) => item.templateId === templateId)
+  if (!vocabulary) throw new Error(`Unknown page template vocabulary: ${templateId}`)
+  return vocabulary
+}
+
+function vocab(templateId: string, requiredClasses: string[], slotNames: string[], replaceableSlots: string[], contractNotes: string[]): PageTemplateVocabulary {
+  const slots = slotNames.map((name) => ({
+    name,
+    required: true,
+    editable: true,
+    replaceable: replaceableSlots.includes(name),
+    description: `${templateId} ${name} slot.`,
+  }))
+  return {
+    templateId,
+    rootClasses: ["template-slide", "template-frame", ...requiredClasses.slice(0, 1)],
+    requiredClasses,
+    optionalClasses: [],
+    slots,
+    editableSlots: slotNames,
+    replaceableSlots,
+    contractNotes,
+  }
+}

package/lib/prompt-builder.ts

@@ -82,12 +82,12 @@ export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, l
   // Layer 1 — core skill for the selected prompt mode.
   const coreSkill = readFileSync(mode === "deck-render" ? SKILL_MD_PATH : NARRATIVE_SKILL_MD_PATH, "utf-8")
 
-  // Check for preview.html
+  // Check for CSS-native design styling.
   const designDir = join(DESIGNS_DIR, design)
-  const hasPreview = existsSync(join(designDir, "preview.html"))
-  const previewLine = hasPreview
-    ? "<!--   - preview.html — canonical visual reference (read this before generating slides) -->"
-    : "<!--   - (no preview.html for this design) -->"
+  const hasDesignCss = existsSync(join(designDir, "design.css"))
+  const previewLine = hasDesignCss
+    ? "<!--   - design.css — executable design styling; generated previews use the built-in page template fixture -->"
+    : "<!--   - (no design.css for this design; compatibility CSS may be generated from DESIGN.md) -->"
 
   // Layer 2 — DOMAIN.md skill text (narrative mode only). Deck-render mode
   // renders the approved canonical narrative and must not re-interpret domain
@@ -190,6 +190,10 @@ function buildDesignLayer(designName: string): string {
   const componentIndex = generateComponentIndex(components)
   if (componentIndex) {
     layerParts.push(componentIndex)
+    layerParts.push([
+      "Components marked `✓` in the Contract column have required internal structure.",
+      "Fetch the component details before using them and preserve the required DOM/classes instead of hand-rolling a simpler lookalike.",
+    ].join(" "))
   }
 
   // 5. On-demand note

package/lib/qa/artifact.ts

@@ -1,8 +1,13 @@
 import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "../deck-html/contract"
-import type { DesignClassVocabulary } from "../design/designs"
+import { activeDesign, extractDesignComponentContracts } from "../design/designs"
+import type { DesignClassVocabulary, DesignComponentContract } from "../design/designs"
 import { formatReport, runQA } from "./index"
 import { runComplianceQA } from "./compliance"
+import { runComponentContractQA } from "./component-contracts"
+import { formatPageTemplateContractReport, validatePageTemplateContracts } from "../page-templates"
 import type { QAReport } from "./checks"
+import { existsSync, readFileSync } from "fs"
+import { basename, dirname, resolve } from "path"
 
 export interface ArtifactQAReport {
   file: string
@@ -24,6 +29,7 @@ export async function runArtifactQA(input: {
   workspaceRoot: string
   filePath: string
   vocabulary?: DesignClassVocabulary
+  componentContracts?: DesignComponentContract[]
 }): Promise<ArtifactQAReport> {
   const sections: string[] = []
   let hardErrorCount = 0
@@ -39,12 +45,42 @@ export async function runArtifactQA(input: {
     sections.push("**[deck HTML contract]**\n\n" + formatDeckHtmlContractReport(contract))
   }
 
-  const compliance = runComplianceQA(input.filePath, input.vocabulary)
-  const complianceErrors = hardErrors(compliance)
-  if (compliance.totalIssues > 0) {
-    hardErrorCount += complianceErrors
-    warningCount += warnings(compliance)
-    sections.push("**[component compliance]**\n\n" + formatReport(compliance))
+  const designCss = validateLinkedDesignCss(input.filePath)
+  if (designCss.errors.length > 0 || designCss.warnings.length > 0) {
+    hardErrorCount += designCss.errors.length
+    warningCount += designCss.warnings.length
+    sections.push("**[design CSS snapshot]**\n\n" + [
+      ...designCss.errors.map((message) => `- ERROR: ${message}`),
+      ...designCss.warnings.map((message) => `- WARNING: ${message}`),
+    ].join("\n"))
+  }
+
+  if (shouldRunArtifactCompliance(input.filePath)) {
+    const compliance = runComplianceQA(input.filePath, input.vocabulary)
+    const complianceErrors = hardErrors(compliance)
+    if (compliance.totalIssues > 0) {
+      hardErrorCount += complianceErrors
+      warningCount += warnings(compliance)
+      sections.push("**[component compliance]**\n\n" + formatReport(compliance))
+    }
+  }
+
+  const componentContracts = input.componentContracts ?? componentContractsForArtifact(input.filePath)
+  if (componentContracts.length > 0) {
+    const componentContractReport = runComponentContractQA(input.filePath, componentContracts)
+    const contractErrors = hardErrors(componentContractReport)
+    if (componentContractReport.totalIssues > 0) {
+      hardErrorCount += contractErrors
+      warningCount += warnings(componentContractReport)
+      sections.push("**[component structure contracts]**\n\n" + formatReport(componentContractReport))
+    }
+  }
+
+  const templateContracts = validatePageTemplateContracts(input.filePath)
+  if (templateContracts.issues.length > 0) {
+    hardErrorCount += templateContracts.issues.filter((issue) => issue.severity === "error").length
+    warningCount += templateContracts.issues.filter((issue) => issue.severity === "warning").length
+    sections.push("**[page template contracts]**\n\n" + formatPageTemplateContractReport(templateContracts))
   }
 
   try {
@@ -69,6 +105,80 @@ export async function runArtifactQA(input: {
   }
 }
 
+function validateLinkedDesignCss(filePath: string): { errors: string[]; warnings: string[] } {
+  if (isDesignPreviewFile(filePath)) return { errors: [], warnings: [] }
+  const errors: string[] = []
+  const warnings: string[] = []
+  let html = ""
+  try {
+    html = readFileSync(filePath, "utf-8")
+  } catch {
+    return { errors, warnings }
+  }
+  const hrefs = [...html.matchAll(/<link\b[^>]*rel=["']stylesheet["'][^>]*href=["']([^"']*design\.css)["'][^>]*>/gi)].map((match) => match[1])
+  if (hrefs.length === 0) {
+    warnings.push("Deck does not reference a design.css snapshot.")
+    return { errors, warnings }
+  }
+  for (const href of hrefs) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href)) continue
+    const cssPath = resolve(dirname(filePath), href)
+    if (!existsSync(cssPath)) {
+      errors.push(`Linked design CSS is missing: ${href}`)
+      continue
+    }
+    const css = readFileSync(cssPath, "utf-8")
+    for (const asset of cssAssetUrls(css)) {
+      const assetPath = resolve(dirname(cssPath), asset)
+      if (!existsSync(assetPath)) errors.push(`Linked design CSS references missing asset: ${href} -> ${asset}`)
+    }
+  }
+  return { errors, warnings }
+}
+
+function cssAssetUrls(css: string): string[] {
+  const urls: string[] = []
+  const seen = new Set<string>()
+  const urlRe = /url\(\s*["']?([^"')]+)["']?\s*\)/gi
+  let match: RegExpExecArray | null
+  while ((match = urlRe.exec(css)) !== null) {
+    const raw = match[1].trim()
+    if (!raw || raw.startsWith("data:") || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("#")) continue
+    if (seen.has(raw)) continue
+    seen.add(raw)
+    urls.push(raw)
+  }
+  return urls
+}
+
+function componentContractsForArtifact(filePath: string): DesignComponentContract[] {
+  const designName = designNameFromPreviewPath(filePath)
+  try {
+    return extractDesignComponentContracts(designName || activeDesign())
+  } catch {
+    return []
+  }
+}
+
+export function shouldRunArtifactCompliance(filePath: string): boolean {
+  return !isDesignPreviewFile(filePath)
+}
+
+function isDesignPreviewFile(filePath: string): boolean {
+  const normalizedPath = filePath.replace(/\\/g, "/")
+  if (basename(normalizedPath) !== "preview.html") return false
+  const parts = dirname(normalizedPath).split("/")
+  return parts.length >= 2 && parts[parts.length - 2] === "designs"
+}
+
+function designNameFromPreviewPath(filePath: string): string | undefined {
+  const normalizedPath = filePath.replace(/\\/g, "/")
+  if (basename(normalizedPath) !== "preview.html") return undefined
+  const parts = dirname(normalizedPath).split("/")
+  if (parts.length >= 2 && parts[parts.length - 2] === "designs") return parts[parts.length - 1]
+  return undefined
+}
+
 export function formatArtifactQAReport(report: ArtifactQAReport): string {
   const heading = report.passed ? "Artifact QA: PASSED" : "Artifact QA: FAILED"
   const summary = `**File:** \`${report.file}\`\n\n**Hard errors:** ${report.hardErrorCount}\n**Warnings:** ${report.warningCount}`

package/lib/qa/checks.ts

@@ -30,7 +30,7 @@ export interface LayoutIssue {
       | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
-      | "unknown_class" | "novel_css_rule"
+      | "unknown_class" | "novel_css_rule" | "component_contract"
       | "remote_url" | "refine_proxy" | "missing_file"
   severity: IssueSeverity
   /** Human-readable description for the LLM to act on */

package/lib/qa/compliance.ts

@@ -103,9 +103,13 @@ function extractCssDefinedClasses(html: string): ClassUse[] {
   while ((styleMatch = styleRe.exec(html)) !== null) {
     const styleBody = styleMatch[1]
     const bodyOffset = styleMatch.index + styleMatch[0].indexOf(styleBody)
+    const scanBody = styleBody
+      .replace(/url\([^)]*\)/gi, "url()")
+      .replace(/"[^"]*"/g, '""')
+      .replace(/'[^']*'/g, "''")
     classRe.lastIndex = 0
     let classMatch: RegExpExecArray | null
-    while ((classMatch = classRe.exec(styleBody)) !== null) {
+    while ((classMatch = classRe.exec(scanBody)) !== null) {
       const cls = classMatch[1]
       if (classes.has(cls)) continue
 

package/lib/qa/component-contracts.ts

@@ -0,0 +1,90 @@
+import { readFileSync } from "fs"
+import type { DesignComponentContract } from "../design/designs"
+import type { LayoutIssue, QAReport, SlideReport } from "./checks"
+
+function stripTags(value: string): string {
+  return value.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim()
+}
+
+function extractTitle(html: string, index: number): string {
+  const match = /<(?:h1|h2|h3|title)\b[^>]*>([\s\S]*?)<\/(?:h1|h2|h3|title)>/i.exec(html)
+  const title = match ? stripTags(match[1]).slice(0, 80) : ""
+  return title || `Slide ${index + 1}`
+}
+
+function htmlHasClass(html: string, className: string): boolean {
+  const classAttrRe = /class\s*=\s*(["'])([\s\S]*?)\1/gi
+  let match: RegExpExecArray | null
+  while ((match = classAttrRe.exec(html)) !== null) {
+    if (match[2].split(/\s+/).includes(className)) return true
+  }
+  return false
+}
+
+function htmlUsesComponent(html: string, contract: DesignComponentContract): boolean {
+  if (new RegExp(`data-preview-component\\s*=\\s*["']${escapeRegExp(contract.component)}["']`, "i").test(html)) return true
+  return contract.requiredRootClasses.some((className) => htmlHasClass(html, className))
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function validateContract(html: string, contract: DesignComponentContract): LayoutIssue[] {
+  if (!htmlUsesComponent(html, contract)) return []
+
+  const variantFailures: string[] = []
+  for (const variant of contract.variants) {
+    const missing = [
+      ...variant.requiredDescendantClasses.filter((className) => !htmlHasClass(html, className)),
+      ...(variant.repeatedItemClass && !htmlHasClass(html, variant.repeatedItemClass) ? [variant.repeatedItemClass] : []),
+      ...(variant.requiredItemClasses ?? []).filter((className) => !htmlHasClass(html, className)),
+      ...(variant.requireAlternatingClasses ?? []).filter((className) => !htmlHasClass(html, className)),
+    ]
+    if (missing.length === 0) return []
+    variantFailures.push(`${variant.name}: missing ${missing.join(", ")}`)
+  }
+
+  return [{
+    type: "compliance",
+    sub: "component_contract",
+    severity: "error",
+    detail: `Component \`${contract.component}\` does not satisfy its design structure contract. ${contract.guidance}`,
+    data: {
+      component: contract.component,
+      variants: variantFailures.join(" | "),
+    },
+  }]
+}
+
+function summarize(filePath: string, slides: SlideReport[]): QAReport {
+  const totalIssues = slides.reduce((sum, slide) => sum + slide.issues.length, 0)
+  const errorCount = slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "error").length, 0)
+  const warningCount = slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "warning").length, 0)
+  const summary = totalIssues === 0
+    ? "All component structure contracts passed."
+    : `Found ${totalIssues} component contract issue(s): ${errorCount} error(s), ${warningCount} warning(s).`
+  return { file: filePath, slides, totalIssues, errorCount, warningCount, summary }
+}
+
+export function runComponentContractQA(htmlFilePath: string, contracts: DesignComponentContract[]): QAReport {
+  const html = readFileSync(htmlFilePath, "utf-8")
+  const sectionRe = /<section\b[\s\S]*?<\/section>/gi
+  const slides: SlideReport[] = []
+  let match: RegExpExecArray | null
+  let index = 0
+
+  while ((match = sectionRe.exec(html)) !== null) {
+    const chunk = match[0]
+    const issues = contracts.flatMap((contract) => validateContract(chunk, contract))
+    slides.push({ index, title: extractTitle(chunk, index), issues })
+    index++
+  }
+
+  if (slides.length === 0) {
+    const issues = contracts.flatMap((contract) => validateContract(html, contract))
+    slides.push({ index: 0, title: extractTitle(html, 0), issues })
+  }
+
+  return summarize(htmlFilePath, slides)
+}