@cyber-dash-tech/revela 0.14.0 → 0.15.1

package/lib/decks-state.ts

@@ -18,6 +18,7 @@ import {
 } from "./workspace-state/review-snapshots"
 import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type WorkspaceAction } from "./workspace-state/types"
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
+import { computeNarrativeHash } from "./narrative-state/hash"
 import type { NarrativeStateV1 } from "./narrative-state/types"
 
 export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
@@ -91,6 +92,7 @@ export interface DeckSpec {
   researchPlan: ResearchAxis[]
   slides: SlideSpec[]
   assets: DeckAsset[]
+  planReview?: DeckPlanReview
   writeReadiness: {
     status: WriteReadinessStatus
     blockers: string[]
@@ -98,6 +100,15 @@ export interface DeckSpec {
   }
 }
 
+export interface DeckPlanReview {
+  status: "pending" | "confirmed"
+  narrativeHash: string
+  planHash: string
+  confirmedAt?: string
+  confirmedBy?: "user"
+  summary?: string
+}
+
 export interface NarrativeBrief {
   audienceBeliefBefore?: string
   audienceBeliefAfter?: string
@@ -202,6 +213,7 @@ export type ReadinessSeverity = "blocker" | "warning"
 export type ReadinessIssueType =
   | "missing_required_input"
   | "missing_slide_spec"
+  | "slide_plan_unconfirmed"
   | "research_not_ready"
   | "missing_evidence"
   | "weak_evidence"
@@ -278,6 +290,22 @@ const SOURCE_TRACE_ACTION = "Add slide evidence with source plus source trace su
 
 export interface ReviewDeckStateOptions {
   workspaceRoot?: string
+  narrativeHash?: string
+}
+
+export interface ConfirmDeckPlanOptions {
+  approvedBy?: "user"
+  note?: string
+  now?: string
+}
+
+export interface ConfirmDeckPlanResult {
+  confirmed: boolean
+  skipped: boolean
+  reason?: string
+  slug?: string
+  narrativeHash?: string
+  planHash?: string
 }
 
 export function decksStatePath(workspaceRoot: string): string {
@@ -357,10 +385,74 @@ export function createDeckSpec(input: Partial<DeckSpec> & { slug: string }): Dec
     researchPlan: input.researchPlan ?? [],
     slides: normalizeSlides(input.slides ?? []),
     assets: input.assets ?? [],
+    planReview: normalizeDeckPlanReview(input.planReview),
     writeReadiness: input.writeReadiness ?? { status: "blocked", blockers: [] },
   }
 }
 
+export function deckPlanHash(slides: SlideSpec[]): string {
+  return createHash("sha1")
+    .update(JSON.stringify(normalizeSlides(slides).map((slide) => ({
+      index: slide.index,
+      title: slide.title,
+      purpose: slide.purpose,
+      narrativeRole: slide.narrativeRole,
+      layout: slide.layout,
+      components: slide.components,
+      claimIds: slide.claimIds ?? [],
+      claimRefs: slide.claimRefs ?? [],
+      evidenceBindingIds: slide.evidenceBindingIds ?? [],
+      content: slide.content,
+      evidence: slide.evidence,
+      visuals: slide.visuals ?? [],
+    }))))
+    .digest("hex")
+}
+
+export function currentDeckPlanReviewStatus(deck: DeckSpec, narrativeHash?: string): { current: boolean; stale: boolean; reason?: string; planHash: string } {
+  const planHash = deckPlanHash(deck.slides)
+  const review = deck.planReview
+  if (!review) return { current: false, stale: false, reason: "deck plan has not been shown and confirmed", planHash }
+  if (review.status !== "confirmed") return { current: false, stale: false, reason: "deck plan is pending user confirmation", planHash }
+  if (narrativeHash && review.narrativeHash !== narrativeHash) return { current: false, stale: true, reason: "deck plan confirmation is stale because the narrative hash changed", planHash }
+  if (review.planHash !== planHash) return { current: false, stale: true, reason: "deck plan confirmation is stale because the slide plan changed", planHash }
+  return { current: true, stale: false, planHash }
+}
+
+export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptions = {}): { state: DecksState; result: ConfirmDeckPlanResult } {
+  const normalized = normalizeDecksStateWithNarrative(state)
+  const key = currentDeckKey(normalized)
+  const deck = key ? normalized.decks[key] : undefined
+  if (!deck) {
+    return { state: normalized, result: { confirmed: false, skipped: true, reason: `No active deck exists in ${DECKS_STATE_FILE}.` } }
+  }
+  if (deck.slides.length === 0) {
+    return { state: normalized, result: { confirmed: false, skipped: true, slug: deck.slug, reason: "Cannot confirm a deck plan with no slides." } }
+  }
+  const narrative = normalizeNarrativeState(normalized)
+  const narrativeHash = computeNarrativeHash(narrative)
+  const planHash = deckPlanHash(deck.slides)
+  const pending = deck.planReview
+  if (pending && pending.status === "pending" && (pending.narrativeHash !== narrativeHash || pending.planHash !== planHash)) {
+    return { state: normalized, result: { confirmed: false, skipped: true, slug: deck.slug, narrativeHash, planHash, reason: "Cannot confirm because the pending deck plan is stale. Re-run compileDeckPlan first." } }
+  }
+
+  deck.planReview = {
+    status: "confirmed",
+    narrativeHash,
+    planHash,
+    confirmedAt: options.now ?? new Date().toISOString(),
+    confirmedBy: options.approvedBy ?? "user",
+    summary: cleanOptionalText(options.note),
+  }
+  deck.requiredInputs = { ...deck.requiredInputs, slidePlanConfirmed: true }
+  deck.writeReadiness = { status: "blocked", blockers: [] }
+  normalized.decks[deck.slug] = deck
+  normalized.activeDeck = deck.slug
+  normalized.narrative = narrative
+  return { state: normalized, result: { confirmed: true, skipped: false, slug: deck.slug, narrativeHash, planHash } }
+}
+
 export function readDecksState(workspaceRoot: string): DecksState {
   return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
 }
