@cyber-dash-tech/revela 0.7.3 → 0.7.5

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-207%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-171%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
@@ -22,7 +22,7 @@ Enable it for the current session, assign a presentation task, and the agent can
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
 - uses workspace `DECKS.json` as machine-readable deck memory, slide spec, and prewrite readiness state
 - blocks premature writes to `decks/*.html` until the active deck is marked structurally ready
-- runs automatic layout QA whenever the agent writes `decks/*.html`
+- runs fast design compliance checks whenever the agent writes, patches, or edits `decks/*.html`
 - opens a visual comment editor for existing decks so users can Ctrl/Cmd-click elements and send precise edit requests back to OpenCode
 - exports finished decks to PDF and editable PPTX
 - switches designs and domains locally with zero LLM cost
@@ -302,23 +302,18 @@ This keeps final decks stable, offline-friendly, and independent from expiring r
 
 ## Layout QA And Compliance
 
-Every time the agent writes `decks/*.html`, Revela runs an automatic Puppeteer-based QA pass at `1920x1080`.
-The report is returned immediately so the agent can fix problems before moving on.
+Every time the agent writes, patches, or edits `decks/*.html`, Revela runs a fast static design compliance check.
+The manual `revela-qa` tool and PDF/PPTX export preflight also run a Puppeteer-based overflow check at `1920x1080`.
 
-Current QA dimensions:
+Current QA checks:
 
 | Dimension | What it checks |
 |---|---|
 | `overflow` | Elements extending outside the slide canvas |
-| `balance` | Sparse slides, centroid drift, and bottom-gap issues |
-| `symmetry` | Side-by-side column imbalance in height or density |
-| `rhythm` | Irregular vertical spacing between stacked siblings |
 | `compliance` | Unknown design classes and novel CSS rules outside the active design vocabulary |
 
 Each slide must declare `slide-qa="true"` or `slide-qa="false"`.
-
-- use `slide-qa="true"` for content-heavy slides that should undergo full QA
-- use `slide-qa="false"` for structural slides such as cover, TOC, quote, summary, or closing pages
+The current QA path keeps this as deck metadata; it does not enable additional subjective balance or spacing checks.
 
 You can also run QA manually with the `revela-qa` tool.
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-207%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-171%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
@@ -22,7 +22,7 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
 - 使用工作区 `DECKS.json` 保存机器可读的 deck 记忆、逐页规格和写入前 readiness 状态
 - 在 active deck 结构化 ready 前，阻止过早写入 `decks/*.html`
-- agent 每次写入 `decks/*.html` 时自动执行布局 QA
+- agent 每次写入、patch 或 edit `decks/*.html` 时自动执行快速 design compliance 检查
 - 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
 - design 和 domain 的切换都在本地完成，不消耗 LLM token
@@ -268,23 +268,18 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 
 ## 布局 QA 与合规检查
 
-每次 agent 写入 `decks/*.html` 时，Revela 都会自动在 `1920x1080` 下运行一轮基于 Puppeteer 的 QA。
-报告会立刻返回，便于 agent 继续修正。
+每次 agent 写入、patch 或 edit `decks/*.html` 时，Revela 都会自动运行快速静态 design compliance 检查。
+手动 `revela-qa` 工具以及 PDF/PPTX 导出前置检查会额外在 `1920x1080` 下运行基于 Puppeteer 的 overflow 检查。
 
-当前 QA 维度：
+当前 QA 检查：
 
 | 维度 | 检查内容 |
 |---|---|
 | `overflow` | 元素是否超出 slide canvas |
-| `balance` | 是否过稀、重心偏移、底部留白过大 |
-| `symmetry` | 并列列之间的高度或密度是否明显失衡 |
-| `rhythm` | 垂直堆叠元素之间的间距节奏是否不稳定 |
 | `compliance` | 是否使用了 active design 之外的 class 或新增 CSS 规则 |
 
 每张 slide 都必须声明 `slide-qa="true"` 或 `slide-qa="false"`。
-
-- `slide-qa="true"` 适用于内容型页面，执行完整 QA
-- `slide-qa="false"` 适用于封面、目录、引用、总结、结尾等结构型页面
+当前 QA 路径将其保留为 deck metadata，不再启用额外的主观平衡或间距检查。
 
 也可以手动调用 `revela-qa` 工具执行 QA。
 

package/lib/commands/pdf.ts

@@ -9,6 +9,7 @@
 
 import { resolve } from "path"
 import { exportToPdf } from "../pdf/export"
