@cyber-dash-tech/revela 0.15.0 → 0.15.2

package/lib/qa/index.ts

@@ -1,15 +1,17 @@
 /**
  * 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"
 import { runChecks, formatReport } from "./checks"
-import type { QAReport } from "./checks"
+import type { LayoutIssue, QAReport } from "./checks"
 import type { DesignClassVocabulary } from "../design/designs"
+import { existsSync, readFileSync } from "fs"
+import { dirname, resolve } from "path"
 
 export type { QAReport, SlideReport, LayoutIssue, IssueSeverity } from "./checks"
 export type { RunChecksOptions } from "./checks"
@@ -18,12 +20,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.
  */
@@ -32,7 +36,76 @@ export async function runQA(
   _vocabulary?: DesignClassVocabulary,
 ): Promise<QAReport> {
   const result = await measureSlides(htmlFilePath)
-  return runChecks(htmlFilePath, result.slides)
+  const report = runChecks(htmlFilePath, result.slides)
+  return withAssetChecks(report, htmlFilePath)
+}
+
+function withAssetChecks(report: QAReport, htmlFilePath: string): QAReport {
+  const issues = scanAssetRefs(htmlFilePath)
+  if (!issues.length) return report
+  const slides = [...report.slides]
+  const first = slides[0] ?? { index: 1, title: "Deck", issues: [] }
+  slides[0] = { ...first, issues: [...first.issues, ...issues] }
+  const errorCount = report.errorCount + issues.filter((issue) => issue.severity === "error").length
+  const warningCount = report.warningCount + issues.filter((issue) => issue.severity === "warning").length
+  return {
+    ...report,
+    slides,
+    totalIssues: report.totalIssues + issues.length,
+    errorCount,
+    warningCount,
+    summary: errorCount === 0
+      ? `QA passed with ${warningCount} warning${warningCount === 1 ? "" : "s"}.`
+      : `QA failed with ${errorCount} error${errorCount === 1 ? "" : "s"} and ${warningCount} warning${warningCount === 1 ? "" : "s"}.`,
+  }
+}
+
+function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
+  let html = ""
+  try {
+    html = readFileSync(htmlFilePath, "utf-8")
+  } catch {
+    return []
+  }
+  const refs = new Set<string>()
+  const attrPattern = /\b(?:src|href|poster)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi
+  let match: RegExpExecArray | null
+  while ((match = attrPattern.exec(html))) refs.add(match[1] ?? match[2] ?? match[3] ?? "")
+  const cssPattern = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^\s)]+))\s*\)/gi
+  while ((match = cssPattern.exec(html))) refs.add(match[1] ?? match[2] ?? match[3] ?? "")
+
+  const issues: LayoutIssue[] = []
+  for (const raw of refs) {
+    const ref = raw.trim()
+    if (!ref || ref.startsWith("data:") || ref.startsWith("#") || ref.startsWith("mailto:") || ref.startsWith("tel:")) continue
+    if (/^https?:\/\//i.test(ref) || ref.startsWith("//")) {
+      issues.push({ type: "asset", sub: "remote_url", severity: "error", detail: `Deck HTML references remote asset URL \`${ref}\`. Save network images to workspace assets and reference the local file instead.` })
+      continue
+    }
+    if (ref.includes("/__revela_asset")) {
+      issues.push({ type: "asset", sub: "refine_proxy", severity: "error", detail: `Deck HTML references Refine proxy URL \`${ref}\`. Use the saved workspace asset path instead.` })
+      continue
+    }
+    if (!looksLikeImageRef(ref)) continue
+    const pathOnly = safeDecode(ref.split(/[?#]/)[0])
+    const resolved = resolve(dirname(htmlFilePath), pathOnly)
+    if (!existsSync(resolved)) {
+      issues.push({ type: "asset", sub: "missing_file", severity: "error", detail: `Deck HTML references missing image asset \`${ref}\`. Use a path relative to the deck HTML file or save the asset into workspace assets first.` })
+    }
+  }
+  return issues
+}
+
+function looksLikeImageRef(ref: string): boolean {
+  return /\.(?:png|jpe?g|webp|gif|svg)(?:[?#].*)?$/i.test(ref)
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
 }
 
 /**

package/lib/qa/measure.ts

@@ -49,6 +49,19 @@ export interface ElementInfo {
   children: ElementInfo[]
   /** all CSS class names on this element */
   classList: string[]
+  /** visible text excerpt for text overflow diagnostics */
+  text?: string
+  /** whether text content is clipped inside this element */
+  textOverflow?: boolean
+}
+
+export interface SlideContentStats {
+  /** Non-title effective text points: English words + CJK characters. */
+  bodyTextPoints: number
+  /** Recognizable semantic content units such as boxes, cards, evidence, charts, tables, media, metrics, bullets. */
+  contentUnits: number
+  /** Evidence/source/caveat-like references visible on the slide. */
+  supportReferences: number
 }
 
 export interface SlideMetrics {
@@ -65,10 +78,16 @@ export interface SlideMetrics {
   slideQa: boolean
   /** bounding box of the slide-canvas element itself (post-scale) */
   canvasRect: Rect
+  /** bounding box of the .slide element itself (post-scale) */
+  slideRect: Rect
+  /** whether document/body/slide has scrollbars at 1920x1080 */
+  hasScrollbars: boolean
   /** top-level visible children of .slide-canvas */
   elements: ElementInfo[]
   /** union bounding box of all visible leaf elements */
   contentRect: Rect
+  /** text/content-density signals for content slides */
+  contentStats: SlideContentStats
 }
 
 /**
@@ -207,6 +226,29 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             visible: boolean
             children: EI[]
             classList: string[]
+            text?: string
+            textOverflow?: boolean
+          }
+
+          function textPoints(text: string): number {
+            const normalized = text.replace(/\s+/g, " ").trim()
+            if (!normalized) return 0
+            const cjk = (normalized.match(/[\u3400-\u9fff\uf900-\ufaff]/g) || []).length
+            const words = (normalized.replace(/[\u3400-\u9fff\uf900-\ufaff]/g, " ").match(/[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)*/g) || []).length
+            return cjk + words
+          }
+
+          function isSemanticContentUnit(el: Element): boolean {
+            const tag = el.tagName.toLowerCase()
+            if (["li", "table", "figure", "img", "svg", "canvas", "blockquote"].includes(tag)) return true
+            const cls = Array.from(el.classList).join(" ")
+            return /\b(box|card|claim|evidence|source|caveat|metric|stat|quote|media|chart|echart|table|step|roadmap|toc-item|bullet)\b/i.test(cls)
+          }
+
+          function isSupportReference(el: Element): boolean {
+            const text = (el.textContent || "").replace(/\s+/g, " ").trim()
+            const cls = Array.from(el.classList).join(" ")
+            return /\b(evidence|source|caveat|claim|support|citation|note)\b/i.test(cls) || /\b(source|evidence|caveat|claim|来源|证据|出处|风险|假设)\b/i.test(text)
           }
 
           function collectChildren(
@@ -220,6 +262,11 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             for (const child of Array.from(el.children)) {
               if (!isVisible(child)) continue
               const rawR = child.getBoundingClientRect()
+              const text = (child.textContent || "").replace(/\s+/g, " ").trim()
+              const textOverflow = textPoints(text) > 0 && (
+                (child as HTMLElement).scrollHeight > (child as HTMLElement).clientHeight + 2 ||
+                (child as HTMLElement).scrollWidth > (child as HTMLElement).clientWidth + 2
+              )
               const cls = child.className || ""
               if (
                 typeof cls === "string" &&
@@ -235,6 +282,8 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
                 rect: relR,
                 visible: true,
                 classList: Array.from(child.classList),
+                text: text.slice(0, 160),
+                textOverflow,
                 children: collectChildren(child, offsetTop, offsetLeft, depth + 1),
               })
             }
@@ -273,6 +322,7 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
           if (!canvas) return null
 
           const canvasRaw = canvas.getBoundingClientRect()
+          const slideRaw = (slide as HTMLElement).getBoundingClientRect()
           // Use canvas top-left as the coordinate origin
           const offsetTop = canvasRaw.top
           const offsetLeft = canvasRaw.left
@@ -286,8 +336,40 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             height: canvasRaw.height,
           }
 
