@cyber-dash-tech/revela 0.15.0 → 0.15.2

package/lib/media/search.ts

@@ -0,0 +1,385 @@
+import type { MediaPurpose } from "./types"
+
+export interface ImageCandidate {
+  candidateId: string
+  provider: string
+  title: string
+  thumbnailUrl: string
+  imageUrl: string
+  sourcePageUrl?: string
+  width?: number
+  height?: number
+  alt?: string
+  license?: string
+  attribution?: string
+  purpose?: MediaPurpose
+}
+
+export interface ImageSearchInput {
+  query: string
+  purpose?: MediaPurpose
+  limit?: number
+  page?: number
+  signal?: AbortSignal
+  providerTimeoutMs?: number
+}
+
+export interface ImageSearchProvider {
+  name: string
+  search(input: ImageSearchInput): Promise<ImageCandidate[]>
+}
+
+const PROVIDER_TIMEOUT_MS: Record<string, number> = {
+  "website-metadata": 3000,
+  unsplash: 6000,
+  "wikimedia-commons": 7000,
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function normalizeLimit(limit: number | undefined): number {
+  if (!Number.isFinite(limit ?? Number.NaN)) return 12
+  return Math.max(1, Math.min(48, Math.floor(limit!)))
+}
+
+function normalizePage(page: number | undefined): number {
+  if (!Number.isFinite(page ?? Number.NaN)) return 1
+  return Math.max(1, Math.floor(page!))
+}
+
+function domainFromQuery(query: string): string | null {
+  const value = query.trim().toLowerCase()
+  if (!value) return null
+  const withoutProtocol = value.replace(/^https?:\/\//, "").replace(/^www\./, "")
+  const first = withoutProtocol.split(/[\s/]+/)[0]
+  if (/^[a-z0-9.-]+\.[a-z]{2,}$/.test(first)) return first
+  const compact = value.replace(/\b(logo|company|brand)\b/g, "").replace(/[^a-z0-9]+/g, "")
+  if (!compact) return null
+  return `${compact}.com`
+}
+
+function textFromMetadata(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const raw = (value as { value?: unknown }).value
+  return typeof raw === "string" && raw.trim() ? raw.replace(/<[^>]+>/g, "").trim() : undefined
+}
+
+function compactBrandName(query: string): string | null {
+  const value = query
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/^www\./, "")
+    .split(/[\s/]+/)[0]
+    .replace(/\.[a-z]{2,}$/, "")
+    .replace(/\b(logo|company|brand)\b/g, "")
+    .replace(/[^a-z0-9]+/g, "")
+  return value || null
+}
+
+function absoluteUrl(value: string, base: string): string | undefined {
+  try {
+    return new URL(value, base).toString()
+  } catch {
+    return undefined
+  }
+}
+
+function uniqueValues(values: Array<string | undefined>): string[] {
+  const seen = new Set<string>()
+  return values.flatMap((value) => {
+    if (!value || seen.has(value)) return []
+    seen.add(value)
+    return [value]
+  })
+}
+
+function htmlAttr(tag: string, attr: string): string | undefined {
+  const pattern = new RegExp(`${attr}=["']([^"']+)["']`, "i")
+  return tag.match(pattern)?.[1]
+}
+
+function htmlMetaContent(html: string, property: string): string | undefined {
+  const tags = html.match(/<meta\b[^>]*>/gi) ?? []
+  const needle = property.toLowerCase()
+  for (const tag of tags) {
+    const key = htmlAttr(tag, "property") || htmlAttr(tag, "name")
+    if (key?.toLowerCase() === needle) return htmlAttr(tag, "content")
+  }
+  return undefined
+}
+
+function htmlIconLinks(html: string): string[] {
+  const tags = html.match(/<link\b[^>]*>/gi) ?? []
+  return tags.flatMap((tag) => {
+    const rel = htmlAttr(tag, "rel")?.toLowerCase() ?? ""
+    if (!rel.includes("icon") && !rel.includes("apple-touch-icon")) return []
+    return htmlAttr(tag, "href") ?? []
+  })
+}
+
+function queryForPurpose(query: string, purpose: MediaPurpose | undefined): string {
+  const value = query.trim()
+  if (!value) return value
+  if (purpose === "hero") return `${value} hero background professional photography`
+  if (purpose === "portrait") return `${value} portrait headshot`
+  if (purpose === "screenshot") return `${value} screenshot interface product`
+  if (purpose === "illustration") return `${value} professional photo concept visual`
+  return value
+}
+
+function wikimediaQueryForPurpose(query: string, purpose: MediaPurpose | undefined): string {
+  const value = query.trim()
+  if (!value) return value
+  if (purpose === "portrait") return `${value} portrait`
+  if (purpose === "screenshot") return `${value} screenshot`
+  return value
+}
+
+export const clearbitLogoProvider: ImageSearchProvider = {
+  name: "clearbit-logo",
+  async search(input) {
+    if (normalizePage(input.page) > 1) return []
+    if (input.purpose && input.purpose !== "logo") return []
+    const domain = domainFromQuery(input.query)
+    if (!domain) return []
+    const title = `${domain} logo`
+    return [{
+      candidateId: `clearbit-${slugify(domain)}`,
+      provider: this.name,
+      title,
+      thumbnailUrl: `https://logo.clearbit.com/${encodeURIComponent(domain)}`,
+      imageUrl: `https://logo.clearbit.com/${encodeURIComponent(domain)}`,
+      sourcePageUrl: `https://${domain}`,
+      alt: title,
+      purpose: "logo",
+    }]
+  },
+}
+
+export const simpleIconsProvider: ImageSearchProvider = {
+  name: "simple-icons",
+  async search(input) {
+    if (normalizePage(input.page) > 1) return []
+    if (input.purpose && input.purpose !== "logo") return []
+    const brand = compactBrandName(input.query)
+    if (!brand) return []
+    const title = `${brand} logo`
+    const cdnUrl = `https://cdn.simpleicons.org/${encodeURIComponent(brand)}`
+    const imageUrl = `https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/${encodeURIComponent(brand)}.svg`
+    return [{
+      candidateId: `simple-icons-${slugify(brand)}`,
+      provider: this.name,
+      title,
+      thumbnailUrl: cdnUrl,
+      imageUrl,
+      sourcePageUrl: `https://simpleicons.org/?q=${encodeURIComponent(brand)}`,
+      alt: title,
+      license: "See Simple Icons source license",
+      attribution: "Simple Icons",
+      purpose: "logo",
+    }]
+  },
+}
+
+export const websiteMetadataProvider: ImageSearchProvider = {
+  name: "website-metadata",
+  async search(input) {
+    if (normalizePage(input.page) > 1) return []
+    const domain = domainFromQuery(input.query)
+    if (!domain) return []
+    const homepage = `https://${domain}`
+    const response = await fetch(homepage, {
+      headers: { "user-agent": "Revela/0.15 asset search" },
+      signal: input.signal,
+    })
+    if (!response.ok) throw new Error(`Website metadata fetch failed: ${response.status}`)
+    const html = await response.text()
+    const title = htmlMetaContent(html, "og:site_name") || html.match(/<title[^>]*>([^<]+)<\/title>/i)?.[1]?.trim() || domain
+    const socialImages = [htmlMetaContent(html, "og:image"), htmlMetaContent(html, "twitter:image")]
+    const icons = [...htmlIconLinks(html), "/favicon.ico"]
+    const sourceUrls = input.purpose === "logo"
+      ? icons
+      : input.purpose === "screenshot"
+        ? socialImages
+        : socialImages
+    const urls = uniqueValues(sourceUrls.map((value) => value ? absoluteUrl(value, homepage) : undefined))
+    return urls.slice(0, normalizeLimit(input.limit)).map((imageUrl, index) => ({
+      candidateId: `website-${slugify(domain)}-${index + 1}`,
+      provider: this.name,
+      title: index === 0 ? `${title} image` : `${title} icon ${index}`,
+      thumbnailUrl: imageUrl,
+      imageUrl,
+      sourcePageUrl: homepage,
+      alt: `${title} image`,
+      purpose: input.purpose,
+    }))
+  },
+}
+
+export const unsplashProvider: ImageSearchProvider = {
+  name: "unsplash",
+  async search(input) {
+    const accessKey = process.env.UNSPLASH_ACCESS_KEY?.trim()
+    if (!accessKey) return []
+    if (input.purpose === "logo" || input.purpose === "screenshot") return []
+    const limit = normalizeLimit(input.limit)
+    const page = normalizePage(input.page)
+    const url = new URL("https://api.unsplash.com/search/photos")
+    url.searchParams.set("query", input.query)
+    url.searchParams.set("per_page", String(Math.min(30, limit)))
+    url.searchParams.set("page", String(page))
+    url.searchParams.set("orientation", input.purpose === "portrait" ? "portrait" : "landscape")
+    const response = await fetch(url, {
+      headers: {
+        authorization: `Client-ID ${accessKey}`,
+        "accept-version": "v1",
+        "user-agent": "Revela/0.15 asset search",
+      },
+      signal: input.signal,
+    })
+    if (!response.ok) throw new Error(`Unsplash search failed: ${response.status}`)
+    const body = await response.json() as any
+    const results = Array.isArray(body?.results) ? body.results : []
+    return results.flatMap((item: any) => {
+      const imageUrl = typeof item?.urls?.regular === "string" ? item.urls.regular : ""
+      if (!imageUrl) return []
+      const title = item.description || item.alt_description || "Unsplash photo"
+      const author = item.user?.name ? String(item.user.name) : undefined
+      return [{
+        candidateId: `unsplash-${slugify(String(item.id || title))}`,
+        provider: this.name,
+        title,
+        thumbnailUrl: typeof item.urls?.small === "string" ? item.urls.small : imageUrl,
+        imageUrl,
+        sourcePageUrl: typeof item.links?.html === "string" ? item.links.html : undefined,
+        width: typeof item.width === "number" ? item.width : undefined,
+        height: typeof item.height === "number" ? item.height : undefined,
+        alt: item.alt_description || title,
+        license: "Unsplash License",
+        attribution: author ? `Photo by ${author} on Unsplash` : "Unsplash",
+        purpose: input.purpose,
+      }]
+    }).slice(0, limit)
+  },
+}
+
+export const wikimediaProvider: ImageSearchProvider = {
+  name: "wikimedia-commons",
+  async search(input) {
+    const limit = normalizeLimit(input.limit)
+    const page = normalizePage(input.page)
+    const url = new URL("https://commons.wikimedia.org/w/api.php")
+    url.searchParams.set("action", "query")
+    url.searchParams.set("format", "json")
+    url.searchParams.set("origin", "*")
+    url.searchParams.set("generator", "search")
+    url.searchParams.set("gsrnamespace", "6")
+    url.searchParams.set("gsrlimit", String(limit))
+    url.searchParams.set("gsroffset", String((page - 1) * limit))
+    url.searchParams.set("gsrsearch", input.query)
+    url.searchParams.set("prop", "imageinfo|info")
+    url.searchParams.set("iiprop", "url|thumburl|mime|size|extmetadata")
+    url.searchParams.set("iiurlwidth", "320")
+    url.searchParams.set("inprop", "url")
+
+    const response = await fetch(url, {
+      headers: { "user-agent": "Revela/0.15 asset search" },
+      signal: input.signal,
+    })
+    if (!response.ok) throw new Error(`Wikimedia search failed: ${response.status}`)
+    const body = await response.json() as any
+    const pages = Object.values(body?.query?.pages ?? {}) as any[]
+    return pages.flatMap((page) => {
+      const info = page?.imageinfo?.[0]
+      const mime = typeof info?.mime === "string" ? info.mime : ""
+      if (!mime.startsWith("image/")) return []
+      const imageUrl = typeof info?.url === "string" ? info.url : ""
+      if (!imageUrl) return []
+      const thumbnailUrl = typeof info?.thumburl === "string" ? info.thumburl : imageUrl
+      const metadata = info?.extmetadata ?? {}
+      const title = String(page.title || "Wikimedia image").replace(/^File:/, "")
+      return [{
+        candidateId: `wikimedia-${slugify(title).slice(0, 80)}`,
+        provider: this.name,
+        title,
+        thumbnailUrl,
+        imageUrl,
+        sourcePageUrl: typeof page.fullurl === "string" ? page.fullurl : undefined,
+        width: typeof info.width === "number" ? info.width : undefined,
+        height: typeof info.height === "number" ? info.height : undefined,
+        alt: title,
+        license: textFromMetadata(metadata.LicenseShortName) || textFromMetadata(metadata.UsageTerms),
+        attribution: textFromMetadata(metadata.Artist) || textFromMetadata(metadata.Credit),
+        purpose: input.purpose,
+      }]
+    }).slice(0, limit)
+  },
+}
+
+export async function searchRemoteImages(input: ImageSearchInput): Promise<ImageCandidate[]> {
+  const query = input.query.trim()
+  if (!query) return []
+  const limit = normalizeLimit(input.limit)
+  const page = normalizePage(input.page)
+  const mediaQuery = queryForPurpose(query, input.purpose)
+  const wikimediaQuery = wikimediaQueryForPurpose(query, input.purpose)
+  const searches: Array<Promise<ImageCandidate[]>> = input.purpose === "logo"
+    ? [
+      runProvider(clearbitLogoProvider, { ...input, query, limit, page }),
+      runProvider(simpleIconsProvider, { ...input, query, limit, page }),
+      runProvider(websiteMetadataProvider, { ...input, query, limit, page }),
+    ]
+    : input.purpose === "screenshot"
+      ? [
+        runProvider(websiteMetadataProvider, { ...input, query, limit, page }),
+        runProvider(wikimediaProvider, { ...input, query: wikimediaQuery, limit, page }),
+      ]
+      : [
+        runProvider(websiteMetadataProvider, { ...input, query, limit, page }),
+        runProvider(unsplashProvider, { ...input, query: mediaQuery, limit, page }),
+        runProvider(wikimediaProvider, { ...input, query: wikimediaQuery, limit, page }),
+      ]
+  const batches = await Promise.allSettled(searches)
+  const candidates = batches.flatMap((result) => result.status === "fulfilled" ? result.value : [])
+  const seen = new Set<string>()
+  return candidates.filter((candidate) => {
+    const key = candidate.imageUrl || candidate.thumbnailUrl || candidate.candidateId
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  }).slice(0, limit)
+}
+
+async function runProvider(provider: ImageSearchProvider, input: ImageSearchInput): Promise<ImageCandidate[]> {
+  const timeoutMs = input.providerTimeoutMs ?? PROVIDER_TIMEOUT_MS[provider.name]
+  if (!timeoutMs) return provider.search(input).catch(() => [])
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  const signal = input.signal ? anySignal([input.signal, controller.signal]) : controller.signal
+  try {
+    return await provider.search({ ...input, signal })
+  } catch {
+    return []
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function anySignal(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController()
+  const abort = () => controller.abort()
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort()
+      break
+    }
+    signal.addEventListener("abort", abort, { once: true })
+  }
+  return controller.signal
+}

package/lib/media/types.ts

@@ -15,6 +15,12 @@ export interface MediaSaveInput {
   alt?: string
   notes?: string
   failureReason?: string
+  provider?: string
+  sourcePageUrl?: string
+  license?: string
+  attribution?: string
+  width?: number
+  height?: number
 }
 
 export interface MediaAssetRecord {
@@ -30,6 +36,12 @@ export interface MediaAssetRecord {
   alt?: string
   notes?: string
   failureReason?: string
+  provider?: string
+  sourcePageUrl?: string
+  license?: string
+  attribution?: string
+  width?: number
+  height?: number
   savedAt: string
 }
 

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

@@ -1,4 +1,4 @@
-import { 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 } from "../decks-state"
 import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
 import { getClaimSlideRefs } from "./queries"
 import { computeNarrativeHash } from "./hash"
@@ -65,6 +65,15 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
     writeReadiness: deck?.writeReadiness ?? { status: "blocked" as const, blockers: [] },
   })
   next = upsertSlides(next, slug, slides)
