@cyber-dash-tech/revela 0.1.3 → 0.1.5

package/README.md

@@ -102,9 +102,8 @@ Three designs are bundled. Switch with `/revela designs <name>`.
 
 | Name | Description | Preview |
 |---|---|---|
-| `default` | Dark executive style — deep navy/slate, sharp typography, ECharts data visualization | ![default](assets/img/slide-example-default.jpg) |
-| `minimal` | Clean light theme — high contrast, generous whitespace, professional look | ![minimal](assets/img/slide-example-minimal.jpg) |
-| `editorial-ribbon` | Bold editorial layout — accent ribbons, strong headlines, high visual impact | ![editorial-ribbon](assets/img/slide-example-ribbon.jpg) |
+| `aurora` | Dark executive style — deep navy/slate, sharp typography, ECharts data visualization | ![default](assets/img/slide-example-aurora.jpg) |
+| `summit` | Editorial outdoor annual-report theme | ![summit](assets/img/slide-example-summit.jpg) |
 
 ---
 

package/README.zh-CN.md

@@ -133,9 +133,8 @@ OPENCODE_ENABLE_EXA=1 opencode
 
 | 名称 | 说明 | 预览 |
 |---|---|---|
-| `default` | 深色商务风格 —— 深海军蓝/石板色，锐利字体，ECharts 数据可视化 | ![default](assets/img/slide-example-default.jpg) |
-| `minimal` | 简洁浅色主题 —— 高对比度，充足留白，专业外观 | ![minimal](assets/img/slide-example-minimal.jpg) |
-| `editorial-ribbon` | 大胆的编辑版式 —— 强调色横幅，醒目标题，高视觉冲击力 | ![editorial-ribbon](assets/img/slide-example-ribbon.jpg) |
+| `aurora` | 颜色主题 — 极光, 高饱和度, ECharts 数据可视化 | ![default](assets/img/slide-example-aurora.jpg) |
+| `summit` | 极简主义 - 户外，适合有丰富插图，Echart 数据可视化 | ![summit](assets/img/slide-example-summit.jpg) |
 
 ---
 

package/lib/agents/research-prompt.ts

@@ -53,9 +53,13 @@ Formulate **3–6 targeted search queries** for your specific axis, covering:
 
 For Chinese topics: search in **both Chinese and English**.
 
