@cyber-dash-tech/revela 0.1.2 → 0.1.3

package/README.md

@@ -148,7 +148,7 @@ Checks performed on every slide:
 | **Density imbalance** | Columns where CSS `align-items: stretch` hides content imbalance |
 | **Sparse** | Slides with too few visible elements |
 
-Cover, TOC, divider, summary, and closing slides are automatically exempted from fill/spacing checks via the `data-slide-type` attribute.
+Structural slides (cover, TOC, quote, summary, closing) set `slide-qa="false"` and are automatically exempted from fill/spacing checks. Content-heavy slides set `slide-qa="true"` to opt in.
 
 You can also invoke QA manually: ask the AI to "run QA on slides/my-deck.html" or use the `revela-qa` tool directly.
 

package/README.zh-CN.md

@@ -179,7 +179,7 @@ OPENCODE_ENABLE_EXA=1 opencode
 | **密度失衡** | CSS `align-items: stretch` 列布局中隐藏的内容不平衡 |
 | **稀疏** | 可见元素过少的幻灯片 |
 
-封面、目录、分隔、总结、结语幻灯片通过 `data-slide-type` 属性自动豁免填充/间距检查。
+结构性幻灯片（封面、目录、引言、总结、结语）设置 `slide-qa="false"`，自动豁免填充/间距检查。内容型幻灯片设置 `slide-qa="true"` 启用 QA 检查。
 
 也可以手动触发：让 AI "对 slides/my-deck.html 运行 QA"，或直接使用 `revela-qa` 工具。
 

package/lib/config.ts

@@ -28,7 +28,7 @@ export const CONFIG_FILE = join(CONFIG_DIR, "config.json")
 export const ACTIVE_PROMPT_FILE = join(CONFIG_DIR, "_active-prompt.md")
 
 /** Default design name. */
-export const DEFAULT_DESIGN = "default"
+export const DEFAULT_DESIGN = "aurora"
 
 /** Default domain name. */
 export const DEFAULT_DOMAIN = "general"

package/lib/design/designs.ts