+  const plannedDeck = next.decks[slug]
+  plannedDeck.planReview = {
+    status: "pending",
+    narrativeHash,
+    planHash: deckPlanHash(plannedDeck.slides),
+  }
+  plannedDeck.requiredInputs = { ...plannedDeck.requiredInputs, slidePlanConfirmed: false }
+  plannedDeck.writeReadiness = { status: "blocked", blockers: [] }
+  next.decks[slug] = plannedDeck
   next.narrative = { ...narrative, updatedAt: options.now ?? narrative.updatedAt }
   const htmlTarget = ensureActiveHtmlDeckRenderTarget(next)
   if (htmlTarget) {

package/lib/qa/artifact.ts

@@ -0,0 +1,77 @@
+import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "../deck-html/contract"
+import type { DesignClassVocabulary } from "../design/designs"
+import { formatReport, runQA } from "./index"
+import { runComplianceQA } from "./compliance"
+import type { QAReport } from "./checks"
+
+export interface ArtifactQAReport {
+  file: string
+  passed: boolean
+  hardErrorCount: number
+  warningCount: number
+  sections: string[]
+}
+
+function hardErrors(report: QAReport): number {
+  return report.slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "error").length, 0)
+}
+
+function warnings(report: QAReport): number {
+  return report.slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "warning").length, 0)
+}
+
+export async function runArtifactQA(input: {
+  workspaceRoot: string
+  filePath: string
+  vocabulary?: DesignClassVocabulary
+}): Promise<ArtifactQAReport> {
+  const sections: string[] = []
+  let hardErrorCount = 0
+  let warningCount = 0
+
+  const contract = validateDeckHtmlContract(input.workspaceRoot, input.filePath)
+  if (contract.status === "invalid") {
+    hardErrorCount += contract.issues.filter((issue) => issue.severity === "error").length
+    warningCount += contract.warnings.length
+    sections.push("**[deck HTML contract]**\n\n" + formatDeckHtmlContractReport(contract))
+  } else if (contract.warnings.length > 0) {
+    warningCount += contract.warnings.length
+    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))
+  }
+
+  try {
+    const browser = await runQA(input.filePath)
+    const browserErrors = hardErrors(browser)
+    if (browser.totalIssues > 0) {
+      hardErrorCount += browserErrors
+      warningCount += warnings(browser)
+      sections.push("**[browser artifact QA]**\n\n" + formatReport(browser))
+    }
+  } catch (e) {
+    hardErrorCount += 1
+    sections.push("**[browser artifact QA]**\n\nError running browser QA: " + (e instanceof Error ? e.message : String(e)))
+  }
+
+  return {
+    file: input.filePath,
+    passed: hardErrorCount === 0,
+    hardErrorCount,
+    warningCount,
+    sections,
+  }
+}
+
+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}`
+  if (report.sections.length === 0) return `## ${heading}\n\n${summary}\n\nAll artifact QA checks passed.`
+  return `## ${heading}\n\n${summary}\n\n${report.sections.join("\n\n---\n\n")}`
+}