+import { assertExportQAPassed } from "../qa/export-gate"
 
 export async function handlePdf(
   filePath: string,
@@ -23,9 +24,11 @@ export async function handlePdf(
   }
 
   const abs = resolve(filePath)
-  await send(`Exporting \`${abs}\` to PDF...`)
+  await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
+    await assertExportQAPassed(abs)
+    await send(`Exporting \`${abs}\` to PDF...`)
     const result = await exportToPdf(filePath)
     const secs = (result.durationMs / 1000).toFixed(1)
     await send(

package/lib/commands/pptx.ts

@@ -9,6 +9,7 @@
 
 import { resolve } from "path"
 import { exportToPptx } from "../pptx/export"
+import { assertExportQAPassed } from "../qa/export-gate"
 
 function formatSecs(ms: number): string {
   return `${(ms / 1000).toFixed(1)}s`
@@ -27,9 +28,11 @@ export async function handlePptx(
   }
 
   const abs = resolve(filePath)
-  await send(`Exporting \`${abs}\` to PPTX...`)
+  await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
+    await assertExportQAPassed(abs)
+    await send(`Exporting \`${abs}\` to PPTX...`)
     let lastSlideUpdate = 0
     let longDeckThreshold: number | null = null
 

package/lib/edit/prompt.ts

@@ -76,6 +76,7 @@ Instructions:
 - 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.
-- After editing, run ${"`revela-qa`"} on ${payload.file} and fix any relevant regressions caused by the edit.
+- 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.
 - If the comment is ambiguous, ask one concise clarification question instead of guessing.`
 }

package/lib/edit/server.ts

@@ -94,16 +94,22 @@ async function handleRequest(req: Request): Promise<Response> {
 
 function handleDeckVersion(session: EditSession): Response {
   try {
-    const stat = statSync(session.absoluteFile)
+    const version = readDeckVersion(session)
     session.lastActiveAt = Date.now()
     scheduleIdleStop()
-    return jsonResponse({ ok: true, mtimeMs: stat.mtimeMs, size: stat.size })
+    return jsonResponse({ ok: true, ...version })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     return jsonResponse({ ok: false, error: message }, 404)
   }
 }
 
+function readDeckVersion(session: EditSession): { mtimeMs: number; size: number; version: string } {
+  const stat = statSync(session.absoluteFile)
+  const version = `${stat.mtimeMs}:${stat.size}`
+  return { mtimeMs: stat.mtimeMs, size: stat.size, version }
+}
+
 async function handleComment(req: Request, session: EditSession): Promise<Response> {
   let body: Partial<EditCommentPayload>
   try {
@@ -132,6 +138,7 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
     elements,
     comments,
   })
+  const deckVersion = readDeckVersion(session).version
 
   await session.client.session.prompt({
     path: { id: session.sessionID },
@@ -142,7 +149,7 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
 
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
-  return jsonResponse({ ok: true })
+  return jsonResponse({ ok: true, deckVersion })
 }
 
 function validateSession(token: string | null): { ok: true; value: EditSession } | { ok: false; response: Response } {
@@ -233,11 +240,13 @@ function renderEditorShell(token: string): string {
     .comment-thread { display: flex; flex-direction: column; gap: 10px; max-height: 30vh; overflow: auto; }
     .comment-bubble { border: 1px solid #374151; border-radius: 14px; padding: 10px 12px; background: #0f172a; color: #e5e7eb; font-size: 13px; line-height: 1.45; }
     .comment-bubble.sending { border-color: rgba(56,189,248,.5); background: rgba(14,116,144,.14); }
-    .comment-bubble.done { border-color: rgba(34,197,94,.55); background: rgba(22,101,52,.18); }
+    .comment-bubble.applied { border-color: rgba(34,197,94,.55); background: rgba(22,101,52,.18); }
+    .comment-bubble.stale { border-color: rgba(251,191,36,.6); background: rgba(120,53,15,.2); }
     .comment-bubble.failed { border-color: rgba(248,113,113,.65); background: rgba(127,29,29,.2); }
     .comment-bubble-text { white-space: pre-wrap; overflow-wrap: anywhere; }
     .comment-bubble-state { margin-top: 8px; color: #93c5fd; font-size: 12px; font-weight: 700; }
-    .comment-bubble.done .comment-bubble-state { color: #86efac; }
+    .comment-bubble.applied .comment-bubble-state { color: #86efac; }
+    .comment-bubble.stale .comment-bubble-state { color: #fcd34d; }
     .comment-bubble.failed .comment-bubble-state { color: #fca5a5; }
     button { width: 100%; padding: 12px 14px; border: 0; border-radius: 12px; background: #38bdf8; color: #04111d; font-weight: 700; cursor: pointer; }
     button:disabled { cursor: not-allowed; opacity: .5; }
@@ -265,6 +274,7 @@ function renderEditorShell(token: string): string {
   <script>
     (() => {
       const token = ${encodedToken};
+      const COMMENT_STALE_MS = 60000;
       const state = {
         references: [],
         pendingComments: [],
@@ -374,7 +384,6 @@ function renderEditorShell(token: string): string {
           updateSendState();
           if (state.pendingRefreshMessage) {
             state.pendingRefreshMessage = false;
-            markPendingCommentsDone();
             setStatus('Deck updated. Preview refreshed. Element references were cleared.');
           } else {
             setStatus(slides.length > 0 ? 'Editor ready. Found ' + slides.length + ' slides. Ctrl/Cmd + click to reference elements.' : 'Editor ready, but no .slide elements were found. Ctrl/Cmd + click to reference elements.');
@@ -394,13 +403,18 @@ function renderEditorShell(token: string): string {
           const res = await fetch('/api/deck-version?token=' + encodeURIComponent(token), { cache: 'no-store' });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to check deck version');
-          const nextVersion = String(body.mtimeMs) + ':' + String(body.size);
+          const nextVersion = body.version || (String(body.mtimeMs) + ':' + String(body.size));
           if (!state.deckVersion) {
             state.deckVersion = nextVersion;
+            markStaleComments();
+            return;
+          }
+          if (state.deckVersion === nextVersion) {
+            markStaleComments();
             return;
           }
-          if (state.deckVersion === nextVersion) return;
           state.deckVersion = nextVersion;
+          markCommentsAppliedForVersion(nextVersion);
           refreshDeckPreview(body.mtimeMs);
         } catch (error) {
           reportError(error);
@@ -482,7 +496,7 @@ function renderEditorShell(token: string): string {
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send comment');
-          updatePendingCommentStatus(commentId, 'sent');
+          updatePendingCommentStatus(commentId, 'sent', { baseDeckVersion: body.deckVersion || state.deckVersion });
           setStatus('Comment sent. Waiting for deck update...');
           updateSendState();
         } catch (error) {
@@ -555,29 +569,53 @@ function renderEditorShell(token: string): string {
           text,
           elements,
           status,
+          createdAt: Date.now(),
+          baseDeckVersion: state.deckVersion,
+          appliedVersion: null,
         });
         renderCommentThread();
         return id;
       }
 
-      function updatePendingCommentStatus(id, status) {
+      function updatePendingCommentStatus(id, status, updates) {
         const comment = state.pendingComments.find((item) => item.id === id);
         if (!comment) return;
+        if (comment.status === 'applied' && status !== 'failed') return;
         comment.status = status;
+        if (updates) Object.assign(comment, updates);
         renderCommentThread();
       }
 
-      function markPendingCommentsDone() {
+      function markCommentsAppliedForVersion(version) {
         let changed = false;
         state.pendingComments.forEach((comment) => {
-          if (comment.status === 'sent' || comment.status === 'sending') {
-            comment.status = 'done';
+          if ((comment.status === 'sent' || comment.status === 'sending' || comment.status === 'stale') && comment.baseDeckVersion !== version) {
+            comment.status = 'applied';
+            comment.appliedVersion = version;
             changed = true;
           }
         });
         if (changed) renderCommentThread();
       }
 
+      function markStaleComments() {
+        const now = Date.now();
+        let changed = false;
+        const hasWaiting = state.pendingComments.some((comment) => {
+          if (comment.status !== 'sent' && comment.status !== 'sending') return false;
+          if (now - comment.createdAt < COMMENT_STALE_MS) return true;
+          comment.status = 'stale';
+          changed = true;
+          return true;
+        });
+        if (changed) {
+          renderCommentThread();
+          setStatus('Still waiting for deck file update. If OpenCode already finished, refresh the editor.');
+        } else if (hasWaiting) {
+          setStatus('Comment sent. Waiting for deck update...');
+        }
+      }
+
       function renderCommentThread() {
         els.commentThread.textContent = '';
         state.pendingComments.forEach((comment) => {
@@ -599,7 +637,8 @@ function renderEditorShell(token: string): string {
       }
 
       function commentStatusLabel(status) {
-        if (status === 'done') return '✅ Applied';
+        if (status === 'applied') return '✅ Applied';
+        if (status === 'stale') return 'Still waiting for deck file update';
         if (status === 'failed') return 'Failed to send';
         if (status === 'sending') return 'Sending to OpenCode...';
         return '⏳ Sent to OpenCode';

package/lib/qa/checks.ts

@@ -1,8 +1,8 @@
 /**
  * lib/qa/checks.ts
  *
- * Geometry-based layout quality checks — four orthogonal visual dimensions,
- * plus a design-compliance dimension that verifies CSS class usage.
+ * Geometry-based layout quality checks. The active default path only checks
+ * overflow; softer 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)
@@ -523,106 +523,13 @@ function checkRhythm(metrics: SlideMetrics): LayoutIssue[] {
   return issues
 }
 
-// ── Compliance checks ─────────────────────────────────────────────────────────
-
-/**
- * Check whether a class name is exempt from compliance checking.
- * Returns true if the class matches any of the given prefix exemptions.
- */
-function isExemptClass(cls: string, prefixExemptions: string[]): boolean {
-  return prefixExemptions.some((prefix) => cls.startsWith(prefix))
-}
-
-/**
- * Dimension 5a: unknown_class
- *
- * Walk the element tree and flag any CSS class not in `allowedClasses`
- * and not matching any `prefixExemptions`. Each unique unknown class name
- * is reported at most once per slide (de-duplicated).
- */
-function checkCompliance(
-  slide: SlideMetrics,
-  allowedClasses: Set<string>,
-  prefixExemptions: string[],
-): LayoutIssue[] {
-  const issues: LayoutIssue[] = []
-  const reported = new Set<string>()
-
-  function walk(el: ElementInfo): void {
-    for (const cls of el.classList) {
-      if (!cls) continue
-      if (reported.has(cls)) continue
-      if (allowedClasses.has(cls)) continue
-      if (isExemptClass(cls, prefixExemptions)) continue
-
-      reported.add(cls)
-      issues.push({
-        type: "compliance",
-        sub: "unknown_class",
-        severity: "warning",
-        detail: `Element \`${el.selector}\` uses CSS class \`${cls}\` which is not defined in the active design. Replace it with a class from the Component Index or Layout Index.`,
-        data: { class: cls, selector: el.selector },
-      })
-    }
-    for (const child of el.children) {
-      walk(child)
-    }
-  }
-
-  for (const el of slide.elements) {
-    walk(el)
-  }
-
-  return issues
-}
-
-/**
- * Dimension 5b: novel_css_rule
- *
- * Check whether the <style> block defines CSS classes not in `allowedClasses`.
- * Returns issues as a flat list (caller attaches them to slide 0).
- */
-function checkNovelCssRules(
-  cssDefinedClasses: string[],
-  allowedClasses: Set<string>,
-  prefixExemptions: string[],
-): LayoutIssue[] {
-  const issues: LayoutIssue[] = []
-  const reported = new Set<string>()
-
-  for (const cls of cssDefinedClasses) {
-    if (!cls) continue
-    if (reported.has(cls)) continue
-    if (allowedClasses.has(cls)) continue
-    if (isExemptClass(cls, prefixExemptions)) continue
-
-    reported.add(cls)
-    issues.push({
-      type: "compliance",
-      sub: "novel_css_rule",
-      severity: "warning",
-      detail: `<style> defines CSS class \`.${cls}\` which is not part of the active design. Remove this custom rule and use the design's existing component styles. For minor adjustments, use inline \`style=""\` instead.`,
-      data: { class: cls },
-    })
-  }
-
-  return issues
-}
-
 // ── Main export ───────────────────────────────────────────────────────────────
 
 /**
- * Options for runChecks(). All fields are optional — omitting them disables
- * the corresponding checks (backward compatible).
+ * Options for future geometry checks. The current default path only checks
+ * overflow, regardless of options.
  */