+          const slideRect = {
+            left: 0,
+            top: 0,
+            right: slideRaw.width,
+            bottom: slideRaw.height,
+            width: slideRaw.width,
+            height: slideRaw.height,
+          }
+
           const elements = collectChildren(canvas, offsetTop, offsetLeft)
 
+          let bodyTextPoints = 0
+          let contentUnits = 0
+          let supportReferences = 0
+          for (const el of Array.from(canvas.querySelectorAll("*"))) {
+            if (!isVisible(el)) continue
+            if (/^H[1-2]$/.test(el.tagName)) continue
+            const text = (el.textContent || "").replace(/\s+/g, " ").trim()
+            if (text) bodyTextPoints += textPoints(text)
+            if (isSemanticContentUnit(el)) contentUnits++
+            if (isSupportReference(el)) supportReferences++
+          }
+
+          const doc = document.documentElement
+          const body = document.body
+          const slideEl = slide as HTMLElement
+          const hasScrollbars =
+            doc.scrollWidth > window.innerWidth + 2 ||
+            doc.scrollHeight > window.innerHeight + 2 ||
+            body.scrollWidth > window.innerWidth + 2 ||
+            body.scrollHeight > window.innerHeight + 2 ||
+            slideEl.scrollWidth > slideEl.clientWidth + 2 ||
+            slideEl.scrollHeight > slideEl.clientHeight + 2
+
           const titleEl = canvas.querySelector("h1, h2")
           const title = titleEl
             ? (titleEl.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80)
