@cyber-dash-tech/revela 0.17.14 → 0.17.16

package/bin/revela.ts

@@ -86,7 +86,7 @@ Usage:
   revela deck-foundation --outputPath <path> --title <title> --language <tag> [--workspaceRoot <path>] [--designName <name>] [--mode create|repair] [--overwrite true]
   revela qa --file <path> [--workspaceRoot <path>]
   revela review-read --file <path> [--workspaceRoot <path>] [--format json|markdown]
-  revela export-pdf --file <path> [--workspaceRoot <path>]
+  revela export-pdf --file <path> [--workspaceRoot <path>]  # deck PDF, or single-page PDF fallback for non-deck HTML
   revela export-pptx --file <path> [--workspaceRoot <path>]
   revela design-list
   revela design-read [--name <design>]

package/lib/browser/chrome.ts

@@ -0,0 +1,48 @@
+import puppeteer, { type Browser } from "puppeteer-core"
+import { existsSync } from "fs"
+
+export const CHROME_PATHS = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+]
+
+export function findChromePath(): string {
+  for (const p of CHROME_PATHS) {
+    if (existsSync(p)) return p
+  }
+  throw new Error(
+    "Could not find a Chrome/Chromium installation.\n" +
+    "Tried:\n" + CHROME_PATHS.map((p) => `  ${p}`).join("\n")
+  )
+}
+
+export interface LaunchChromeOptions {
+  width?: number
+  height?: number
+  allowFileAccess?: boolean
+}
+
+export async function launchChrome(options: LaunchChromeOptions = {}): Promise<Browser> {
+  const width = options.width ?? 1920
+  const height = options.height ?? 1080
+  const args = [
+    "--no-sandbox",
+    "--disable-setuid-sandbox",
+    "--disable-dev-shm-usage",
+    `--window-size=${width},${height}`,
+  ]
+
+  if (options.allowFileAccess) {
+    args.splice(3, 0, "--allow-file-access-from-files")
+  }
+
+  return await puppeteer.launch({
+    executablePath: findChromePath(),
+    headless: true,
+    args,
+  })
+}

package/lib/commands/pdf.ts

@@ -10,7 +10,6 @@
 import { existsSync, readdirSync } from "fs"
 import { resolve } from "path"
 import { exportToPdf } from "../pdf/export"