-export interface RunChecksOptions {
-  /** Allowed CSS class vocabulary from the active design (enables compliance checks). */
-  allowedClasses?: Set<string>
-  /** Class name prefixes exempt from compliance checks (e.g. "lucide-", "echarts-"). */
-  prefixExemptions?: string[]
-  /** CSS class names defined in <style> blocks (enables novel_css_rule check). */
-  cssDefinedClasses?: string[]
-}
+export interface RunChecksOptions {}
 
 /**
  * Run all dimension checks on a set of slide metrics and produce a QA report.
@@ -630,31 +537,12 @@ export interface RunChecksOptions {
 export function runChecks(
   filePath: string,
   allMetrics: SlideMetrics[],
-  options?: RunChecksOptions,
+  _options?: RunChecksOptions,
 ): QAReport {
   const slides: SlideReport[] = []
-  const { allowedClasses, prefixExemptions = [], cssDefinedClasses } = options ?? {}
-
-  // novel_css_rule issues are global (not per-slide); attach to slide 0.
-  const novelCssIssues: LayoutIssue[] =
-    allowedClasses && cssDefinedClasses
-      ? checkNovelCssRules(cssDefinedClasses, allowedClasses, prefixExemptions)
-      : []
 
   for (const metrics of allMetrics) {
-    const complianceIssues: LayoutIssue[] =
-      allowedClasses
-        ? checkCompliance(metrics, allowedClasses, prefixExemptions)
-        : []
-
-    const issues: LayoutIssue[] = [
-      ...checkOverflow(metrics),
-      ...checkBalance(metrics),
-      ...checkRhythm(metrics),
-      ...complianceIssues,
-      // Attach novel_css_rule issues to slide 0 only
-      ...(metrics.index === 0 ? novelCssIssues : []),
-    ]
+    const issues: LayoutIssue[] = [...checkOverflow(metrics)]
 
     slides.push({ index: metrics.index, title: metrics.title, issues })
   }
@@ -709,12 +597,8 @@ export function formatReport(report: QAReport): string {
   lines.push(
     `### Action Required`,
     ``,
-    `Please fix the above layout issues in the HTML file. For each issue type:`,
+    `Please fix the above hard-error issues in the HTML file. For each issue type:`,
     `- **overflow**: reduce font size, padding, or content amount for the affected element.`,
-    `- **balance/centroid_offset**: redistribute content so the visual weight is centred — avoid concentrating everything in one corner or side.`,
-    `- **balance/bottom_gap**: expand content to fill the slide, use \`flex: 1\` on containers, add more content blocks, or reduce top padding.`,
-    `- **balance/sparse**: add more content components, increase font sizes, or use a layout with fewer columns.`,
-    `- **rhythm/gap_variance**: use consistent \`gap\` or \`margin\` values between stacked elements instead of mixing sizes.`,
     `- **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/compliance.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from "fs"
+import type { DesignClassVocabulary } from "../design/designs"
+import type { LayoutIssue, QAReport, SlideReport } from "./checks"
+
+interface ClassUse {
+  className: string
+  selector: string
+}
+
+interface SlideClassUses {
+  title: string
+  uses: ClassUse[]
+}
+
+function isExemptClass(cls: string, prefixExemptions: string[]): boolean {
+  return prefixExemptions.some((prefix) => cls.startsWith(prefix))
+}
+
+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 extractClassUses(html: string): ClassUse[] {
+  const uses: ClassUse[] = []
+  const classAttrRe = /class\s*=\s*(["'])([\s\S]*?)\1/gi
+  let match: RegExpExecArray | null
+
+  while ((match = classAttrRe.exec(html)) !== null) {
+    const raw = match[2] || ""
+    for (const cls of raw.split(/\s+/).map((v) => v.trim()).filter(Boolean)) {
+      uses.push({ className: cls, selector: `.${cls}` })
+    }
+  }
+
+  return uses
+}
+
+function extractSlideClassUses(html: string): SlideClassUses[] {
+  const slides: SlideClassUses[] = []
+  const sectionRe = /<section\b[\s\S]*?<\/section>/gi
+  let match: RegExpExecArray | null
+  let index = 0
+
+  while ((match = sectionRe.exec(html)) !== null) {
+    const chunk = match[0]
+    slides.push({ title: extractTitle(chunk, index), uses: extractClassUses(chunk) })
+    index++
+  }
+
+  if (slides.length === 0) {
+    slides.push({ title: extractTitle(html, 0), uses: extractClassUses(html) })
+  }
+
+  return slides
+}
+
+function extractCssDefinedClasses(html: string): string[] {
+  const classes = new Set<string>()
+  const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi
+  const classRe = /\.([a-zA-Z_][\w-]*)/g
+  let styleMatch: RegExpExecArray | null
+
+  while ((styleMatch = styleRe.exec(html)) !== null) {
+    classRe.lastIndex = 0
+    let classMatch: RegExpExecArray | null
+    while ((classMatch = classRe.exec(styleMatch[1])) !== null) {
+      classes.add(classMatch[1])
+    }
+  }
+
+  return [...classes]
+}
+
+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 slides passed layout QA."
+    : `Found ${totalIssues} issue(s): ${errorCount} error(s), ${warningCount} warning(s) across ${slides.filter((s) => s.issues.length > 0).length} slide(s).`
+
+  return { file: filePath, slides, totalIssues, errorCount, warningCount, summary }
+}
+
+export function runComplianceQA(htmlFilePath: string, vocabulary?: DesignClassVocabulary): QAReport {
+  const html = readFileSync(htmlFilePath, "utf-8")
+  const slideUses = extractSlideClassUses(html)
+  const allowedClasses = vocabulary?.classes
+  const prefixExemptions = vocabulary?.prefixExemptions ?? []
+
+  const slides: SlideReport[] = slideUses.map((slide, index) => {
+    const issues: LayoutIssue[] = []
+    const reported = new Set<string>()
+
+    if (allowedClasses) {
+      for (const use of slide.uses) {
+        if (reported.has(use.className)) continue
+        if (allowedClasses.has(use.className)) continue
+        if (isExemptClass(use.className, prefixExemptions)) continue
+
+        reported.add(use.className)
+        issues.push({
+          type: "compliance",
+          sub: "unknown_class",
+          severity: "warning",
+          detail: `HTML uses CSS class \`${use.className}\` which is not defined in the active design. Replace it with a class from the Component Index or Layout Index.`,
+          data: { class: use.className, selector: use.selector },
+        })
+      }
+    }
+
+    return { index, title: slide.title, issues }
+  })
+
+  if (allowedClasses && slides.length > 0) {
+    const first = slides[0]
+    const reported = new Set<string>()
+    for (const cls of extractCssDefinedClasses(html)) {
+      if (reported.has(cls)) continue
+      if (allowedClasses.has(cls)) continue
+      if (isExemptClass(cls, prefixExemptions)) continue
+
+      reported.add(cls)
+      first.issues.push({
+        type: "compliance",
+        sub: "novel_css_rule",
+        severity: "warning",
+        detail: `<style> defines CSS class \`.${cls}\` which is not part of the active design. Remove this custom rule and use the design's existing component styles. For minor adjustments, use inline \`style=""\` instead.`,
+        data: { class: cls },
+      })
+    }
+  }
+
+  return summarize(htmlFilePath, slides)
+}

package/lib/qa/export-gate.ts

@@ -0,0 +1,11 @@
+import { formatReport, runQA } from "./index"
+
+export async function assertExportQAPassed(filePath: string): Promise<void> {
+  const report = await runQA(filePath)
+  if (report.totalIssues === 0) return
+
+  throw new Error(
+    "Export blocked because pre-export QA found issues. Fix them and export again.\n\n" +
+    formatReport(report)
+  )
+}

package/lib/qa/index.ts

@@ -1,44 +1,38 @@
 /**
  * lib/qa/index.ts
  *
- * Public entry point for the slide layout QA system.
- * Combines measurement (Puppeteer) + checks (geometry rules) into one call.
+ * 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.
  */
 
 import { measureSlides } from "./measure"
 import { runChecks, formatReport } from "./checks"