@@ -298,8 +380,11 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             title,
             slideQa,
             canvasRect,
+            slideRect,
+            hasScrollbars,
             elements,
             contentRect: unionRect(elements),
+            contentStats: { bodyTextPoints, contentUnits, supportReferences },
           }
         },
         idx

package/lib/refine/open.ts

@@ -22,6 +22,10 @@ export interface OpenRefineDeckResult {
   mode: RefineMode
 }
 
+export interface EnsureRefineDeckOpenResult extends OpenRefineDeckResult {
+  skippedReason?: "live-session"
+}
+
 export interface OpenRefineDeckOptions {
   client: any
   sessionID: string
@@ -32,6 +36,21 @@ export interface OpenRefineDeckOptions {
 }
 
 export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
+  return openRefineDeckInternal(target, options, { skipLiveSession: false })
+}
+
+export function ensureRefineDeckOpenForChange(
+  target: string,
+  options: OpenRefineDeckOptions,
+): EnsureRefineDeckOpenResult {
+  return openRefineDeckInternal(target, options, { skipLiveSession: true })
+}
+
+function openRefineDeckInternal(
+  target: string,
+  options: OpenRefineDeckOptions,
+  behavior: { skipLiveSession: boolean },
+): EnsureRefineDeckOpenResult {
   const deck = resolveEditableDeck(options.workspaceRoot, target)
   const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
   assertDeckHtmlContractValid(options.workspaceRoot, deck.absoluteFile)
@@ -53,7 +72,7 @@ export function openRefineDeck(target: string, options: OpenRefineDeckOptions):
     mode,
   })
   const url = `${refineServer.baseUrl}/refine?token=${encodeURIComponent(session.token)}`
-  const shouldOpen = options.openBrowser !== false
+  const shouldOpen = options.openBrowser !== false && !(behavior.skipLiveSession && session.live)
   if (shouldOpen) (options.openUrl ?? openUrl)(url)
 
   return {
@@ -66,5 +85,6 @@ export function openRefineDeck(target: string, options: OpenRefineDeckOptions):
     liveSession: session.live,
     openedBrowser: shouldOpen,
     mode,
+    skippedReason: behavior.skipLiveSession && session.live ? "live-session" : undefined,
   }
 }