-import { assertExportQAPassed } from "../qa/export-gate"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
 
 export async function handlePdf(
@@ -30,10 +29,8 @@ export async function handlePdf(
   }
 
   const abs = resolvedFile.deck.absoluteFile
-  await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
-    await assertExportQAPassed(abs, { workspaceRoot: root })
     await send(`Exporting \`${abs}\` to PDF...`)
     const result = await exportToPdf(abs)
     recordRenderedArtifact(root, {
@@ -46,6 +43,7 @@ export async function handlePdf(
     await send(
       `**PDF exported successfully**\n\n` +
       `- Output: \`${result.outputPath}\`\n` +
+      `- Mode: ${result.exportMode}\n` +
       `- Slides: ${result.slideCount}\n` +
       `- Time: ${secs}s`
     )

package/lib/commands/pptx.ts

@@ -9,7 +9,6 @@
 
 import { existsSync, readdirSync } from "fs"
 import { relative, resolve, sep } from "path"
-import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { exportToPptx } from "../pptx/export"
 import { recordRenderedArtifact } from "../workspace-state/rendered-artifacts"
 
@@ -103,7 +102,6 @@ export async function handlePptx(
     const deck = resolvePptxDeck(workspaceRoot, args.filePath)
     const abs = deck.absoluteFile
 
-    assertDeckHtmlContractValid(workspaceRoot, abs)
     await send(`Exporting \`${abs}\` to PPTX...`)
     let lastSlideUpdate = 0
     let longDeckThreshold: number | null = null

package/lib/html-export/deck-detect.ts

@@ -0,0 +1,78 @@
+import type { Browser } from "puppeteer-core"
+import { pathToFileURL } from "url"
+import { launchChrome } from "../browser/chrome"
+
+export interface DeckDetectionResult {
+  isDeck: boolean
+  slideCount: number
+  reason: string
+}
+
+export async function detectDeckHtml(htmlFilePath: string): Promise<DeckDetectionResult> {
+  const browser = await launchChrome({ allowFileAccess: true })
+  try {
+    return await detectDeckHtmlWithBrowser(browser, htmlFilePath)
+  } finally {
+    await browser.close().catch(() => undefined)
+  }
+}
+
+export async function detectDeckHtmlWithBrowser(browser: Browser, htmlFilePath: string): Promise<DeckDetectionResult> {
+  const page = await browser.newPage()
+  try {
+    await page.goto(pathToFileURL(htmlFilePath).href, { waitUntil: "domcontentloaded", timeout: 15000 })
+    return await page.evaluate(() => {
+      const slides = Array.from(document.querySelectorAll(".slide")) as HTMLElement[]
+      if (slides.length === 0) {
+        return { isDeck: false, slideCount: 0, reason: "no .slide elements found" }
+      }
+
+      const missingCanvas = slides.findIndex((slide) => !slide.querySelector(".slide-canvas"))
+      if (missingCanvas >= 0) {
+        return {
+          isDeck: false,
+          slideCount: slides.length,
+          reason: `.slide ${missingCanvas + 1} has no .slide-canvas`,
+        }
+      }
+
+      const indexValues = slides
+        .map((slide) => slide.getAttribute("data-slide-index"))
+        .filter((value): value is string => value !== null && value.trim() !== "")
+
+      if (indexValues.length > 0) {
+        if (indexValues.length !== slides.length) {
+          return {
+            isDeck: false,
+            slideCount: slides.length,
+            reason: "some slides have data-slide-index and some do not",
+          }
+        }
+
+        const seen = new Set<number>()
+        for (let i = 0; i < indexValues.length; i++) {
+          const parsed = Number(indexValues[i])
+          if (!Number.isInteger(parsed) || parsed < 1) {
+            return {
+              isDeck: false,
+              slideCount: slides.length,
+              reason: `slide ${i + 1} has invalid data-slide-index "${indexValues[i]}"`,
+            }
+          }
+          if (seen.has(parsed)) {
+            return {
+              isDeck: false,
+              slideCount: slides.length,
+              reason: `duplicate data-slide-index "${parsed}"`,
+            }
+          }
+          seen.add(parsed)
+        }
+      }
+
+      return { isDeck: true, slideCount: slides.length, reason: "valid deck contract" }
+    })
+  } finally {
+    await page.close().catch(() => undefined)
+  }
+}

package/lib/html-export/index.ts

@@ -0,0 +1,231 @@
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "fs"
+import { dirname, join, resolve } from "path"
+import { pathToFileURL } from "url"
+import { randomBytes } from "crypto"
+import { Jimp } from "jimp"
+import type { Page } from "puppeteer-core"
+import { launchChrome } from "../browser/chrome"
+import { chooseSelector } from "./selectors"
+import { findTrimmedHeight } from "./trim"
+import { validatePngOutput } from "./validate"
+import { writeSinglePagePdfFromPng } from "./pdf"
+
+export interface ExportSinglePageHtmlPdfOptions {
+  selector?: string
+  outputPath?: string
+  scale?: number
+  trim?: boolean
+  trimColor?: string
+  trimThreshold?: number
+  trimPadding?: number
+  timeout?: number
+  wait?: number
+  background?: boolean
+  maxSegmentHeight?: number
+}
+
+export interface ExportSinglePageHtmlPdfResult {
+  outputPath: string
+  pngPath: string
+  width: number
+  height: number
+  segmentCount: number
+  selector: string
+  attemptedSelectors: string[]
+  warnings: string[]
+}
+
+type Stage = "load" | "selector" | "screenshot" | "stitch" | "trim" | "validate" | "pdf"
+
+export async function exportSinglePageHtmlPdf(
+  htmlFilePath: string,
+  options: ExportSinglePageHtmlPdfOptions = {},
+): Promise<ExportSinglePageHtmlPdfResult> {
+  const abs = resolve(htmlFilePath)
+  if (!existsSync(abs)) throw new Error(`File not found: ${abs}`)
+  if (!/\.html?$/i.test(abs)) throw new Error(`Not an HTML file: ${abs}`)
+
+  const outputPath = options.outputPath ?? abs.replace(/\.html?$/i, ".pdf")
+  const scale = normalizedNumber(options.scale, 2, 0.25, 4)
+  const timeout = normalizedNumber(options.timeout, 60000, 1000, 300000)
+  const wait = normalizedNumber(options.wait, 500, 0, 30000)
+  const maxSegmentHeight = Math.floor(normalizedNumber(options.maxSegmentHeight, 1600, 256, 4096))
+  const background = options.background ?? true
+  const selectorChoice = chooseSelector(options.selector)
+  const tmpDir = join(dirname(outputPath), `.revela-html-export-${randomBytes(6).toString("hex")}`)
+  mkdirSync(tmpDir, { recursive: true })
+  const tmpPng = join(tmpDir, "artifact.png")
+  const finalPng = join(tmpDir, "artifact-final.png")
+  const promotedPng = outputPath.replace(/\.pdf$/i, ".png")
+  const warnings: string[] = []
+  let stage: Stage = "load"
+
+  const browser = await launchChrome({ allowFileAccess: true, width: 1200, height: maxSegmentHeight })
+  try {
+    const page = await browser.newPage()
+    try {
+      await page.setViewport({ width: 1200, height: maxSegmentHeight, deviceScaleFactor: scale })
+      await page.goto(pathToFileURL(abs).href, { waitUntil: "domcontentloaded", timeout })
+      await waitForStablePage(page, timeout, wait, warnings)
+
+      stage = "selector"
+      const target = await resolveTarget(page, selectorChoice.attempted)
+      if (!target) {
+        throw new Error(`selector was not found. Attempted: ${selectorChoice.attempted.join(", ")}`)
+      }
+
+      const viewportWidth = Math.max(1, Math.ceil(target.box.width + target.box.x))
+      await page.setViewport({ width: viewportWidth, height: maxSegmentHeight, deviceScaleFactor: scale })
+      await waitForAnimationFrames(page)
+
+      const segments: Array<{ buffer: Buffer; top: number; height: number }> = []
+      const totalHeight = Math.ceil(target.box.height)
+      const width = Math.ceil(target.box.width)
+      const x = Math.max(0, Math.floor(target.box.x))
+      const y = Math.max(0, Math.floor(target.box.y))
+
+      stage = "screenshot"
+      for (let top = 0; top < totalHeight; top += maxSegmentHeight) {
+        const height = Math.min(maxSegmentHeight, totalHeight - top)
+        const clip = { x, y: y + top, width, height }
+        try {
+          const buffer = await page.screenshot({ type: "png", clip, omitBackground: !background })
+          segments.push({ buffer: Buffer.from(buffer), top, height })
+        } catch {
+          const buffer = await page.screenshot({ type: "png", clip, omitBackground: !background })
+          segments.push({ buffer: Buffer.from(buffer), top, height })
+        }
+      }
+
+      stage = "stitch"
+      const stitched = new Jimp({
+        width: Math.round(width * scale),
+        height: Math.round(totalHeight * scale),
+        color: background ? 0x000000ff : 0x00000000,
+      })
+      for (const segment of segments) {
+        const image = await Jimp.read(segment.buffer)
+        stitched.composite(image, 0, Math.round(segment.top * scale))
+      }
+
+      stage = "trim"
+      const trimmedHeight = findTrimmedHeight(stitched, {
+        enabled: options.trim ?? true,
+        color: options.trimColor,
+        threshold: options.trimThreshold,
+        padding: options.trimPadding,
+      })
+      const finalImage = trimmedHeight < stitched.bitmap.height
+        ? stitched.crop({ x: 0, y: 0, w: stitched.bitmap.width, h: trimmedHeight })
+        : stitched
+
+      const finalBuffer = await (finalImage.getBuffer as any)("image/png")
+      writeFileSync(tmpPng, new Uint8Array(finalBuffer))
+      renameSync(tmpPng, finalPng)
+
+      stage = "validate"
+      const validation = await validatePngOutput(finalPng)
+
+      stage = "pdf"
+      await writeSinglePagePdfFromPng(finalPng, outputPath, validation.width, validation.height)
+
+      return {
+        outputPath,
+        pngPath: promotedPng,
+        width: validation.width,
+        height: validation.height,
+        segmentCount: segments.length,
+        selector: target.selector,
+        attemptedSelectors: selectorChoice.attempted,
+        warnings,
+      }
+    } finally {
+      await page.close().catch(() => undefined)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(
+      `Single-page HTML PDF export failed during ${stage}.\n` +
+      `File: ${abs}\n` +
+      `Attempted selector(s): ${selectorChoice.attempted.join(", ")}\n` +
+      message
+    )
+  } finally {
+    await browser.close().catch(() => undefined)
+    if (existsSync(finalPng)) {
+      try {
+        if (statSync(finalPng).size > 0) renameSync(finalPng, promotedPng)
+      } catch {
+        // Non-fatal; the PDF is the requested artifact.
+      }
+    }
+    rmSync(tmpDir, { recursive: true, force: true })
+  }
+}
+
+function normalizedNumber(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = typeof value === "number" ? value : Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.min(max, Math.max(min, parsed))
+}
+
+async function waitForStablePage(page: Page, timeout: number, wait: number, warnings: string[]) {
+  await page.evaluate(async (timeoutMs) => {
+    const deadline = Date.now() + timeoutMs
+    const fonts = (document as any).fonts
+    if (fonts?.ready) {
+      await Promise.race([
+        fonts.ready,
+        new Promise((resolve) => setTimeout(resolve, Math.max(0, deadline - Date.now()))),
+      ])
+    }
+  }, Math.min(timeout, 10000)).catch(() => warnings.push("Timed out waiting for fonts."))
+
+  await page.evaluate(async (timeoutMs) => {
+    const deadline = Date.now() + timeoutMs
+    const images = Array.from(document.images)
+    await Promise.all(images.map((img) => {
+      if (img.complete) return undefined
+      return new Promise<void>((resolve) => {
+        const done = () => resolve()
+        const remaining = Math.max(0, deadline - Date.now())
+        const timer = setTimeout(done, remaining)
+        img.addEventListener("load", () => { clearTimeout(timer); done() }, { once: true })
+        img.addEventListener("error", () => { clearTimeout(timer); done() }, { once: true })
+      })
+    }))
+  }, Math.min(timeout, 20000)).catch(() => warnings.push("Timed out waiting for images."))
+
+  await waitForAnimationFrames(page)
+  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait))
+}
+
+async function waitForAnimationFrames(page: Page) {
+  await page.evaluate(() => new Promise<void>((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()))
+  }))
+}
+
+async function resolveTarget(
+  page: Page,
+  selectors: string[],
+): Promise<{ selector: string; box: { x: number; y: number; width: number; height: number } } | null> {
+  return await page.evaluate((candidates) => {
+    for (const selector of candidates) {
+      const el = document.querySelector(selector) as HTMLElement | null
+      if (!el) continue
+      const rect = el.getBoundingClientRect()
+      if (rect.width <= 0 || rect.height <= 0) continue
+      return {
+        selector,
+        box: {
+          x: rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+          width: rect.width,
+          height: rect.height,
+        },
+      }
+    }
+    return null
+  }, selectors)
+}

package/lib/html-export/pdf.ts

@@ -0,0 +1,15 @@
+import { PDFDocument } from "pdf-lib"
+import { readFileSync, renameSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import { randomBytes } from "crypto"
+
+export async function writeSinglePagePdfFromPng(pngPath: string, outputPath: string, width: number, height: number): Promise<void> {
+  const pdf = await PDFDocument.create()
+  const image = await pdf.embedPng(new Uint8Array(readFileSync(pngPath)))
+  const page = pdf.addPage([width, height])
+  page.drawImage(image, { x: 0, y: 0, width, height })
+
+  const tmpPath = join(dirname(outputPath), `.revela-${randomBytes(6).toString("hex")}.pdf`)
+  writeFileSync(tmpPath, await pdf.save())
+  renameSync(tmpPath, outputPath)
+}

package/lib/html-export/selectors.ts

@@ -0,0 +1,12 @@
+export const DEFAULT_SINGLE_PAGE_SELECTORS = [".poster", ".artifact", "main", "body"]
+
+export interface SelectorChoice {
+  selector: string
+  attempted: string[]
+}
+
+export function chooseSelector(input?: string): SelectorChoice {
+  const trimmed = input?.trim()
+  if (trimmed) return { selector: trimmed, attempted: [trimmed] }
+  return { selector: DEFAULT_SINGLE_PAGE_SELECTORS[0], attempted: [...DEFAULT_SINGLE_PAGE_SELECTORS] }
+}

package/lib/html-export/trim.ts

@@ -0,0 +1,60 @@
+import { Jimp } from "jimp"
+
+export interface TrimOptions {
+  enabled: boolean
+  color?: string
+  threshold?: number
+  padding?: number
+}
+
+export function parseHexColor(value = "#020615"): { r: number; g: number; b: number } {
+  const normalized = value.trim().replace(/^#/, "")
+  if (!/^[0-9a-fA-F]{6}$/.test(normalized)) return { r: 2, g: 6, b: 21 }
+  return {
+    r: Number.parseInt(normalized.slice(0, 2), 16),
+    g: Number.parseInt(normalized.slice(2, 4), 16),
+    b: Number.parseInt(normalized.slice(4, 6), 16),
+  }
+}
+
+export function findTrimmedHeight(image: InstanceType<typeof Jimp>, options: TrimOptions): number {
+  if (!options.enabled) return image.bitmap.height
+
+  const { width, height, data } = image.bitmap
+  const color = parseHexColor(options.color)
+  const threshold = options.threshold ?? 8
+  const padding = Math.max(0, Math.floor(options.padding ?? 0))
+  const requiredBlankRows = Math.min(24, Math.max(4, Math.floor(height * 0.003)))
+  let blankRun = 0
+  let trimStart = height
+
+  for (let y = height - 1; y >= 0; y--) {
+    let rowBlank = true
+    for (let x = 0; x < width; x++) {
+      const idx = (y * width + x) * 4
+      const a = data[idx + 3] ?? 255
+      const r = data[idx] ?? 0
+      const g = data[idx + 1] ?? 0
+      const b = data[idx + 2] ?? 0
+      const close =
+        Math.abs(r - color.r) <= threshold &&
+        Math.abs(g - color.g) <= threshold &&
+        Math.abs(b - color.b) <= threshold
+      if (a > 8 && !close) {
+        rowBlank = false
+        break
+      }
+    }
+
+    if (rowBlank) {
+      blankRun += 1
+      if (blankRun >= requiredBlankRows) trimStart = y
+      continue
+    }
+
+    break
+  }
+
+  if (trimStart >= height) return height
+  return Math.min(height, Math.max(1, trimStart + padding))
+}

package/lib/html-export/validate.ts

@@ -0,0 +1,44 @@
+import { statSync } from "fs"
+import { Jimp } from "jimp"
+
+export interface PngValidationResult {
+  width: number
+  height: number
+  fileSize: number
+}
+
+export async function validatePngOutput(path: string): Promise<PngValidationResult> {
+  const fileSize = statSync(path).size
+  const image = await Jimp.read(path)
+  const { width, height, data } = image.bitmap
+  if (width <= 0 || height <= 0) throw new Error("PNG output has invalid dimensions")
+  if (fileSize <= 0) throw new Error("PNG output is empty")
+
+  const samples = samplePixels(width, height)
+  let varied = false
+  let visible = false
+  let first: string | undefined
+
+  for (const [x, y] of samples) {
+    const idx = (y * width + x) * 4
+    const rgba = `${data[idx]},${data[idx + 1]},${data[idx + 2]},${data[idx + 3]}`
+    if ((data[idx + 3] ?? 0) > 8) visible = true
+    first ??= rgba
+    if (rgba !== first) varied = true
+  }
+
+  if (!visible) throw new Error("PNG output appears fully transparent")
+  if (!varied && width * height > 1) throw new Error("PNG output appears flat")
+
+  return { width, height, fileSize }
+}
+
+function samplePixels(width: number, height: number): Array<[number, number]> {
+  const xs = [0.1, 0.25, 0.5, 0.75, 0.9].map((v) => Math.min(width - 1, Math.max(0, Math.floor(width * v))))
+  const ys = [0.1, 0.25, 0.5, 0.75, 0.9].map((v) => Math.min(height - 1, Math.max(0, Math.floor(height * v))))
+  const out: Array<[number, number]> = []
+  for (const y of ys) {
+    for (const x of xs) out.push([x, y])
+  }
+  return out
+}

package/lib/pdf/export.ts

@@ -17,7 +17,6 @@
  * Output path: replaces the .html extension with .pdf, same directory as input.
  */
 
-import puppeteer from "puppeteer-core"
 import { PDFDocument } from "pdf-lib"
 import {
   existsSync,
@@ -29,6 +28,9 @@ import {
 import { resolve, dirname, basename, join, extname } from "path"
 import { pathToFileURL } from "url"
 import { randomBytes } from "crypto"
+import { launchChrome } from "../browser/chrome"
+import { detectDeckHtml } from "../html-export/deck-detect"
+import { exportSinglePageHtmlPdf } from "../html-export"
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -36,16 +38,6 @@ import { randomBytes } from "crypto"
 const CANVAS_W = 1920
 const CANVAS_H = 1080
 
-/** Path to system Chrome on macOS and Linux — same as measure.ts */
-const CHROME_PATHS = [
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  "/Applications/Chromium.app/Contents/MacOS/Chromium",
-  "/usr/bin/google-chrome-stable",
-  "/usr/bin/google-chrome",
-  "/usr/bin/chromium-browser",
-  "/usr/bin/chromium",
-]
-
 /** Mime type → file extension mapping for downloaded images */
 const MIME_TO_EXT: Record<string, string> = {
   "image/jpeg": ".jpg",
@@ -71,16 +63,6 @@ const EXT_TO_MIME: Record<string, string> = {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function findChromePath(): string {
-  for (const p of CHROME_PATHS) {
-    if (existsSync(p)) return p
-  }
-  throw new Error(
-    "Could not find a Chrome/Chromium installation.\n" +
-    "Tried:\n" + CHROME_PATHS.map((p) => `  ${p}`).join("\n")
-  )
-}
-
 /** Derive output PDF path from input HTML path (same dir, .html → .pdf) */
 export function derivePdfPath(htmlFilePath: string): string {
   const abs = resolve(htmlFilePath)
@@ -233,6 +215,15 @@ export interface ExportResult {
   outputPath: string
   slideCount: number
   durationMs: number
+  exportMode: "deck" | "single-page-html"
+  deckDetection?: {
+    isDeck: boolean
+    slideCount: number
+    reason: string
+  }
+  selector?: string
+  pngPath?: string
+  warnings?: string[]
 }
 
 /**
@@ -244,6 +235,28 @@ export interface ExportResult {
 export async function exportToPdf(htmlFilePath: string): Promise<ExportResult> {
   const startMs = Date.now()
   const abs = resolve(htmlFilePath)
+  const detection = await detectDeckHtml(abs)
+  if (detection.isDeck) {
+    const result = await exportDeckToPdf(abs)
+    return { ...result, exportMode: "deck", deckDetection: detection, durationMs: Date.now() - startMs }
+  }
+
+  const result = await exportSinglePageHtmlPdf(abs, { outputPath: derivePdfPath(abs) })
+  return {
+    outputPath: result.outputPath,
+    slideCount: 1,
+    durationMs: Date.now() - startMs,
+    exportMode: "single-page-html",
+    deckDetection: detection,
+    selector: result.selector,
+    pngPath: result.pngPath,
+    warnings: result.warnings,
+  }
+}
+
+export async function exportDeckToPdf(htmlFilePath: string): Promise<Omit<ExportResult, "exportMode">> {
+  const startMs = Date.now()
+  const abs = resolve(htmlFilePath)
 
   if (!existsSync(abs)) {
     throw new Error(`File not found: ${abs}`)
@@ -254,7 +267,6 @@ export async function exportToPdf(htmlFilePath: string): Promise<ExportResult> {
   }
 
   const outputPath = derivePdfPath(abs)
-  const executablePath = findChromePath()
 
   // ── Step 1: Download external images and rewrite HTML ─────────────────────
   const tmpDir = join("/tmp", `revela-pdf-${randomBytes(6).toString("hex")}`)
@@ -275,18 +287,7 @@ export async function exportToPdf(htmlFilePath: string): Promise<ExportResult> {
   const fileUrl = pathToFileURL(tmpHtmlPath).href
 
   // ── Step 2: Launch Puppeteer and screenshot each slide ────────────────────
-  const browser = await puppeteer.launch({
-    executablePath,
-    headless: true,
-    args: [
-      "--no-sandbox",
-      "--disable-setuid-sandbox",
-      "--disable-dev-shm-usage",
-      // Allow file:// pages to load other local file:// resources (downloaded images)
-      "--allow-file-access-from-files",
-      `--window-size=${CANVAS_W},${CANVAS_H}`,
-    ],
-  })
+  const browser = await launchChrome({ width: CANVAS_W, height: CANVAS_H, allowFileAccess: true })
 
   let screenshots: Buffer[] = []
 

package/lib/pptx/export.ts

@@ -13,7 +13,7 @@
  * editable whenever dom-to-pptx can represent them.
  */
 
-import puppeteer, { type Browser, type Page } from "puppeteer-core"
+import { type Browser, type Page } from "puppeteer-core"
 import { DOMParser, XMLSerializer } from "@xmldom/xmldom"
 import { unzipSync, zipSync, strFromU8, strToU8 } from "fflate"
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs"
@@ -21,6 +21,7 @@ import { createRequire } from "module"
 import { basename, dirname, extname, join, posix as pathPosix, resolve } from "path"
 import { randomBytes } from "crypto"
 import { pathToFileURL } from "url"
+import { findChromePath, launchChrome } from "../browser/chrome"
 
 const CANVAS_W = 1920
 const CANVAS_H = 1080
@@ -28,15 +29,6 @@ const MIN_PPTX_FONT_SIZE_PT = 6
 const PPT_REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
 const requireFromExportModule = createRequire(import.meta.url)
 
-const CHROME_PATHS = [
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  "/Applications/Chromium.app/Contents/MacOS/Chromium",
-  "/usr/bin/google-chrome-stable",
-  "/usr/bin/google-chrome",
-  "/usr/bin/chromium-browser",
-  "/usr/bin/chromium",
-]
-
 const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".avif", ".bmp"])
 const MIME_TO_EXT: Record<string, string> = {
   "image/jpeg": ".jpg",
@@ -125,28 +117,8 @@ interface LocalizeExternalImagesResult {
   localizedCount: number
 }
 
-function findChromePath(): string {
-  for (const p of CHROME_PATHS) {
-    if (existsSync(p)) return p
-  }
-  throw new Error(
-    "Could not find a Chrome/Chromium installation.\n" +
-    "Tried:\n" + CHROME_PATHS.map((p) => `  ${p}`).join("\n")
-  )
-}
-
-async function launchBrowser(executablePath: string): Promise<Browser> {
-  return await puppeteer.launch({
-    executablePath,
-    headless: true,
-    args: [
-      "--no-sandbox",
-      "--disable-setuid-sandbox",
-      "--disable-dev-shm-usage",
-      "--allow-file-access-from-files",
-      `--window-size=${CANVAS_W},${CANVAS_H}`,
-    ],
-  })
+async function launchBrowser(): Promise<Browser> {
+  return await launchChrome({ width: CANVAS_W, height: CANVAS_H, allowFileAccess: true })
 }
 
 export function derivePptxPath(htmlFilePath: string): string {
@@ -984,7 +956,7 @@ export async function exportToPptx(
     kind: "stage",
     message: "Launching Chrome and preparing slide DOM...",
   })
-  const browser = await launchBrowser(executablePath)
+  const browser = await launchBrowser()
 
   try {
     const pageSetupStart = Date.now()

package/lib/qa/measure.ts

@@ -9,8 +9,8 @@
  * Returns raw per-slide geometry data consumed by checks.ts.
  */
 
-import puppeteer from "puppeteer-core"
 import { pathToFileURL } from "url"
+import { launchChrome } from "../browser/chrome"
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -18,16 +18,6 @@ import { pathToFileURL } from "url"
 export const CANVAS_W = 1920
 export const CANVAS_H = 1080
 
-/** Path to system Chrome on macOS. Falls back to common Linux paths. */
-const CHROME_PATHS = [
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  "/Applications/Chromium.app/Contents/MacOS/Chromium",
-  "/usr/bin/google-chrome-stable",
-  "/usr/bin/google-chrome",
-  "/usr/bin/chromium-browser",
-  "/usr/bin/chromium",
-]
-
 // ── Types ────────────────────────────────────────────────────────────────────
 
 export interface Rect {
@@ -127,19 +117,6 @@ export interface MeasurementResult {
   cssDefinedClasses: string[]
 }
 
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function findChromePath(): string {
-  const { existsSync } = require("fs") as typeof import("fs")
-  for (const p of CHROME_PATHS) {
-    if (existsSync(p)) return p
-  }
-  throw new Error(
-    "Could not find a Chrome/Chromium installation. " +
-    "Tried: " + CHROME_PATHS.join(", ")
-  )
-}
-
 // ── Main export ──────────────────────────────────────────────────────────────
 
 /**
@@ -147,19 +124,9 @@ function findChromePath(): string {
  * and return slide geometry + CSS class names defined in <style> blocks.
  */
 export async function measureSlides(htmlFilePath: string): Promise<MeasurementResult> {
-  const executablePath = findChromePath()
   const fileUrl = pathToFileURL(htmlFilePath).href
 
-  const browser = await puppeteer.launch({
-    executablePath,
-    headless: true,
-    args: [
-      "--no-sandbox",
-      "--disable-setuid-sandbox",
-      "--disable-dev-shm-usage",
-      "--window-size=1920,1080",
-    ],
-  })
+  const browser = await launchChrome({ width: CANVAS_W, height: CANVAS_H })
 
   try {
     const page = await browser.newPage()

package/lib/runtime/index.ts

@@ -10,6 +10,7 @@ import { readDeckPlanArtifact } from "../narrative-state/deck-plan-artifact"
 import { extractDesignClasses } from "../design/designs"
 import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
 import type { ReviewDeckOpenInput, ReviewDeckReadInput } from "./review"
+import pkg from "../../package.json"
 export { bindResearchFindings, evaluateResearchFindings, researchSave, researchTargets } from "./research"
 export { storyRead } from "./story"
 
@@ -42,6 +43,7 @@ export function doctor(input: RuntimeWorkspaceInput = {}) {
   const workspaceRoot = root(input.workspaceRoot)
   return {
     ok: true,
+    version: pkg.version,
     workspaceRoot,
     hasNarrativeVault: existsSync(resolve(workspaceRoot, "revela-narrative")),
     hasDeckPlan: existsSync(resolve(workspaceRoot, "deck-plan")),
@@ -111,10 +113,8 @@ export async function runDeckQa(input: RuntimeFileInput) {
 
 export async function exportPdf(input: RuntimeFileInput) {
   const { exportToPdf } = await import("../pdf/export")
-  const { assertExportQAPassed } = await import("../qa/export-gate")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
-  await assertExportQAPassed(filePath, { workspaceRoot })
   const result = await exportToPdf(filePath)
   recordRenderedArtifact(workspaceRoot, {
     sourceHtmlPath: workspaceRelative(resolve(workspaceRoot), filePath),
@@ -127,10 +127,8 @@ export async function exportPdf(input: RuntimeFileInput) {
 
 export async function exportPptx(input: RuntimeFileInput & { speakerNotes?: Array<string | null | undefined> }) {
   const { exportToPptx } = await import("../pptx/export")
-  const { assertExportQAPassed } = await import("../qa/export-gate")
   const workspaceRoot = root(input.workspaceRoot)
   const filePath = resolve(workspaceRoot, input.file)
-  await assertExportQAPassed(filePath, { workspaceRoot })
   const result = await exportToPptx(filePath, { speakerNotes: input.speakerNotes })
   recordRenderedArtifact(workspaceRoot, {
     sourceHtmlPath: workspaceRelative(resolve(workspaceRoot), filePath),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.14",
+  "version": "0.17.16",
   "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugins/revela/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "revela": {
       "command": "npx",
-      "args": ["-y", "@cyber-dash-tech/revela@0.17.14", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.16", "mcp"]
     }
   }
 }

package/plugins/revela/mcp/revela-server.ts

@@ -83,7 +83,7 @@ const tools = [
   },
   {
     name: "revela_export_pdf",
-    description: "Run export QA and export a Revela HTML deck to PDF.",
+    description: "Export HTML to PDF. Deck HTML uses multi-page deck export; non-deck HTML falls back to a single-page artifact PDF.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       file: requiredStringProp("Workspace-relative or absolute HTML deck path."),
@@ -91,7 +91,7 @@ const tools = [
   },
   {
     name: "revela_export_pptx",
-    description: "Run export QA and export a Revela HTML deck to PPTX.",
+    description: "Export a Revela HTML deck to PPTX.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       file: requiredStringProp("Workspace-relative or absolute HTML deck path."),

package/plugins/revela/skills/revela-export/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: revela-export
-description: Export Revela deck artifacts from Codex to PDF or PPTX after artifact QA.
+description: Export Revela deck artifacts from Codex to PDF or PPTX.
 ---
 
 # Revela Export
@@ -10,12 +10,12 @@ Use this skill when the user asks to export a Revela deck.
 ## Workflow
 
 1. Resolve the target HTML deck path.
-2. Call `revela_run_deck_qa` before export.
-3. If QA hard errors exist, repair the HTML before exporting.
-4. For PDF, call `revela_export_pdf`.
-5. For PPTX, call `revela_export_pptx`.
-6. Report output path and any export diagnostics.
+2. For PDF, call `revela_export_pdf`.
+3. For PPTX, call `revela_export_pptx`.
+4. Report output path or export errors.
 
 `revela_run_deck_qa`, `revela_export_pdf`, and `revela_export_pptx` may launch a browser. In sandboxed Codex sessions, request user-approved command escalation when the browser cannot start inside the default sandbox.
 
+Deck writes run post-write QA automatically. Do not run artifact QA as a pre-export blocker unless the user explicitly asks for diagnostics.
+
 Do not treat narrative gaps as export blockers unless they affect technical artifact validity or data safety.

package/tools/pdf.ts

@@ -8,13 +8,11 @@ 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"
 import { recordRenderedArtifact, workspaceRelative } from "../lib/workspace-state/rendered-artifacts"
 
 export default tool({
   description:
-    "Export a Revela-generated HTML slide deck to PDF. " +
-    "Runs pre-export QA before writing the PDF. " +
+    "Export HTML to PDF. Revela deck HTML exports as a multi-page deck PDF; non-deck HTML falls back to a single-page artifact PDF. " +
     "Output is written beside the input file with the same basename and a .pdf extension.",
   args: {
     file: tool.schema
@@ -37,7 +35,6 @@ export default tool({
 
     try {
       const root = directory || process.cwd()
-      await assertExportQAPassed(filePath, { workspaceRoot: root })
       const result = await exportToPdf(filePath)
       recordRenderedArtifact(root, {
         sourceHtmlPath: workspaceRelative(resolve(root), filePath),

package/tools/pptx.ts

@@ -7,7 +7,6 @@
 import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
-import { assertDeckHtmlContractValid } from "../lib/deck-html/contract"
 import { exportToPptx } from "../lib/pptx/export"
 import { recordRenderedArtifact, workspaceRelative } from "../lib/workspace-state/rendered-artifacts"
 
@@ -45,7 +44,6 @@ export default tool({
 
     try {
       const root = directory || process.cwd()
-      assertDeckHtmlContractValid(root, filePath)
       const result = await exportToPptx(filePath, {
         speakerNotes: normalizeSpeakerNotes(speakerNotes),
         onProgress: (event) => {

package/tools/qa.ts

@@ -3,7 +3,7 @@
  *
  * revela-qa — Artifact quality assurance for generated slide HTML files.
  *
- * Exposed as a manual diagnostic tool. Export commands run pre-export QA automatically.
+ * Exposed as a manual diagnostic tool. Deck writes run post-write QA automatically.
  */
 
 import { tool } from "@opencode-ai/plugin"
@@ -18,7 +18,7 @@ export default tool({
     "Opens the file in a headless browser and measures actual rendered geometry. " +
     "Checks deck contract, component compliance, exact 1920x1080 canvas, scrollbars, element overflow, text overflow, and content/evidence density warnings. " +
     "Returns a structured report with specific issues and fix instructions. " +
-    "Deck writes and PDF/PPTX export commands run QA automatically; call it directly for explicit diagnostics.",
+    "Deck writes run QA automatically; call it directly for explicit diagnostics before review or export.",
   args: {
     file: tool.schema
       .string()

package/lib/qa/export-gate.ts

@@ -1,18 +0,0 @@
-import { formatReport, runQA } from "./index"
-import { assertDeckHtmlContractValid } from "../deck-html/contract"
-
-export interface ExportQAGateOptions {
-  workspaceRoot?: string
-}
-
-export async function assertExportQAPassed(filePath: string, options: ExportQAGateOptions = {}): Promise<void> {
-  if (options.workspaceRoot) assertDeckHtmlContractValid(options.workspaceRoot, filePath)
-
-  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)
-  )
-}