-Use \`webfetch\` to retrieve specific pages for depth. Do NOT use \`websearch\` —
-it is not available. Use \`webfetch\` with targeted URLs from your knowledge or
-from initial search results.
+Use **\`websearch\`** for broad keyword queries to find relevant pages, reports,
+and data. Then use **\`webfetch\`** to retrieve specific pages for depth.
+
+Search strategy:
+- Start with \`websearch\` to discover relevant URLs (market reports, company pages, news)
+- Follow up with \`webfetch\` on the most promising URLs for full content
+- For Chinese topics: run \`websearch\` queries in both Chinese and English
 
 ---
 

package/lib/design/designs.ts

@@ -436,6 +436,164 @@ function installFromPath(srcPath: string, name?: string): string {
   return designName
 }
 
+// ---------------------------------------------------------------------------
+// Design class vocabulary extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * The set of CSS class names that are always allowed, regardless of design.
+ * These are structural/behavioural classes used by every presentation.
+ */
+const UNIVERSAL_CLASSES = new Set([
+  "slide",
+  "slide-canvas",
+  "visible",
+  "reveal",
+  "editable",
+  "page",
+  "bg",
+  "fg",
+  "overlay",
+  "alt",
+  "strong",
+])
+
+/**
+ * CSS class prefixes that are always exempt from compliance checks.
+ * Third-party libraries (icons, charts) generate classes with these prefixes.
+ */
+export const DEFAULT_PREFIX_EXEMPTIONS: string[] = ["lucide-", "echarts-", "editable-"]
+
+export interface DesignClassVocabulary {
+  /** Complete set of allowed CSS class names. */
+  classes: Set<string>
+  /** Class name prefixes that bypass compliance checks. */
+  prefixExemptions: string[]
+}
+
+/**
+ * Extract all CSS class names defined in a DESIGN.md and return a closed
+ * vocabulary of allowed class names for compliance checking.
+ *
+ * Extraction sources:
+ * - @design:foundation — parses CSS `.class-name` selectors in code blocks
+ * - @layout:xxx — parses HTML class="..." attributes and CSS selectors
+ * - @component:xxx — same as layouts
+ *
+ * UNIVERSAL_CLASSES and DEFAULT_PREFIX_EXEMPTIONS are always included.
+ *
+ * Falls back to UNIVERSAL_CLASSES-only when the design has no markers.
+ */
+export function extractDesignClasses(designName?: string): DesignClassVocabulary {
+  const name = designName || activeDesign()
+  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
+
+  if (!existsSync(mdPath)) {
+    return { classes: new Set(UNIVERSAL_CLASSES), prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
+  }
+
+  const raw = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(raw)
+  const { sections, layouts, components, hasMarkers } = parseDesignSections(body)
+
+  if (!hasMarkers) {
+    // No markers — can't extract a reliable vocabulary; return universal only
+    return { classes: new Set(UNIVERSAL_CLASSES), prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
+  }
+
+  const classes = new Set(UNIVERSAL_CLASSES)
+
+  // Regex patterns for extraction (stateless — reset lastIndex before each use)
+  const htmlClassRe = /class="([^"]*)"/g
+  const cssClassRe = /\.([a-zA-Z_][\w-]*)/g
+
+  /** Extract CSS class names from a CSS string (selector context only).
+   * Strips url(...) and string literals before scanning to avoid false positives
+   * from inline SVG data URIs and other non-selector content.
+   */
+  function extractFromCss(css: string): void {
+    // Remove url(...) values (may contain encoded paths like w3.org, data URIs, etc.)
+    const stripped = css
+      .replace(/url\([^)]*\)/gi, "url()")
+      // Remove quoted strings (single or double)
+      .replace(/"[^"]*"/g, '""')
+      .replace(/'[^']*'/g, "''")
+    cssClassRe.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = cssClassRe.exec(stripped)) !== null) {
+      if (m[1]) classes.add(m[1])
+    }
+  }
+
+  /** Extract CSS class names from an HTML string (class="..." attributes only). */
+  function extractFromHtml(html: string): void {
+    htmlClassRe.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = htmlClassRe.exec(html)) !== null) {
+      for (const cls of m[1].split(/\s+/)) {
+        if (cls.trim()) classes.add(cls.trim())
+      }
+    }
+    // Also scan inline <style>...</style> blocks inside HTML snippets
+    const styleBlockRe = /<style[^>]*>([\s\S]*?)<\/style>/gi
+    styleBlockRe.lastIndex = 0
+    while ((m = styleBlockRe.exec(html)) !== null) {
+      extractFromCss(m[1])
+    }
+  }
+
+  /**
+   * Scan a DESIGN.md section body and extract CSS class names only from:
+   *   - ```css ... ``` code blocks  → CSS selector extraction
+   *   - ```html ... ``` code blocks → HTML class="..." attribute extraction
+   *   - <style>...</style> blocks   → CSS selector extraction
+   *
+   * Skips ```javascript / ```js / ```ts code blocks entirely to avoid
+   * extracting JS method names (e.g. .classList, .forEach) as class names.
+   */
+  function extractFromSection(text: string): void {
+    // Match fenced code blocks: ```<lang>\n...\n```
+    const fenceRe = /```(\w*)\n([\s\S]*?)```/g
+    let m: RegExpExecArray | null
+    fenceRe.lastIndex = 0
+    while ((m = fenceRe.exec(text)) !== null) {
+      const lang = m[1].toLowerCase()
+      const body = m[2]
+      if (lang === "css" || lang === "scss" || lang === "less") {
+        extractFromCss(body)
+      } else if (lang === "html" || lang === "xml" || lang === "") {
+        // Unknown-lang fences in DESIGN.md are usually HTML snippets
+        extractFromHtml(body)
+      }
+      // javascript / js / ts / typescript → skip entirely
+    }
+
+    // Also scan top-level <style>...</style> outside code blocks
+    const styleBlockRe = /<style[^>]*>([\s\S]*?)<\/style>/gi
+    styleBlockRe.lastIndex = 0
+    while ((m = styleBlockRe.exec(text)) !== null) {
+      extractFromCss(m[1])
+    }
+  }
+
+  // Extract from all sections (foundation, rules, etc.)
+  for (const content of Object.values(sections)) {
+    extractFromSection(content)
+  }
+
+  // Extract from all layouts
+  for (const { content } of Object.values(layouts)) {
+    extractFromSection(content)
+  }
+
+  // Extract from all components
+  for (const content of Object.values(components)) {
+    extractFromSection(content)
+  }
+
+  return { classes, prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
+}
+
 async function installFromUrl(url: string, name?: string): Promise<string> {
   // Download zip to temp dir
   const tmp = join(tmpdir(), `revela-design-${Date.now()}`)

package/lib/log.ts

@@ -17,8 +17,9 @@ export const log = new Logger({
   type: "json",
   hideLogPositionForProduction: true,
   overwrite: {
-    transportJSON: (logObj: unknown) => {
-      process.stderr.write(JSON.stringify(logObj) + "\n")
+    transportJSON: (_logObj: unknown) => {
+      // Silenced: revela runs as an OpenCode plugin; writing to stderr
+      // pollutes the host terminal. Logs are intentionally suppressed.
     },
   },
 })

package/lib/qa/checks.ts

@@ -1,15 +1,17 @@
 /**
  * lib/qa/checks.ts
  *
- * Geometry-based layout quality checks — four orthogonal visual dimensions.
+ * Geometry-based layout quality checks — four orthogonal visual dimensions,
+ * plus a design-compliance dimension that verifies CSS class usage.
  *
- * Dimension 1: Overflow   — elements exceed canvas bounds (correctness)
- * Dimension 2: Balance    — content centroid & distribution (fill, sparsity)
- * Dimension 3: Symmetry   — side-by-side element consistency (height, density)
- * Dimension 4: Rhythm     — spacing regularity & internal whitespace
+ * Dimension 1: Overflow    — elements exceed canvas bounds (correctness)
+ * Dimension 2: Balance     — content centroid & distribution (fill, sparsity)
+ * Dimension 3: Rhythm      — spacing regularity & internal whitespace
+ * Dimension 4: Compliance  — CSS classes match the active design's vocabulary
  *
  * All checks operate on SlideMetrics produced by measure.ts.
- * Design-system-agnostic: no CSS class-name assumptions.
+ * Dimensions 1–4 are geometry-only (no CSS class-name assumptions).
+ * Dimension 5 requires an allowedClasses vocabulary from the design system.
  */
 
 import type { SlideMetrics, ElementInfo, Rect } from "./measure"
@@ -20,11 +22,12 @@ import { CANVAS_W, CANVAS_H } from "./measure"
 export type IssueSeverity = "error" | "warning" | "info"
 
 export interface LayoutIssue {
-  type: "overflow" | "balance" | "symmetry" | "rhythm"
+  type: "overflow" | "balance" | "symmetry" | "rhythm" | "compliance"
   /** Sub-category within the dimension */
   sub?: "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
+      | "unknown_class" | "novel_css_rule"
   severity: IssueSeverity
   /** Human-readable description for the LLM to act on */
   detail: string
@@ -520,20 +523,137 @@ 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 ───────────────────────────────────────────────────────────────
 
 /**
- * Run all four dimension checks on a set of slide metrics and produce a QA report.
+ * Options for runChecks(). All fields are optional — omitting them disables
+ * the corresponding checks (backward compatible).
+ */
+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[]
+}
+
+/**
+ * Run all dimension checks on a set of slide metrics and produce a QA report.
  */
-export function runChecks(filePath: string, allMetrics: SlideMetrics[]): QAReport {
+export function runChecks(
+  filePath: string,
+  allMetrics: SlideMetrics[],
+  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),
-      ...checkSymmetry(metrics),
       ...checkRhythm(metrics),
+      ...complianceIssues,
+      // Attach novel_css_rule issues to slide 0 only
+      ...(metrics.index === 0 ? novelCssIssues : []),
     ]
 
     slides.push({ index: metrics.index, title: metrics.title, issues })
@@ -594,9 +714,9 @@ export function formatReport(report: QAReport): string {
     `- **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.`,
-    `- **symmetry/height_mismatch**: equalise side-by-side column heights — use \`align-items: stretch\` or match content density.`,
-    `- **symmetry/density_mismatch**: balance content between columns — add items to the sparse column or reduce items in the dense one.`,
     `- **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.`,
   )
 
   return lines.join("\n")

package/lib/qa/index.ts

@@ -7,31 +7,49 @@
 
 import { measureSlides } from "./measure"
 import { runChecks, formatReport } from "./checks"
-import type { QAReport } from "./checks"
+import type { QAReport, RunChecksOptions } 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`.
  *
  * 1. Opens the file in headless Chrome (puppeteer-core)
- * 2. Measures each .slide element's geometry
- * 3. Runs all checks (fill, whitespace, overflow, asymmetry, sparse)
+ * 2. Measures each .slide element's geometry + CSS class definitions
+ * 3. Runs all checks (overflow, balance, symmetry, rhythm, compliance)
  * 4. Returns a structured QAReport
  *
+ * Pass `vocabulary` (from `extractDesignClasses()`) to enable compliance checks.
+ * Omit it to run geometry-only checks (backward compatible).
+ *
  * Throws if the file cannot be opened or Chrome is not found.
  */
-export async function runQA(htmlFilePath: string): Promise<QAReport> {
-  const metrics = await measureSlides(htmlFilePath)
-  return runChecks(htmlFilePath, metrics)
+export async function runQA(
+  htmlFilePath: string,
+  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)
 }
 
 /**
  * Run QA and return a formatted markdown report string.
  * Suitable for injecting into tool output or sending as a message to the LLM.
  */
-export async function runQAFormatted(htmlFilePath: string): Promise<string> {
-  const report = await runQA(htmlFilePath)
+export async function runQAFormatted(
+  htmlFilePath: string,
+  vocabulary?: DesignClassVocabulary,
+): Promise<string> {
+  const report = await runQA(htmlFilePath, vocabulary)
   return formatReport(report)
 }
 

package/lib/qa/measure.ts

@@ -47,6 +47,8 @@ export interface ElementInfo {
   visible: boolean
   /** direct children that are also visible */
   children: ElementInfo[]
+  /** all CSS class names on this element */
+  classList: string[]
 }
 
 export interface SlideMetrics {
@@ -69,6 +71,16 @@ export interface SlideMetrics {
   contentRect: Rect
 }
 
+/**
+ * Result returned by measureSlides().
+ * Contains per-slide geometry data and CSS class names defined in <style> blocks.
+ */
+export interface MeasurementResult {
+  slides: SlideMetrics[]
+  /** All CSS class names defined in <style> blocks of the HTML (deduplicated). */
+  cssDefinedClasses: string[]
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function findChromePath(): string {
@@ -86,9 +98,9 @@ function findChromePath(): string {
 
 /**
  * Open `htmlFilePath` in a headless Chrome at 1920×1080, measure each slide,
- * and return an array of SlideMetrics (one per .slide element).
+ * and return slide geometry + CSS class names defined in <style> blocks.
  */
-export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[]> {
+export async function measureSlides(htmlFilePath: string): Promise<MeasurementResult> {
   const executablePath = findChromePath()
   const fileUrl = pathToFileURL(htmlFilePath).href
 
@@ -106,9 +118,22 @@ export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[
   try {
     const page = await browser.newPage()
 
+    // Block all external (http/https) requests — fonts, CDN scripts, images.
+    // QA checks are purely geometry-based and do not require network resources.
+    // This makes measurement fast and reliable regardless of network conditions.
+    await page.setRequestInterception(true)
+    page.on("request", (req) => {
+      const url = req.url()
+      if (url.startsWith("https://") || url.startsWith("http://")) {
+        req.abort()
+      } else {
+        req.continue()
+      }
+    })
+
     // Set viewport to exact canvas size so scale === 1 (no CSS transform needed).
     await page.setViewport({ width: CANVAS_W, height: CANVAS_H })
-    await page.goto(fileUrl, { waitUntil: "networkidle0", timeout: 30000 })
+    await page.goto(fileUrl, { waitUntil: "domcontentloaded", timeout: 15000 })
 
     // Wait for any entrance animations / intersection observers to fire.
     await new Promise((r) => setTimeout(r, 600))
@@ -181,6 +206,7 @@ export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[
             rect: ReturnType<typeof toRectRelative>
             visible: boolean
             children: EI[]
+            classList: string[]
           }
 
           function collectChildren(
@@ -208,6 +234,7 @@ export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[
                 selector: selectorOf(child),
                 rect: relR,
                 visible: true,
+                classList: Array.from(child.classList),
                 children: collectChildren(child, offsetTop, offsetLeft, depth + 1),
               })
             }
@@ -281,7 +308,30 @@ export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[
       if (slideData) metrics.push(slideData as SlideMetrics)
     }
 
-    return metrics
+    // Extract all CSS class names defined in <style> blocks.
+    // Uses the browser's CSSStyleRule API for reliable selector parsing.
+    const cssDefinedClasses = await page.evaluate((): string[] => {
+      const classes: string[] = []
+      const classRe = /\.([a-zA-Z_][\w-]*)/g
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            if (rule instanceof CSSStyleRule) {
+              let m: RegExpExecArray | null
+              classRe.lastIndex = 0
+              while ((m = classRe.exec(rule.selectorText)) !== null) {
+                classes.push(m[1])
+              }
+            }
+          }
+        } catch {
+          // Cross-origin or inaccessible sheets (e.g. external CDN) will throw
+        }
+      }
+      return [...new Set(classes)]
+    })
+
+    return { slides: metrics, cssDefinedClasses }
   } finally {
     await browser.close()
   }

package/package.json

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

package/plugin.ts

@@ -48,6 +48,7 @@ import workspaceScanTool from "./tools/workspace-scan"
 import qaTool from "./tools/qa"
 import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research-prompt"
 import { runQA, formatReport } from "./lib/qa"
+import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
 
 // OpenCode internal agent signatures — used to skip system prompt injection
@@ -111,6 +112,7 @@ const server: Plugin = (async (pluginCtx) => {
       // Permissions: read-only on edit/bash; write allowed to create researches/ files.
       // No model override — inherits from the calling primary agent.
       opencodeConfig.agent ??= {}
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       opencodeConfig.agent["revela-research"] = {
         description: "Revela research agent — searches and collects raw materials for presentations",
         mode: "subagent",
@@ -123,7 +125,19 @@ const server: Plugin = (async (pluginCtx) => {
             "ls": "allow",
           },
           webfetch: "allow",
-        },
+        } as any,
+      }
+      // Give revela-research explicit websearch allow (overrides global deny below)
+      ;(opencodeConfig.agent["revela-research"].permission as any).websearch = "allow"
+
+      // Block websearch for the primary agent globally.
+      // permission.ask hook is not triggered by OpenCode (no R.trigger call in binary).
+      // tool.execute.before throw is swallowed (trigger().catch(()=>{})).
+      // The only working mechanism is the config-level permission ruleset.
+      // revela-research agent overrides this with websearch: "allow" above.
+      opencodeConfig.permission ??= {}
+      if (!(opencodeConfig.permission as Record<string, unknown>)["websearch"]) {
+        ;(opencodeConfig.permission as Record<string, unknown>)["websearch"] = "deny"
       }
     },
 
@@ -283,22 +297,10 @@ const server: Plugin = (async (pluginCtx) => {
     // ── Pre-read: intercept binary files before read executes ──────────────
     // Handles DOCX/PPTX/XLSX — read tool would Effect.fail on these.
     // Extracts text → writes temp .txt → redirects args.filePath.
-    //
-    // Also blocks websearch for the primary agent — websearch must be delegated
-    // to the revela-research subagent. Use webfetch for specific URLs instead.
     "tool.execute.before": async (input, output) => {
+      log.info("[hook] tool.execute.before fired", { tool: input.tool, enabled: ctx.enabled, isResearch: ctx.isResearchAgent })
       if (!ctx.enabled) return
 
-      // ── Block websearch for primary agent ──────────────────────────────
-      if (input.tool === "websearch" && !ctx.isResearchAgent) {
-        throw new Error(
-          "[revela] websearch is not available for the primary agent. " +
-          "Delegate web research to the revela-research subagent via the Task tool — " +
-          "it searches systematically and saves structured findings for reuse across sessions. " +
-          "Use the webfetch tool if you need to read a specific URL directly.",
-        )
-      }
-
       if (input.tool !== "read") return
       try {
         await preRead(output.args)
@@ -338,7 +340,14 @@ const server: Plugin = (async (pluginCtx) => {
         if (!filePath.match(/slides\/[^/]+\.html$/)) return
 
         try {
-          const report = await runQA(filePath)
+          // 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)

package/skill/SKILL.md

@@ -34,9 +34,9 @@ Before writing any HTML, ask the user these questions **in a single message**
 
 If the user's first message already answers most of these, skip what's clear and
 only ask about what's missing. If the message is detailed enough, proceed directly
-to Phase 1.5.
+to Phase 2.
 
-### Phase 1.5 — Select Design
+### Phase 2 — Select Design
 
 Once you have the user's answers (especially topic, audience, and visual style),
 pick the best-fit design before generating slides.
@@ -58,16 +58,16 @@ pick the best-fit design before generating slides.
 
 4. Wait for the user's reply, then act:
    - **Confirmed** (e.g. "yes", "sure", "go ahead") → activate the recommended
-     design and proceed to Phase 2:
+     design and proceed to Phase 3:
      Call the `designs` tool with action `"activate"` and name `"<name>"`.
-   - **User names a different design** → activate that one instead, then Phase 2.
-   - **User says keep the current one** → skip the switch, proceed to Phase 2.
+   - **User names a different design** → activate that one instead, then Phase 3.
+   - **User says keep the current one** → skip the switch, proceed to Phase 3.
 
-Do not proceed to Phase 2 until the user has replied to the design question.
+Do not proceed to Phase 3 until the user has replied to the design question.
 
 ---
 
-### Phase 1.8 — Research-First Protocol (自主调研)
+### Phase 3 — Research-First Protocol (自主调研)
 
 **Always execute this phase — regardless of whether the user mentions reference
 files.** Your job is to proactively gather all available information before
@@ -83,26 +83,26 @@ Research layers are **NOT** a sequential fallback chain where you stop once
 │  LAUNCH TOGETHER (as your first action):    │
 │                                             │
 │  ┌──────────────┐  ┌─────────────────────┐  │
-│  │ Layer 1      │  │ Layer 2.5           │  │
+│  │ Layer 1      │  │ Layer 2             │  │
 │  │ Workspace    │  │ Research agents     │  │
 │  │ scan         │  │ (parallel per axis) │  │
 │  └──────────────┘  └─────────────────────┘  │
 │                                             │
 │  After both complete:                       │
 │  ┌──────────────┐                           │
-│  │ Layer 2      │  AI knowledge fills gaps  │
+│  │ Layer 3      │  AI knowledge fills gaps  │
 │  └──────────────┘                           │
 │                                             │
 │  Only if still missing:                     │
 │  ┌──────────────┐                           │
-│  │ Layer 3      │  Ask the user             │
+│  │ Layer 4      │  Ask the user             │
 │  └──────────────┘                           │
 └─────────────────────────────────────────────┘
 ```
 
-**Layer 1 and Layer 2.5 launch in parallel as the FIRST action after Phase 1.5.**
-Do not wait for Layer 1 results before launching Layer 2.5. Do not use Layer 2
-(AI knowledge) as an excuse to skip Layer 2.5.
+**Layer 1 and Layer 2 launch in parallel as the FIRST action after Phase 2.**
+Do not wait for Layer 1 results before launching Layer 2. Do not use Layer 3
+(AI knowledge) as an excuse to skip Layer 2.
 
 ---
 
@@ -119,15 +119,16 @@ extracts text from binary formats (PDF, Excel, Word, PowerPoint) — just call
 
 ---
 
-#### Layer 2.5 — Deep Research via Research Agents (MANDATORY)
+#### Layer 2 — Deep Research via Research Agents (MANDATORY)
 
 **This layer is mandatory whenever the `@revela-research` subagent (Task tool
 with `subagent_type: "revela-research"`) is available.** It is the primary
 research workhorse — not an optional enhancement.
 
-The research agent searches the web aggressively using `webfetch` on targeted
-URLs, reads workspace documents, and writes structured findings to a single
-file `researches/{topic-slug}/{axis-name}.md` in the workspace.
+The research agent searches the web using `websearch` for broad discovery and
+`webfetch` for depth on specific pages, reads workspace documents, and writes
+structured findings to a single file `researches/{topic-slug}/{axis-name}.md`
+in the workspace.
 
 ##### Parallelization Rule
 
@@ -160,7 +161,8 @@ List and read the findings files: `ls researches/{topic-slug}/`, then `read`
 each `.md` file. Each file contains structured `## Data`, `## Cases`,
 `## Images`, and `## Gaps` sections — use these directly as slide material.
 Cross-reference agent findings with workspace documents (Layer 1). Flag any
-contradictions.
+contradictions. Once all findings are read, proceed to Phase 4 to present the
+slide plan.
 
 **Anti-pattern — NEVER do this:**
 - Do NOT use `websearch` directly — it is blocked by the Revela plugin;
@@ -171,23 +173,23 @@ contradictions.
 
 ---
 
-#### Layer 2 — AI Knowledge (Supplementary)
+#### Layer 3 — AI Knowledge (Supplementary)
 
-After Layer 1 and Layer 2.5 results are in, use your training data to fill
+After Layer 1 and Layer 2 results are in, use your training data to fill
 remaining gaps: industry context, historical background, technical explanations.
 
 **Critical:** Always mark AI-sourced information with
 `[Source: AI 公开知识，建议核实]`. Never present AI knowledge as verified fact.
 
 This layer is supplementary — it adds context around the hard data from
-Layers 1 and 2.5. It must never be the primary source for quantitative claims
+Layers 1 and 2. It must never be the primary source for quantitative claims
 (market size, revenue, growth rates, etc.).
 
 ---
 
-#### Layer 3 — Ask the User (Last Resort Only)
+#### Layer 4 — Ask the User (Last Resort Only)
 
-Only ask the user for information that Layers 1, 2, and 2.5 cannot cover.
+Only ask the user for information that Layers 1, 2, and 3 cannot cover.
 When asking, first report what you already know:
 
 > 我已从 workspace 文档和在线调研中获取了以下信息：
@@ -210,7 +212,6 @@ When asking, first report what you already know:
 - **ALWAYS** decompose the topic into independent axes before launching agents
 - **ALWAYS** read each `researches/{slug}/{axis}.md` after agents complete
 - Use the `read` tool for all file types — binary formats are handled transparently
-
 ---
 
 ### Required Slide Structure
@@ -260,7 +261,41 @@ core rules and the visual design below.
 
 ---
 
-### Phase 2 — Generate
+### Phase 4 — Presentation Plan
+
+After all research is complete and findings have been read, present a detailed
+slide plan to the user **before writing any HTML**.
+
+Format the plan as a markdown table:
+
+| # | Title | Content Summary | Layout | Components |
+|---|-------|-----------------|--------|------------|
+| 1 | Cover | Topic title, subtitle, presenter, date | `cover` | `gradient-text`, `deco-blob`, `accent-line` |
+| 2 | Table of Contents | 5 chapter headings | `toc` | `toc-list` |
+| 3 | Market Background | Key problem, 3 pain points, $4.2B TAM | `two-col` | `evidence-list`, `card` |
+| 4 | Key Metrics | Growth 85%, TAM $12B, NPS 72 | `stats` | `stat-card ×3`, `gradient-text` |
+
+Rules for filling the table:
+- **Layout**: use the exact layout name from the Layout Index (e.g. `cover`, `two-col`, `card-grid`, `stats`)
+- **Components**: list component names from the Component Index — no CSS details
+  (e.g. `card ×3`, `stat-card`, `evidence-list`, `step-flow`, `quote-block`)
+- **Content Summary**: 1 sentence of actual content — specific numbers, key points, or
+  real data from research findings (not vague descriptions like "overview of topic")
+
+After the table, add one sentence explaining any notable layout choices if non-obvious.
+
+Then ask:
+> "Does this plan look good? I'll generate the HTML once you confirm — or let me know
+> if you'd like to adjust any slide."
+
+**Do not write any HTML until the user replies with confirmation.**
+
+- On confirmation → proceed to Phase 5
+- On change request → update the table and ask again
+
+---
+
+### Phase 5 — Generate
 
 Once you have enough information, generate the complete HTML file in one shot.
 
@@ -270,7 +305,7 @@ Once you have enough information, generate the complete HTML file in one shot.
   (e.g. "AI Future" → `slides/ai-future.html`)
 - The file must be completely self-contained (all CSS and JS inline)
 
-### Phase 3 — Iterate
+### Phase 6 — Iterate
 
 After generating, briefly tell the user:
 - The filename you wrote (e.g. `slides/ai-future.html`)
@@ -301,6 +336,42 @@ Follow these rules on every generation. They are non-negotiable.
   Never use any other icon library (no Font Awesome, no Heroicons, no Material Icons).
 - All JS methods must be **fully implemented** — no empty stubs, no `// TODO` comments.
 
+### Design Compliance — Strict Mode
+
+The active design defines a **closed vocabulary** of layouts and components.
+You MUST use ONLY the layouts and components listed in the Layout Index and
+Component Index injected into this prompt.
+
+**Layouts:** Every `<section class="slide">` must use exactly one layout class
+from the Layout Index. Do NOT invent custom grid or flex structures.
+
+**Components:** Every content block must use a component class from the
+Component Index. Do NOT create novel CSS classes for content elements.
+
+**`<style>` block — no new class rules.** The design already provides all
+necessary CSS (foundation, layouts, components). Your `<style>` block should
+contain only CSS rules copied verbatim from the design's sections. Never define
+a CSS class rule (`.my-custom-thing { ... }`) that is not in the design.
+
+**Inline `style=""` — minor adjustments only.** Inline styles are permitted
+for fine-tuning spacing and sizing (`margin`, `padding`, `gap`, `font-size`,
+`max-width`, `min-height`, `width`, `height`). They must NOT be used to
+define new visual effects — no custom `background-image`, `box-shadow`,
+`border-radius`, `color`, or layout structures via inline style.
+
+**CSS variables:** Use only `var(--xxx)` properties defined in
+`@design:foundation`. Do NOT define new custom properties.
+
+**Fetch before use:** Before generating any slide, call the `revela-designs`
+tool to fetch the full HTML/CSS for each layout and component you plan to
+use. Generate HTML that matches the fetched examples exactly.
+
+**No suitable component?** Adapt the *content* to fit the closest available
+component — never adapt the component structure to fit content.
+
+The QA system will automatically flag any unrecognised CSS class as a
+compliance warning after you write the file.
+
 ### Inline Editing
 
 **Always include inline editing** in every generated presentation. The complete
@@ -314,8 +385,9 @@ element selector list, and `window.getEditedHTML()` definition.
 - Always use the **original** file path in HTML `<img src>` for full-quality rendering
 - Never repeat the same image on multiple slides (logos: title + closing only)
 - Image compression is handled automatically by the server
-- **Use the active design's image components** (`.image-card`, `.card-img`, `.avatar`)
-  for displaying images — they provide proper rounded corners and cropping
+- **Use the active design's image components** for displaying images — they
+  provide proper rounded corners and cropping. Use inline `style=""` only for
+  minor sizing adjustments; do not create custom image container classes.
 
 ### Accessibility
 
@@ -333,13 +405,15 @@ element selector list, and `window.getEditedHTML()` definition.
 
 ### Visual Quality Rules
 
-**Layout Diversity** — choose components and layout based on content type, never
-default to a bullet list. The active design's **Composition Guide** suggests
-which components work well for each content pattern — consult it first.
+**Layout Diversity** — choose from the design's defined layouts and components
+based on content type, never default to a bullet list. The active design's
+**Composition Guide** suggests which components work well for each content
+pattern — consult it first.
 
 The active design's **Component Library** defines the HTML/CSS for each
 component, and **Layout Primitives** defines the grid/flex patterns for
-arranging them. Combine components and layouts freely to serve the content.
+arranging them. Combine the design's defined layouts and components to serve
+the content — never invent new ones.
 
 **Visual Hierarchy** — every slide must have exactly 1 dominant visual focal point.
 Forbidden: plain background + unstyled bullet list with zero decorative elements.

package/tools/qa.ts

@@ -12,6 +12,7 @@ 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:
@@ -42,7 +43,14 @@ export default tool({
     }
 
     try {
-      const report = await runQA(filePath)
+      // 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 formatted = formatReport(report)
 
       // Prepend a compact JSON summary for programmatic use if needed

package/tools/workspace-scan.ts

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin"
 import { readdirSync, statSync, existsSync } from "fs"
-import { join, relative, extname } from "path"
+import { join, relative, extname, resolve, sep, isAbsolute } from "path"
 
 const DOC_EXTENSIONS = new Set([
   ".pdf", ".docx", ".doc", ".xlsx", ".xls",
@@ -113,7 +113,22 @@ export default tool({
   async execute(args, context) {
     try {
       const workspaceDir = context.directory ?? process.cwd()
-      const scanRoot = args.path ? join(workspaceDir, args.path) : workspaceDir
+
+      // Validate and resolve scanRoot — must stay within workspaceDir
+      let scanRoot = workspaceDir
+      if (args.path) {
+        if (isAbsolute(args.path)) {
+          return JSON.stringify({ error: "path must be relative to workspace root" })
+        }
+        const candidate = join(workspaceDir, args.path)
+        const resolvedCandidate = resolve(candidate)
+        const resolvedWorkspace = resolve(workspaceDir)
+        if (resolvedCandidate !== resolvedWorkspace && !resolvedCandidate.startsWith(resolvedWorkspace + sep)) {
+          return JSON.stringify({ error: "path must be within workspace" })
+        }
+        scanRoot = candidate
+      }
+
       const maxDepth = args.max_depth ?? 6
 
       if (!existsSync(scanRoot)) {