-import type { QAReport, RunChecksOptions } from "./checks"
+import type { QAReport } from "./checks"
 import type { DesignClassVocabulary } from "../design/designs"
 
 export type { QAReport, SlideReport, LayoutIssue, IssueSeverity } from "./checks"
 export type { RunChecksOptions } from "./checks"
 
 /**
- * Run a full layout QA pass on `htmlFilePath`.
+ * 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 all checks (overflow, balance, symmetry, rhythm, compliance)
+ * 3. Runs hard-error overflow checks only
  * 4. Returns a structured QAReport
  *
- * Pass `vocabulary` (from `extractDesignClasses()`) to enable compliance checks.
- * Omit it to run geometry-only checks (backward compatible).
+ * The optional `vocabulary` argument is retained for backward compatibility;
+ * compliance is intentionally not part of hard-error QA.
  *
  * Throws if the file cannot be opened or Chrome is not found.
  */
 export async function runQA(
   htmlFilePath: string,
-  vocabulary?: DesignClassVocabulary,
+  _vocabulary?: DesignClassVocabulary,
 ): Promise<QAReport> {
   const result = await measureSlides(htmlFilePath)
-  const options: RunChecksOptions | undefined = vocabulary
-    ? {
-        allowedClasses: vocabulary.classes,
-        prefixExemptions: vocabulary.prefixExemptions,
-        cssDefinedClasses: result.cssDefinedClasses,
-      }
-    : undefined
-  return runChecks(htmlFilePath, result.slides, options)
+  return runChecks(htmlFilePath, result.slides)
 }
 
 /**
@@ -54,3 +48,4 @@ export async function runQAFormatted(
 }
 
 export { formatReport } from "./checks"
+export { runComplianceQA } from "./compliance"

package/lib/qa/measure.ts

@@ -57,7 +57,7 @@ export interface SlideMetrics {
   /** slide title extracted from the first h1/h2 inside the slide */
   title: string
   /**
-   * Whether this slide should be included in layout QA checks.
+   * Whether this slide is marked as QA-relevant deck metadata.
    * Read from the `slide-qa` attribute on `<section class="slide">`.
    * Defaults to `false` when the attribute is absent.
    * Content-heavy layouts set `slide-qa="true"`; structural/sparse slides omit or use `"false"`.
@@ -266,7 +266,7 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
           const slide = document.querySelectorAll(".slide")[slideIdx]
           if (!slide) return null
 
-          // Read the QA flag — true means this slide gets balance/rhythm checks
+          // Read the QA flag for deck metadata; default checks do not branch on it.
           const slideQa = (slide as HTMLElement).getAttribute("slide-qa") === "true"
 
           const canvas = slide.querySelector(".slide-canvas") as HTMLElement | null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -11,7 +11,7 @@
  * 5. experimental.chat.system.transform: inject three-layer prompt when enabled
  * 6. chat.message: intercept @-referenced / pasted binary files → extract text → replace FilePart with TextPart
  * 7. tool.execute.before: intercept read on DOCX/PPTX/XLSX → preRead()
- * 8. tool.execute.after: intercept read on PDF/images → postRead()
+ * 8. tool.execute.after: intercept read on PDF/images → postRead(); run static compliance after deck writes/patches/edits
  */
 
 import type { Plugin } from "@opencode-ai/plugin"