@@ -487,7 +579,10 @@ export function reviewDeckState(state: DecksState, slug?: string, options: Revie
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace, options)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace, {
+    ...options,
+    narrativeHash: options.narrativeHash ?? computeNarrativeHash(normalizeNarrativeState(normalized)),
+  })
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   const evidenceCandidates = issues.flatMap((issue) => issue.evidenceCandidates ?? [])
@@ -544,7 +639,9 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace, {
+    narrativeHash: computeNarrativeHash(normalizeNarrativeState(normalized)),
+  })
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   if (normalizeDeckPath(deck.outputPath) !== targetPath) {
@@ -564,7 +661,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       type: "missing_slide_spec",
       severity: "blocker",
       message,
-      suggestedAction: "Run /revela review and resolve all readiness blockers before writing deck HTML.",
+      suggestedAction: "Run /revela make deck --review and resolve all readiness blockers before writing deck HTML.",
     })
   }
   if (deck.writeReadiness.blockers.length > 0) {
@@ -574,7 +671,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       type: "missing_slide_spec",
       severity: "blocker",
       message,
-      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela review.",
+      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela make deck --review.",
     })
   }
   if (normalized.reviews.length > 0) {
@@ -587,7 +684,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Run /revela review so readiness is recorded against the current active render target.",
+        suggestedAction: "Run /revela make deck --review so readiness is recorded against the current active render target.",
       })
     } else if (!isReviewSnapshotCurrent(normalized, snapshot, deck.slug)) {
       const message = "Latest review snapshot is stale for the current deck, sources, evidence, narrative state, or render target"
@@ -596,7 +693,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Run /revela review again after the latest state changes before writing deck HTML.",
+        suggestedAction: "Run /revela make deck --review again after the latest state changes before writing deck HTML.",
       })
     } else if (snapshot.status !== "ready") {
       const message = `Latest review snapshot is ${snapshot.status}, not ready`
@@ -605,7 +702,7 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
         type: "missing_slide_spec",
         severity: "blocker",
         message,
-        suggestedAction: "Resolve review blockers and rerun /revela review before writing deck HTML.",
+        suggestedAction: "Resolve review blockers and rerun /revela make deck --review before writing deck HTML.",
       })
     }
   }