@@ -145,28 +145,41 @@ export function getDesignSkillMd(name?: string): string {
 // Marker-based section / component parsing
 // ---------------------------------------------------------------------------
 
+export interface LayoutInfo {
+  /** Full text content of the layout block (without marker lines). */
+  content: string
+  /** Whether this layout type should be QA-checked for balance/rhythm. */
+  qa: boolean
+}
+
 export interface DesignSections {
-  /** Map of section name → extracted content (without marker lines). */
+  /** Map of @design:<name> section → extracted content (without marker lines). */
   sections: Record<string, string>
-  /** Map of component name → extracted content (without marker lines). */
+  /** Map of @layout:<name> → LayoutInfo with content + qa flag. */
+  layouts: Record<string, LayoutInfo>
+  /** Map of @component:<name> → extracted content (without marker lines). */
   components: Record<string, string>
   /** Whether the DESIGN.md has any markers at all. */
   hasMarkers: boolean
 }
 
 /**
- * Parse a DESIGN.md body (no frontmatter) into sections and components
- * using the two-layer HTML comment marker convention:
- *   <!-- @section:<name>:start --> … <!-- @section:<name>:end -->
+ * Parse a DESIGN.md body (no frontmatter) into sections, layouts, and components
+ * using the three-layer HTML comment marker convention:
+ *   <!-- @design:<name>:start --> … <!-- @design:<name>:end -->
+ *   <!-- @layout:<name>:start qa=true|false --> … <!-- @layout:<name>:end -->
  *   <!-- @component:<name>:start --> … <!-- @component:<name>:end -->
  *
+ * The `qa` attribute on layout markers defaults to `true` when omitted.
  * Returns an object with empty maps and hasMarkers=false when no markers found.
  */
 export function parseDesignSections(body: string): DesignSections {
   const sections: Record<string, string> = {}
+  const layouts: Record<string, LayoutInfo> = {}
   const components: Record<string, string> = {}
 
-  const sectionRe = /<!--\s*@section:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@section:\1:end\s*-->/g
+  const sectionRe   = /<!--\s*@design:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@design:\1:end\s*-->/g
+  const layoutRe    = /<!--\s*@layout:(\w[\w-]*):start(?:\s+qa=(true|false))?\s*-->([\s\S]*?)<!--\s*@layout:\1:end\s*-->/g
   const componentRe = /<!--\s*@component:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@component:\1:end\s*-->/g
 
   let hasMarkers = false
@@ -177,12 +190,20 @@ export function parseDesignSections(body: string): DesignSections {
     sections[match[1]] = match[2].trim()
   }
 
+  while ((match = layoutRe.exec(body)) !== null) {
+    hasMarkers = true
+    const qaAttr = match[2]
+    // qa defaults to true when attribute is omitted
+    const qa = qaAttr === "false" ? false : true
+    layouts[match[1]] = { content: match[3].trim(), qa }
+  }
+
   while ((match = componentRe.exec(body)) !== null) {
     hasMarkers = true
     components[match[1]] = match[2].trim()
   }
 
-  return { sections, components, hasMarkers }
+  return { sections, layouts, components, hasMarkers }
 }
 
 /**
@@ -219,6 +240,75 @@ export function generateComponentIndex(components: Record<string, string>): stri
   ].join("\n")
 }
 
+/**
+ * Generate a compact Layout Index table from parsed layouts.
+ * Lists each layout name with the QA flag and a one-line description.
+ */
+export function generateLayoutIndex(layouts: Record<string, LayoutInfo>): string {
+  const names = Object.keys(layouts)
+  if (names.length === 0) return ""
+
+  const rows = names.map((name) => {
+    const { content, qa } = layouts[name]
+    const firstLine = content
+      .split("\n")
+      .map((l) => l.trim())
+      .find((l) => l && !l.startsWith("<!--") && !l.startsWith("```"))
+    const desc = firstLine
+      ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
+      : ""
+    const qaIcon = qa ? "✓" : "—"
+    return `| \`${name}\` | ${qaIcon} | ${desc} |`
+  })
+
+  return [
+    "### Layout Index",
+    "",
+    "| Layout | QA | Description |",
+    "|---|---|---|",
+    ...rows,
+    "",
+    "_Use `revela-designs` tool with `action: \"read\"` and `layout: \"<name>\"` to get full HTML/CSS for any layout._",
+  ].join("\n")
+}
+
+/**
+ * Get the raw text of one or more named layouts from a DESIGN.md.
+ * @param layoutNames - Comma-separated layout names or an array.
+ * @param designName - Design to read from (defaults to active).
+ */
+export function getDesignLayout(
+  layoutNames: string | string[],
+  designName?: string,
+): string {
+  const name = designName || activeDesign()
+  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
+  if (!existsSync(mdPath)) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { layouts, hasMarkers } = parseDesignSections(body)
+
+  if (!hasMarkers) {
+    throw new Error(`Design '${name}' has no markers — use getDesignSkillMd() for full text`)
+  }
+
+  const names = Array.isArray(layoutNames)
+    ? layoutNames
+    : layoutNames.split(",").map((s) => s.trim())
+
+  const parts: string[] = []
+  for (const layoutName of names) {
+    if (!(layoutName in layouts)) {
+      throw new Error(`Layout '${layoutName}' not found in design '${name}'`)
+    }
+    const { content, qa } = layouts[layoutName]
+    parts.push(`### Layout: ${layoutName} (qa=${qa})\n\n${content}`)
+  }
+  return parts.join("\n\n---\n\n")
+}
+
 /**
  * Get the raw text of a named section from a DESIGN.md.
  * Throws if the design is not installed or the section doesn't exist.

package/lib/prompt-builder.ts

@@ -29,10 +29,10 @@ import {
   getDesignSkillMd,
   parseDesignSections,
   generateComponentIndex,
+  generateLayoutIndex,
 } from "./design/designs"
 import { activeDomain, getDomainSkillMd } from "./domain/domains"
 import { parseFrontmatter } from "./frontmatter"
-import { SLIDE_TYPES, type SlideType } from "./qa/checks"
 import { childLog } from "./log"
 
 const promptLog = childLog("prompt-builder")
@@ -40,21 +40,6 @@ const promptLog = childLog("prompt-builder")
 /** Path to SKILL.md shipped with this package. */
 const SKILL_MD_PATH = resolve(__dirname, "..", "skill", "SKILL.md")
 
-/**
- * Human-readable descriptions for each slide type.
- * Used to generate the data-slide-type table injected into SKILL.md.
- * Kept here (not in checks.ts) — these are prose for the AI, not QA logic.
- */
-const SLIDE_TYPE_DESCRIPTIONS: Record<SlideType, string> = {
-  cover: "Title / opening slide",
-  toc: "Table of contents",
-  content: "Regular content slides (default)",
-  summary: "Key takeaways slide",
-  closing: "Thank-you / Q&A / contact slide",
-  divider: "Section-break / transition slide",
-  "thank-you": "Alias for `closing`",
-}
-
 /**
  * Build the combined system prompt and write it to _active-prompt.md.
  *
@@ -66,9 +51,8 @@ export function buildPrompt(designName?: string, domainName?: string): string {
   const design = designName || activeDesign()
   const domain = domainName || activeDomain()
 
-  // Layer 1 — SKILL.md (with dynamic slide-type table injected)
-  let coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
-  coreSkill = injectSlideTypes(coreSkill)
+  // Layer 1 — SKILL.md
+  const coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
 
   // Check for preview.html
   const designDir = join(DESIGNS_DIR, design)
@@ -121,13 +105,14 @@ export function buildPrompt(designName?: string, domainName?: string): string {
  * Build the design layer text.
  *
  * If the DESIGN.md has markers:
- *   - Always include @section:global
- *   - Always include @section:layouts (layout primitives — always needed)
- *   - Include a generated Component Index table (lightweight catalog)
- *   - Omit @section:components detail, @section:charts, @section:guide
+ *   - Always include @design:foundation (colors, fonts, CSS, JS, HTML skeleton)
+ *   - Always include @design:rules (composition rules, do/don't — always resident)
+ *   - Always include generated Layout Index (with QA column)
+ *   - Always include generated Component Index
+ *   - Omit individual layout details, component details, @design:chart-rules
  *     (available on demand via revela-designs tool)
  *
- * If no markers: return the full DESIGN.md body unchanged.
+ * If no markers: return the full DESIGN.md body unchanged (backward compat).
  */
 function buildDesignLayer(designName: string): string {
   const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
@@ -137,7 +122,7 @@ function buildDesignLayer(designName: string): string {
 
   const raw = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(raw)
-  const { sections, components, hasMarkers } = parseDesignSections(body)
+  const { sections, layouts, components, hasMarkers } = parseDesignSections(body)
 
   if (!hasMarkers) {
     // Backward-compatible: full text injection
@@ -146,23 +131,29 @@ function buildDesignLayer(designName: string): string {
 
   const layerParts: string[] = []
 
-  // 1. Global section (colors, typography, CSS, JS class, HTML structure)
-  if (sections["global"]) {
-    layerParts.push(sections["global"])
+  // 1. Foundation section (colors, typography, CSS vars, JS, HTML skeleton)
+  if (sections["foundation"]) {
+    layerParts.push(sections["foundation"])
+  }
+
+  // 2. Rules section (composition rules, do/don't — always resident)
+  if (sections["rules"]) {
+    layerParts.push(sections["rules"])
   }
 
-  // 2. Component Index — compact catalog
-  const index = generateComponentIndex(components)
-  if (index) {
-    layerParts.push(index)
+  // 3. Layout Index — compact catalog with QA column
+  const layoutIndex = generateLayoutIndex(layouts)
+  if (layoutIndex) {
+    layerParts.push(layoutIndex)
   }
 
-  // 3. Layouts section — always resident (needed for every slide)
-  if (sections["layouts"]) {
-    layerParts.push(sections["layouts"])
+  // 4. Component Index — compact catalog
+  const componentIndex = generateComponentIndex(components)
+  if (componentIndex) {
+    layerParts.push(componentIndex)
   }
 
-  // 4. On-demand note
+  // 5. On-demand note
   layerParts.push(
     [
       "### On-Demand Design Sections",
@@ -172,23 +163,11 @@ function buildDesignLayer(designName: string): string {
       "",
       "| Section | Fetch with |",
       "|---|---|",
+      "| Layout HTML/CSS details | `layout: \"<name>\"` (see Layout Index above) |",
       "| Component CSS/HTML details | `component: \"<name>\"` (see Component Index above) |",
-      "| Data Visualization (ECharts) | `section: \"charts\"` |",
-      "| Composition Guide & Do/Don't | `section: \"guide\"` |",
+      "| Data Visualization (ECharts) | `section: \"chart-rules\"` |",
     ].join("\n"),
   )
 
   return layerParts.join("\n\n---\n\n")
 }
-
-/**
- * Replace the <!-- @slide-types --> placeholder in SKILL.md with a generated
- * markdown table built from SLIDE_TYPES (single source of truth in checks.ts).
- */
-function injectSlideTypes(skillMd: string): string {
-  const rows = SLIDE_TYPES.map(
-    (t) => `| \`${t}\` | ${SLIDE_TYPE_DESCRIPTIONS[t]} |`,
-  )
-  const table = ["| Value | Use for |", "|-------|---------|", ...rows].join("\n")
-  return skillMd.replace("<!-- @slide-types -->", table)
-}

package/lib/qa/checks.ts

@@ -47,41 +47,6 @@ export interface QAReport {
   summary: string
 }
 
-// ── Slide type registry — single source of truth ──────────────────────────────
-
-/**
- * All valid values for the `data-slide-type` attribute on `<section class="slide">`.
- *
- * Single source of truth consumed by:
- *   - QA checks (EXEMPT_TYPES below)
- *   - prompt-builder.ts (injected into SKILL.md via <!-- @slide-types --> placeholder)
- */
-export const SLIDE_TYPES = [
-  "cover",
-  "toc",
-  "content",
-  "summary",
-  "closing",
-  "divider",
-  "thank-you",
-] as const
-
-export type SlideType = (typeof SLIDE_TYPES)[number]
-
-/**
- * Slide types that are intentionally sparse, centred, or structurally
- * different from "content" slides. Balance and rhythm checks are skipped
- * for these types (overflow and symmetry still apply).
- */
-export const EXEMPT_TYPES: ReadonlySet<string> = new Set<SlideType>([
-  "cover",
-  "toc",
-  "closing",
-  "divider",
-  "summary",
-  "thank-you",
-])
-
 // ── Thresholds ────────────────────────────────────────────────────────────────
 
 const T = {
@@ -241,7 +206,8 @@ function checkOverflow(metrics: SlideMetrics): LayoutIssue[] {
 
 /**
  * Check 2: Balance — content centroid, bottom gap, sparsity.
- * Skipped for EXEMPT_TYPES (cover, closing, etc.).
+ * Only runs when `metrics.slideQa` is true (content-heavy layouts).
+ * Structural/sparse slides (cover, closing, etc.) set slide-qa="false" and are skipped.
  *
  * Sub-checks:
  *   - centroid_offset: weighted centroid deviates too far from canvas centre
@@ -263,17 +229,8 @@ function checkBalance(metrics: SlideMetrics): LayoutIssue[] {
     return issues
   }
 
-  // Exempt structural slides
-  if (metrics.slideType && EXEMPT_TYPES.has(metrics.slideType)) return []
-
-  // Geometry fallback for old HTML without data-slide-type:
-  // detect cover-like slides (single centred column)
-  const contentCenterX = (contentRect.left + contentRect.right) / 2
-  const canvasCenterX = canvasRect.width / 2
-  const centerOffsetFrac = Math.abs(contentCenterX - canvasCenterX) / canvasRect.width
-  const maxElemWidth = Math.max(...elements.map((e) => e.rect.width))
-  const isCoverLike = centerOffsetFrac < 0.15 && maxElemWidth < canvasRect.width * 0.65
-  if (isCoverLike) return []
+  // Skip balance checks for structural/sparse slides (slide-qa="false")
+  if (!metrics.slideQa) return []
 
   // ── Sub-check: sparse ────────────────────────────────────────────────────
   const visibleCount = elements.filter((e) => e.visible).length
@@ -500,8 +457,8 @@ function cv(values: number[]): number {
 function checkRhythm(metrics: SlideMetrics): LayoutIssue[] {
   const issues: LayoutIssue[] = []
 
-  // Exempt structural slides
-  if (metrics.slideType && EXEMPT_TYPES.has(metrics.slideType)) return []
+  // Skip rhythm checks for structural/sparse slides (slide-qa="false")
+  if (!metrics.slideQa) return []
 
   function checkContainer(els: ElementInfo[], containerSelector?: string) {
     if (els.length < 2) return

package/lib/qa/measure.ts

@@ -55,11 +55,12 @@ export interface SlideMetrics {
   /** slide title extracted from the first h1/h2 inside the slide */
   title: string
   /**
-   * Structural role from the slide's `data-slide-type` attribute.
-   * Valid values: "cover", "toc", "content", "closing", "divider", "summary".
-   * Undefined when the attribute is absent (old/third-party HTML).
+   * Whether this slide should be included in layout QA checks.
+   * Read from the `slide-qa` attribute on `<section class="slide">`.
+   * Defaults to `false` when the attribute is absent.
+   * Content-heavy layouts set `slide-qa="true"`; structural/sparse slides omit or use `"false"`.
    */
-  slideType?: string
+  slideQa: boolean
   /** bounding box of the slide-canvas element itself (post-scale) */
   canvasRect: Rect
   /** top-level visible children of .slide-canvas */
@@ -238,8 +239,8 @@ export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[
           const slide = document.querySelectorAll(".slide")[slideIdx]
           if (!slide) return null
 
-          // Read the semantic slide type if the author provided it
-          const slideType = (slide as HTMLElement).dataset.slideType || slide.getAttribute("data-slide-type") || undefined
+          // Read the QA flag — true means this slide gets balance/rhythm checks
+          const slideQa = (slide as HTMLElement).getAttribute("slide-qa") === "true"
 
           const canvas = slide.querySelector(".slide-canvas") as HTMLElement | null
           if (!canvas) return null
@@ -268,7 +269,7 @@ export async function measureSlides(htmlFilePath: string): Promise<SlideMetrics[
           return {
             index: slideIdx,
             title,
-            slideType,
+            slideQa,
             canvasRect,
             elements,
             contentRect: unionRect(elements),

package/package.json

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