@@ -85,7 +85,7 @@ import pdfTool from "./tools/pdf"
 import pptxTool from "./tools/pptx"
 import createEditTool from "./tools/edit"
 import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research-prompt"
-import { runQA, formatReport } from "./lib/qa"
+import { formatReport, runComplianceQA } from "./lib/qa"
 import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
 
@@ -97,6 +97,20 @@ const INTERNAL_AGENT_SIGNATURES = [
   "Summarize what was done in this conversation",
 ]
 
+function appendToolResult(output: any, text: string): void {
+  if (typeof output.output === "string") {
+    output.output = (output.output ? output.output + "\n\n" : "") + text
+    return
+  }
+
+  const existing = output.result ?? ""
+  output.result = (existing ? existing + "\n\n" : "") + text
+}
+
+function extractEditFilePath(args: any): string {
+  return args?.filePath ?? args?.file_path ?? args?.path ?? args?.file ?? ""
+}
+
 // ── Helpers ────────────────────────────────────────────────────────────────
 
 /**
@@ -129,6 +143,33 @@ const server: Plugin = (async (pluginCtx) => {
   const blockedDeckWrites = new Map<string, string>()
   const blockedDeckPatches = new Map<string, string>()
 
+  async function appendComplianceReport(filePath: string, output: any): Promise<void> {
+    if (!isDeckHtmlPath(filePath)) return
+
+    try {
+      let vocabulary
+      try {
+        vocabulary = extractDesignClasses()
+      } catch {
+        // Design may not be installed or may have no markers — skip compliance.
+      }
+
+      const report = runComplianceQA(filePath, vocabulary)
+      if (report.totalIssues === 0) return
+
+      appendToolResult(
+        output,
+        "---\n\n**[revela design compliance]** Static check completed:\n\n" +
+        formatReport(report)
+      )
+    } catch (e) {
+      childLog("compliance").warn("static compliance failed", {
+        filePath,
+        error: e instanceof Error ? e.message : String(e),
+      })
+    }
+  }
+
   // ── Startup: seed + build initial prompt ────────────────────────────────
   try {
     seedBuiltinDesigns()
@@ -577,7 +618,8 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
     // Handles PDF and images — read tool succeeds with base64 attachment.
     // PDF: extract text, remove base64. Images: jimp compress.
     //
-    // Also handles: auto layout QA after writing decks/*.html
+    // Also reports writes/patches blocked by the DECKS.json prewrite gate and
+    // runs lightweight static design compliance after successful deck changes.
     "tool.execute.after": async (input, output) => {
       if (!ctx.enabled) return
 
@@ -594,61 +636,47 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
         return
       }
 
-      // ── Auto layout QA after writing decks/*.html ─────────────────────
+      // ── Report blocked deck writes and run static compliance ──────────
       if (input.tool === "write") {
         const filePath: string = input.args?.filePath ?? ""
         const blockedReason = blockedDeckWrites.get(filePath)
         if (blockedReason) {
           blockedDeckWrites.delete(filePath)
-          const existing = (output as any).result ?? ""
-          ;(output as any).result =
-            (existing ? existing + "\n\n" : "") +
+          appendToolResult(
+            output,
             "---\n\n**[revela state gate]** Write was blocked.\n\n" +
             `${blockedReason}\n\n` +
             "Use the `revela-decks` tool or complete the DECKS.json review workflow instead."
+          )
           return
         }
-        // Only trigger for HTML files inside a decks/ directory
-        if (!isDeckHtmlPath(filePath)) return
-
-        try {
-          // Extract design's allowed class vocabulary for compliance checking
-          let vocabulary
-          try {
-            vocabulary = extractDesignClasses()
-          } catch {
-            // Design may not be installed or may have no markers — skip compliance
-          }
-          const report = await runQA(filePath, vocabulary)
-          // Only append QA report to tool output if there are issues
-          if (report.totalIssues > 0) {
-            const formatted = formatReport(report)
-            // Append to the write tool's output so the LLM sees it immediately
-            const existing = (output as any).result ?? ""
-            ;(output as any).result =
-              (existing ? existing + "\n\n" : "") +
-              "---\n\n**[revela layout QA]** Auto-check completed:\n\n" +
-              formatted
-          }
-        } catch (e) {
-          childLog("qa").warn("auto QA failed", {
-            filePath,
-            error: e instanceof Error ? e.message : String(e),
-          })
-          // Don't surface errors to the LLM — fail silently
-        }
+        await appendComplianceReport(filePath, output)
         return
       }
 
       if (input.tool === "apply_patch" && blockedDeckPatches.size > 0) {
         const [blockedPath, blockedReason] = blockedDeckPatches.entries().next().value ?? []
         if (blockedPath) blockedDeckPatches.delete(blockedPath)
-        const existing = (output as any).result ?? ""
-        ;(output as any).result =
-          (existing ? existing + "\n\n" : "") +
+        appendToolResult(
+          output,
           "---\n\n**[revela prewrite gate]** Deck HTML patch was blocked.\n\n" +
           `${blockedReason}\n\n` +
           "Run `/revela review` or complete the same DECKS.json review workflow before patching the deck."
+        )
+        return
+      }
+
+      if (input.tool === "apply_patch") {
+        const patchText = extractPatchTextArg(input.args as Record<string, unknown>)
+        const targets = patchText ? extractDeckHtmlTargetsFromPatch(patchText) : []
+        for (const target of targets) {
+          await appendComplianceReport(target, output)
+        }
+        return
+      }
+
+      if (input.tool === "edit") {
+        await appendComplianceReport(extractEditFilePath(input.args), output)
         return
       }
     },

package/skill/SKILL.md

@@ -232,8 +232,8 @@ layouts (cover, TOC, closing, quote, summary, etc.). When unsure, use `"false"`.
 
 Example: `<section class="slide" slide-qa="true" data-index="0">`
 
-The layout QA system uses this to skip fill-ratio and spacing checks on slides
-that are intentionally sparse.
+The export QA path treats this as deck metadata. It is consumed when PDF/PPTX
+export runs preflight checks.
 
 ### Domain Context
 
@@ -323,7 +323,7 @@ After generating, briefly tell the user:
 - How to navigate (arrow keys / swipe)
 - One line invitation to request changes
 
-Then use `revela-decks` to record written/QA status when available. Preserve
+Then use `revela-decks` to record written status when available. Preserve
 stable decisions in deck memory when useful.
 
 For change requests: re-generate the **entire** file (don't patch). Apply the
@@ -382,11 +382,14 @@ exclusively for fine-tuning spacing and sizing (`margin`, `padding`, `gap`,
 component — **NEVER adapt the component structure to fit content. NEVER create
 a new component because the existing ones "don't quite fit".**
 
-The QA system will flag any unrecognised CSS class as a **compliance error**.
-If the QA report contains compliance issues after you write the file, you MUST
-fix them immediately — remove the offending classes and replace them with the
-closest component from the Component Index. Do not move on until all compliance
-errors are resolved.
+The automatic static compliance check will flag any unrecognised CSS class after
+deck HTML writes or patches. If the tool result reports compliance issues, fix
+them immediately by removing the offending classes and replacing them with the
+closest component from the Component Index.
+
+Do not run `revela-qa` after writing or editing HTML unless the user explicitly
+asks for diagnostics. PDF/PPTX export commands run hard-error pre-export QA
+automatically and will report overflow issues that must be fixed before exporting.
 
 ### Inline Editing
 

package/tools/decks.ts

@@ -57,7 +57,7 @@ export default tool({
       title: tool.schema.string().describe("Slide title."),
       purpose: tool.schema.string().optional().describe("Narrative purpose of this slide."),
       layout: tool.schema.string().describe("Design layout name."),
-      qa: tool.schema.boolean().optional().describe("Whether the layout requires full QA."),
+      qa: tool.schema.boolean().optional().describe("Whether the slide is marked QA-relevant deck metadata."),
       components: tool.schema.array(tool.schema.string()).describe("Design components used by this slide."),
       content: tool.schema.object({
         headline: tool.schema.string().optional(),

package/tools/pdf.ts

@@ -8,11 +8,12 @@ import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
 import { exportToPdf } from "../lib/pdf/export"
+import { assertExportQAPassed } from "../lib/qa/export-gate"
 
 export default tool({
   description:
     "Export a Revela-generated HTML slide deck to PDF. " +
-    "Use this after the deck HTML has been written and layout QA has passed. " +
+    "Runs pre-export QA before writing the PDF. " +
     "Output is written beside the input file with the same basename and a .pdf extension.",
   args: {
     file: tool.schema
@@ -34,6 +35,7 @@ export default tool({
     }
 
     try {
+      await assertExportQAPassed(filePath)
       const result = await exportToPdf(filePath)
       return JSON.stringify({ ok: true, ...result }, null, 2)
     } catch (e: any) {

package/tools/pptx.ts

@@ -8,11 +8,12 @@ import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
 import { exportToPptx } from "../lib/pptx/export"
+import { assertExportQAPassed } from "../lib/qa/export-gate"
 
 export default tool({
   description:
     "Export a Revela-generated HTML slide deck to editable PPTX. " +
-    "Use this after the deck HTML has been written and layout QA has passed. " +
+    "Runs pre-export QA before writing the PPTX. " +
     "Output is written beside the input file with the same basename and a .pptx extension.",
   args: {
     file: tool.schema
@@ -36,6 +37,7 @@ export default tool({
     const progress: string[] = []
 
     try {
+      await assertExportQAPassed(filePath)
       const result = await exportToPptx(filePath, {
         onProgress: (event) => {
           progress.push(event.message)

package/tools/qa.ts

@@ -1,27 +1,23 @@
 /**
  * tools/qa.ts
  *
- * revela-qa — Layout quality assurance tool for generated slide HTML files.
+ * revela-qa — Hard-error quality assurance for generated slide HTML files.
  *
- * Exposed to the LLM so it can run layout checks after writing a slides file.
- * Also called automatically by the tool.execute.after hook in plugin.ts
- * when the LLM writes a file matching decks/*.html.
+ * Exposed as a manual diagnostic tool. Export commands run pre-export QA automatically.
  */
 
 import { tool } from "@opencode-ai/plugin"
 import { resolve } from "path"
 import { existsSync } from "fs"
 import { runQA, formatReport } from "../lib/qa"