@@ -651,7 +748,7 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
-  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection. When review snapshots exist, deck HTML writes require a current non-stale ready review snapshot for the active HTML render target.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
+  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection for the /revela make deck generation workflow, not a hard blocker for targeted artifact-level HTML fixes.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- For /revela make deck generated HTML, use the current deck's outputPath and satisfy the deck HTML contract. For targeted artifact-level edits, patch the requested deck HTML directly without treating \`writeReadiness\` or \`planReview\` as a precondition.`
 }
 
 function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksState["workspace"] {
@@ -765,6 +862,18 @@ function normalizeDecksStateWithNarrative(input: DecksState): DecksState {
   return state
 }
 
+function normalizeDeckPlanReview(input: DeckPlanReview | undefined): DeckPlanReview | undefined {
+  if (!input || !input.narrativeHash || !input.planHash) return undefined
+  return {
+    status: input.status === "confirmed" ? "confirmed" : "pending",
+    narrativeHash: input.narrativeHash,
+    planHash: input.planHash,
+    confirmedAt: cleanOptionalText(input.confirmedAt),
+    confirmedBy: input.confirmedBy === "user" ? "user" : undefined,
+    summary: cleanOptionalText(input.summary),
+  }
+}
+
 function currentDeckKey(state: DecksState): string | undefined {
   if (state.activeDeck && state.decks[state.activeDeck]) return state.activeDeck
   const keys = Object.keys(state.decks)
@@ -800,6 +909,16 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   }
 
   if (deck.slides.length === 0) issues.push(blockerIssue("missing_slide_spec", "slides are missing", "Add the confirmed slide plan through revela-decks upsertSlides."))
+  if (deck.slides.length > 0) {
+    const planReview = currentDeckPlanReviewStatus(deck, options.narrativeHash)
+    if (!planReview.current) {
+      issues.push(blockerIssue(
+        "slide_plan_unconfirmed",
+        planReview.stale ? `Deck slide plan confirmation is stale: ${planReview.reason}` : `Deck slide plan is not confirmed: ${planReview.reason}`,
+        "Show the compiled deck plan with low-fidelity layout sketches to the user, then call revela-decks confirmDeckPlan only after explicit user confirmation.",
+      ))
+    }
+  }
   for (const slide of deck.slides) {
     const slideRef = { slideIndex: slide.index, slideTitle: slide.title }
     if (!slide.title.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} title is missing`, "Add a slide title to the slide spec.", slideRef))

package/lib/design/designs.ts

@@ -642,7 +642,6 @@ const UNIVERSAL_CLASSES = new Set([
   "slide-canvas",
   "visible",
   "reveal",
-  "editable",
   "page",
   "bg",
   "fg",
@@ -655,7 +654,7 @@ const UNIVERSAL_CLASSES = new Set([
  * CSS class prefixes that are always exempt from compliance checks.
  * Third-party libraries (icons, charts) generate classes with these prefixes.
  */
-export const DEFAULT_PREFIX_EXEMPTIONS: string[] = ["lucide-", "echarts-", "editable-"]
+export const DEFAULT_PREFIX_EXEMPTIONS: string[] = ["lucide-", "echarts-"]
 
 export interface DesignClassVocabulary {
   /** Complete set of allowed CSS class names. */

package/lib/edit/prompt.ts

@@ -72,14 +72,15 @@ Instructions:
 - If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
 - Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
 - Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through ${"`revela-decks`"} action ${"`upsertNarrative`"}, then reviewed/approved or explicitly overridden before updating the deck projection.
-- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, or deck HTML contract fixes may remain an artifact-level edit.
+- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, runtime JavaScript fixes, or deck HTML contract fixes may remain an artifact-level edit.
 - If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
 - Do not rewrite unrelated slides or broad sections of the deck.
 - Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.
-- Before patching or writing ${"`decks/*.html`"}, ensure ${"`DECKS.json`"} contains this deck and call ${"`revela-decks`"} with action ${"`review`"}. If ${"`DECKS.json`"} or the deck entry is missing, initialize/upsert the deck state with ${"`revela-decks`"} first. If readiness remains blocked, explain the blockers instead of forcing the edit.
-- Apply the edit to ${payload.file} only after readiness allows deck HTML changes.
-- Static design compliance is checked automatically after deck writes. If the tool result reports unknown classes, replace them with classes from the active design.
-- Do not run QA after the edit unless the user explicitly asks for diagnostics. PDF/PPTX export commands run hard-error pre-export QA automatically.
+- For targeted artifact-level edits, patch ${"`decks/*.html`"} directly. Do not call ${"`revela-decks`"} action ${"`review`"} as a precondition, and do not let ${"`writeReadiness`"}, ${"`planReview`"}, or ${"`slide_plan_unconfirmed`"} block the patch.
+- Do not patch or write ${"`DECKS.json`"} directly. If state must change, use the ${"`revela-decks`"} tool.
+- Apply the edit to ${payload.file} with the smallest targeted HTML patch that satisfies the comment.
+- Artifact QA runs automatically after deck writes/patches/edits. It checks deck HTML contract, design component compliance, exact 1920x1080 slide geometry, scrollbars, element overflow, text clipping, and claim/evidence content-density warnings.
+- If the tool result reports hard QA errors, fix them with the smallest targeted patch and let the post-write QA run again. Refine opens automatically only after hard errors pass; warnings such as thin claim/evidence substance do not block opening.
 - If the comment is ambiguous, ask one concise clarification question instead of guessing.`
 }

package/lib/edit/resolve-deck.ts

@@ -12,7 +12,7 @@ export interface EditableDeck {
 
 export function resolveEditableDeck(workspaceRoot: string, input = ""): EditableDeck {
   if (input.trim()) {
-    throw new Error("/revela edit no longer accepts a target. It opens the only HTML deck in decks/.")
+    throw new Error("/revela refine does not accept a target. It opens the active HTML deck or the only HTML deck in decks/.")
   }
 
   if (hasDecksState(workspaceRoot)) {

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,9 +23,10 @@ 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"
   /** 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"
@@ -75,6 +77,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 +177,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 +246,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 +622,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 +691,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.`,
   )

package/lib/qa/index.ts

@@ -1,9 +1,9 @@
 /**
  * lib/qa/index.ts
  *
- * Public entry point for hard-error slide QA.
- * Runs overflow measurement only. Static design compliance is handled by a
- * separate post-write/post-patch/post-edit hook.
+ * Public entry point for browser-rendered slide QA.
+ * Combined artifact QA, including contract and component compliance, lives in
+ * `lib/qa/artifact.ts`.
  */
 
 import { measureSlides } from "./measure"
@@ -18,12 +18,14 @@ export type { RunChecksOptions } from "./checks"
  * Run hard-error QA on `htmlFilePath`.
  *
  * 1. Opens the file in headless Chrome (puppeteer-core)
- * 2. Measures each .slide element's geometry + CSS class definitions
- * 3. Runs hard-error overflow checks only
+ * 2. Measures each .slide element's geometry, scroll state, text clipping,
+ *    content-density signals, and CSS class definitions
+ * 3. Runs browser QA checks for exact 1920x1080 slides, scrollbars, overflow,
+ *    text clipping, and claim/evidence density warnings
  * 4. Returns a structured QAReport
  *
  * The optional `vocabulary` argument is retained for backward compatibility;
- * compliance is intentionally not part of hard-error QA.
+ * design compliance is handled by combined artifact QA.
  *
  * Throws if the file cannot be opened or Chrome is not found.
  */