package/lib/qa/checks.ts

@@ -1,17 +1,18 @@
 /**
  * lib/qa/checks.ts
  *
- * Geometry-based layout quality checks. The active default path only checks
- * overflow; softer visual heuristics are kept here for future opt-in use.
+ * Browser-measured slide quality checks. The active default path checks hard
+ * artifact failures plus a content-substance warning; older soft visual
+ * heuristics are kept here for future opt-in use.
  *
- * Dimension 1: Overflow    — elements exceed canvas bounds (correctness)
- * Dimension 2: Balance     — content centroid & distribution (fill, sparsity)
- * Dimension 3: Rhythm      — spacing regularity & internal whitespace
+ * Dimension 1: Canvas      — exact 1920x1080 slide/canvas size
+ * Dimension 2: Overflow    — scrollbars, element overflow, and text clipping
+ * Dimension 3: Density     — claim/evidence/source substance warnings
  * Dimension 4: Compliance  — CSS classes match the active design's vocabulary
  *
  * All checks operate on SlideMetrics produced by measure.ts.
- * Dimensions 1–4 are geometry-only (no CSS class-name assumptions).
- * Dimension 5 requires an allowedClasses vocabulary from the design system.
+ * Design component compliance requires an allowedClasses vocabulary from the
+ * design system and is run by combined artifact QA.
  */
 
 import type { SlideMetrics, ElementInfo, Rect } from "./measure"