-import { extractDesignClasses } from "../lib/design/designs"
 
 export default tool({
   description:
-    "Run layout quality checks on a generated slide HTML file. " +
+    "Run hard-error checks on a generated slide HTML file. " +
     "Opens the file in a headless browser and measures actual rendered geometry. " +
-    "Checks for: canvas underfill (too much empty space), bottom whitespace, " +
-    "left-right column asymmetry, element overflow, and card height variance. " +
+    "Checks for element overflow. " +
     "Returns a structured report with specific issues and fix instructions. " +
-    "Call this after writing or editing any decks/*.html file to verify layout quality.",
+    "Normally PDF/PPTX export commands run this automatically; call it directly only for explicit diagnostics.",
   args: {
     file: tool.schema
       .string()
@@ -43,14 +39,7 @@ export default tool({
     }
 
     try {
-      // Extract design's allowed class vocabulary for compliance checking
-      let vocabulary
-      try {
-        vocabulary = extractDesignClasses()
-      } catch {
-        // Design may not be installed or may have no markers — skip compliance
-      }
-      const report = await runQA(filePath, vocabulary)
+      const report = await runQA(filePath)
       const formatted = formatReport(report)
 
       // Prepend a compact JSON summary for programmatic use if needed
@@ -63,7 +52,7 @@ export default tool({
 
       return `<!-- QA Summary: ${jsonSummary} -->\n\n${formatted}`
     } catch (err: any) {
-      return `Error running layout QA: ${err?.message ?? String(err)}\n\nMake sure Chrome is installed at /Applications/Google Chrome.app`
+      return `Error running hard-error QA: ${err?.message ?? String(err)}\n\nMake sure Chrome is installed at /Applications/Google Chrome.app`
     }
   },
 })