@@ -22,12 +23,14 @@ import { CANVAS_W, CANVAS_H } from "./measure"
 export type IssueSeverity = "error" | "warning" | "info"
 
 export interface LayoutIssue {
-  type: "overflow" | "balance" | "symmetry" | "rhythm" | "compliance"
+  type: "canvas" | "scrollbar" | "overflow" | "text_overflow" | "density" | "balance" | "symmetry" | "rhythm" | "compliance" | "asset"
   /** Sub-category within the dimension */
-  sub?: "centroid_offset" | "bottom_gap" | "sparse"
+  sub?: "size_mismatch" | "page_scroll" | "text_clipped" | "thin_content"
+      | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
       | "unknown_class" | "novel_css_rule"
+      | "remote_url" | "refine_proxy" | "missing_file"
   severity: IssueSeverity
   /** Human-readable description for the LLM to act on */
   detail: string
@@ -75,6 +78,9 @@ const T = {
   GAP_MIN_MEAN: 10,
   // Rhythm — min children count to check gap variance
   GAP_MIN_CHILDREN: 3,
+  CANVAS_TOLERANCE: 1,
+  DENSITY_MIN_TEXT_POINTS: 70,
+  DENSITY_MIN_UNITS: 2,
 }
 
 // ── Geometry helpers ──────────────────────────────────────────────────────────
@@ -172,6 +178,42 @@ function collectLeaves(el: ElementInfo): ElementInfo[] {
 
 // ── Dimension 1: Overflow ─────────────────────────────────────────────────────
 
+function checkCanvas(metrics: SlideMetrics): LayoutIssue[] {
+  const issues: LayoutIssue[] = []
+  const tol = T.CANVAS_TOLERANCE
+  const canvasBad = Math.abs(metrics.canvasRect.width - CANVAS_W) > tol || Math.abs(metrics.canvasRect.height - CANVAS_H) > tol
+  const slideBad = Math.abs(metrics.slideRect.width - CANVAS_W) > tol || Math.abs(metrics.slideRect.height - CANVAS_H) > tol
+
+  if (canvasBad || slideBad) {
+    issues.push({
+      type: "canvas",
+      sub: "size_mismatch",
+      severity: "error",
+      detail: `Slide and canvas must render exactly ${CANVAS_W}x${CANVAS_H}px. Measured slide ${Math.round(metrics.slideRect.width)}x${Math.round(metrics.slideRect.height)}px, canvas ${Math.round(metrics.canvasRect.width)}x${Math.round(metrics.canvasRect.height)}px.`,
+      data: {
+        expectedWidth: CANVAS_W,
+        expectedHeight: CANVAS_H,
+        slideWidth: Math.round(metrics.slideRect.width),
+        slideHeight: Math.round(metrics.slideRect.height),
+        canvasWidth: Math.round(metrics.canvasRect.width),
+        canvasHeight: Math.round(metrics.canvasRect.height),
+      },
+    })
+  }
+
+  return issues
+}
+
+function checkScrollbars(metrics: SlideMetrics): LayoutIssue[] {
+  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.",
+  }]
+}
+
 /**
  * Check 1: Overflow — elements extending beyond canvas boundaries.
  * Hard correctness check; applies to all slide types.
@@ -205,6 +247,45 @@ function checkOverflow(metrics: SlideMetrics): LayoutIssue[] {
   return issues
 }
 
+function checkTextOverflow(metrics: SlideMetrics): LayoutIssue[] {
+  const issues: LayoutIssue[] = []
+
+  function walk(els: ElementInfo[]) {
+    for (const el of els) {
+      if (!el.visible) continue
+      if (el.textOverflow) {
+        issues.push({
+          type: "text_overflow",
+          sub: "text_clipped",
+          severity: "error",
+          detail: `Text appears clipped inside \`${el.selector}\`${el.text ? `: "${el.text}"` : ""}. Increase container size, reduce copy, or adjust font/line-height.`,
+          data: { selector: el.selector, text: el.text ?? "" },
+        })
+      }
+      if (el.children.length > 0) walk(el.children)
+    }
+  }
+
+  walk(metrics.elements)
+  return issues
+}
+
+function checkContentDensity(metrics: SlideMetrics): LayoutIssue[] {
+  if (!metrics.slideQa) return []
+  const { bodyTextPoints, contentUnits, supportReferences } = metrics.contentStats
+  const thinText = bodyTextPoints < T.DENSITY_MIN_TEXT_POINTS
+  const thinUnits = contentUnits < T.DENSITY_MIN_UNITS
+  if (!thinText && !thinUnits) return []
+
+  return [{
+    type: "density",
+    sub: "thin_content",
+    severity: "warning",
+    detail: `Content slide may not have enough claim/evidence substance: ${bodyTextPoints} non-title text point(s), ${contentUnits} recognizable content unit(s), ${supportReferences} evidence/source/claim reference(s). Add concrete claim points, evidence, metrics, chart/table support, or source/caveat text if this is not a deliberate focus slide.`,
+    data: { bodyTextPoints, contentUnits, supportReferences },
+  }]
+}
+
 // ── Dimension 2: Balance ──────────────────────────────────────────────────────
 
 /**
@@ -542,7 +623,13 @@ export function runChecks(
   const slides: SlideReport[] = []
 
   for (const metrics of allMetrics) {
-    const issues: LayoutIssue[] = [...checkOverflow(metrics)]
+    const issues: LayoutIssue[] = [
+      ...checkCanvas(metrics),
+      ...checkScrollbars(metrics),
+      ...checkOverflow(metrics),
+      ...checkTextOverflow(metrics),
+      ...checkContentDensity(metrics),
+    ]
 
     slides.push({ index: metrics.index, title: metrics.title, issues })
   }
@@ -605,7 +692,11 @@ export function formatReport(report: QAReport): string {
     `### Action Required`,
     ``,
     `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.`,
     `- **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.`,
+    `- **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.`,
   )