@cyber-dash-tech/revela 0.18.15 → 0.18.16

package/lib/commands/designs-new.ts

@@ -74,6 +74,9 @@ const VISUAL_QUALITY_RULES = `Visual extraction and CSS quality rules:
 - Preserve composition, not just colors and shapes. If the reference is a bottom strip, compact badge, side rail, or sparse header mark, keep that scale and anchoring; do not enlarge it into a full-slide mascot or background unless requested.
 - Do not rewrite the entire base layout system from scratch. Preserve base layout/container CSS where possible; mainly change tokens, typography, component skins, and small decorative components.
 - Keep CSS scoped and boring. Prefer CSS variables and reusable classes over many one-off absolute-positioned selectors.
+- Treat the design as an executable visual system, not a mood board. Document grid, safe-area, spacing, type scale, surface, and chart tokens in \`@design:foundation\`.
+- Layouts must use declared slots and stable grid/flex containers. Do not fake alignment with scattered one-off absolute positioning when a layout grid should own placement.
+- Components must declare normal, dense, and long-copy behavior when relevant. Chart, table, media, and source-note components need stable container dimensions.
 - If a reference is flat vector, doodle, mascot, blob, line-art, or geometric illustration, prefer a self-contained SVG component with a fixed viewBox. CSS should place the SVG; the SVG should draw the motif.
 - If a reference is photography, UI screenshot, webpage, or product surface, do not convert it to SVG. Extract palette, type scale, spacing, layout rhythm, borders, and image treatment instead.
 - For SVG motifs: set a viewBox, keep all eyes/mouths/decorations inside that coordinate system, and document intended placement/scale in the component notes.
@@ -83,6 +86,8 @@ const PREVIEW_REQUIREMENTS = `Preview requirements:
 - \`preview.html\` must include a cover slide and a closing slide. Mark their \`<section class="slide">\` elements with \`data-slide-role="cover"\` and \`data-slide-role="closing"\`.
 - \`preview.html\` must define an explicit CSS rule for \`.slide-canvas\` with \`width: 1920px\` and \`height: 1080px\`; every direct \`.slide-canvas\` is the fixed 1920px x 1080px export surface.
 - \`preview.html\` must showcase every \`@component:*\` defined in \`DESIGN.md\`. Mark each showcased component with \`data-preview-component="<component-name>"\`.
+- \`preview.html\` should showcase every \`@layout:*\` defined in \`DESIGN.md\`. Mark each layout fixture with \`data-preview-layout="<layout-name>"\`.
+- Preview slides should act as test fixtures: include at least one normal content slide, one dense content slide, one chart/table or data slide when supported, mixed Chinese/English copy when relevant, and visible source-note behavior.
 - Do not save with \`revela-designs-author\` until every component has a corresponding preview marker. If a component is decorative or abstract, include a visible labeled sample state.
 - When the design supports chart styling, \`preview.html\` should include a 3x3 ECharts gallery with at least 9 chart examples. This is a preview quality requirement, not a validation blocker.`
 
@@ -133,11 +138,13 @@ Hard requirements:
 - \`DESIGN.md\` must include frontmatter with name, description, author, and version.
 - \`DESIGN.md\` must include valid \`@design\`, \`@layout\`, and \`@component\` markers.
 - \`DESIGN.md\` must include at least \`@design:foundation\`, \`@design:rules\`, one layout, and one component.
+- \`DESIGN.md\` should document the design contract: grid/safe-area, spacing scale, typography scale, surfaces, and chart tokens when charts are supported.
 - \`preview.html\` must be self-contained and directly openable in a browser.
 - \`preview.html\` must include an explicit CSS rule: \`.slide-canvas { width: 1920px; height: 1080px; }\`.
 - Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
 - \`preview.html\` must include \`data-slide-role="cover"\` and \`data-slide-role="closing"\` on slide sections.
 - \`preview.html\` must showcase every \`@component:*\` with \`data-preview-component="<component-name>"\` before saving.
+- \`preview.html\` should showcase every \`@layout:*\` with \`data-preview-layout="<layout-name>"\`.
 - Do not save anything until the user confirms the brief.
 
 Start now by interviewing the user. Keep the first question concise.`
@@ -173,11 +180,13 @@ Workflow:
 Hard requirements:
 - Preserve valid frontmatter and marker structure.
 - Preserve at least \`@design:foundation\`, \`@design:rules\`, one layout, and one component.
+- Preserve or add the design contract: grid/safe-area, spacing scale, typography scale, surfaces, and chart tokens when charts are supported.
 - \`preview.html\` must be self-contained and directly openable in a browser.
 - \`preview.html\` must include an explicit CSS rule: \`.slide-canvas { width: 1920px; height: 1080px; }\`.
 - Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
 - \`preview.html\` must include \`data-slide-role="cover"\` and \`data-slide-role="closing"\` on slide sections.
 - \`preview.html\` must showcase every \`@component:*\` with \`data-preview-component="<component-name>"\` before saving.
+- \`preview.html\` should showcase every \`@layout:*\` with \`data-preview-layout="<layout-name>"\`.
 - Do not save anything until the user confirms the edit brief.
 
 Start now by asking what the user wants to change in \`${name}\`.`

package/lib/design/designs.ts

@@ -92,6 +92,7 @@ export interface ValidateDesignPackageResult {
   components: string[]
   assets: DesignPackageAssetInfo[]
   errors: string[]
+  warnings: string[]
 }
 
 export interface DesignPackageAssetInput {
@@ -551,6 +552,7 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
 function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesignPackageResult {
   let name = nameInput
   const errors: string[] = []
+  const warnings: string[] = []
   try {
     name = normalizeDesignName(nameInput)
   } catch (e) {
@@ -605,6 +607,13 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
     if (missingComponents.length > 0) {
       errors.push(`preview.html must showcase every @component; missing: ${missingComponents.join(", ")}`)
     }
+    const missingLayoutPreviews = layouts.filter((layout) => !hasDataAttribute(preview, "data-preview-layout", layout))
+    if (missingLayoutPreviews.length > 0) {
+      warnings.push(`preview.html should mark layout fixtures with data-preview-layout; missing: ${missingLayoutPreviews.join(", ")}`)
+    }
+    const designText = hasDesignMd ? readFileSync(mdPath, "utf-8") : ""
+    const tokenWarnings = designContractTokenWarnings(`${designText}\n${preview}`)
+    warnings.push(...tokenWarnings)
   }
 
   return {
@@ -619,7 +628,22 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
     components,
     assets,
     errors,
+    warnings,
+  }
+}
+
+function designContractTokenWarnings(text: string): string[] {
+  const warnings: string[] = []
+  const checks = [
+    { label: "grid", pattern: /--grid-|grid columns|grid-column|column line|safe area|safe-area/i },
+    { label: "spacing", pattern: /--space-|spacing scale|baseline|rhythm unit|gap scale/i },
+    { label: "type scale", pattern: /--font-size-|type scale|typographic scale|line-height/i },
+    { label: "surface", pattern: /--surface|surface token|border token|shadow token/i },
+  ]
+  for (const check of checks) {
+    if (!check.pattern.test(text)) warnings.push(`DESIGN.md/preview.html should document ${check.label} design tokens or an equivalent contract`)
   }
+  return warnings
 }
 
 function designDraftDir(workspaceRoot: string, name: string): string {
@@ -764,6 +788,23 @@ export interface DesignInventoryComponent {
     acceptsChildren: boolean
     allowedChildren?: string[]
   }
+  contract?: DesignComponentContract
+}
+
+export interface DesignComponentContractVariant {
+  name: string
+  requiredDescendantClasses: string[]
+  repeatedItemClass?: string
+  requiredItemClasses?: string[]
+  requireAlternatingClasses?: string[]
+}
+
+export interface DesignComponentContract {
+  component: string
+  kind: "structure"
+  requiredRootClasses: string[]
+  variants: DesignComponentContractVariant[]
+  guidance: string
 }
 
 export interface DesignInventory {
@@ -838,17 +879,19 @@ export function generateComponentIndex(components: Record<string, string>): stri
     const desc = firstLine
       ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
       : ""
-    return `| \`${name}\` | ${desc} |`
+    const contract = inferComponentContract(name, body)
+    const contractLabel = contract ? "✓" : "—"
+    return `| \`${name}\` | ${contractLabel} | ${desc} |`
   })
 
   return [
     "### Component Index",
     "",
-    "| Component | Description |",
-    "|---|---|",
+    "| Component | Contract | Description |",
+    "|---|---|---|",
     ...rows,
     "",
-    "_Use `revela_design_read_component` with `component: \"<name>\"` to get full CSS/HTML for any component._",
+    "_Use `revela_design_read_component` with `component: \"<name>\"` to get full CSS/HTML and any structure contract for a component._",
   ].join("\n")
 }
 
@@ -908,12 +951,49 @@ export function getDesignInventory(designName?: string): DesignInventory {
       name: componentName,
       description: designBlockDescription(content),
       nesting: inferComponentNesting(componentName),
+      contract: inferComponentContract(componentName, content),
     })),
     assets: listDesignAssetsInDir(designDir),
     hasMarkers,
   }
 }
 
+export function extractDesignComponentContracts(designName?: string): DesignComponentContract[] {
+  const name = normalizeDesignName(designName || activeDesign())
+  const designDir = resolveDesignDir(name)
+  if (!designDir) return []
+  const mdPath = join(designDir, "DESIGN.md")
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { components, hasMarkers } = parseDesignSections(body)
+  if (!hasMarkers) return []
+  return Object.entries(components)
+    .map(([componentName, content]) => inferComponentContract(componentName, content))
+    .filter((contract): contract is DesignComponentContract => Boolean(contract))
+}
+
+function inferComponentContract(name: string, content: string): DesignComponentContract | undefined {
+  const mentions = (value: string) => content.includes(value)
+
+  if (name === "roadmap-vertical" && ["tjv-axis", "tjv-item", "tjv-axis-dot", "tjv-stem", "tjv-tip-dot", "tjv-label"].every(mentions)) {
+    return {
+      component: name,
+      kind: "structure",
+      requiredRootClasses: ["roadmap-vertical"],
+      variants: [{
+        name: "timeline-journey-vertical",
+        requiredDescendantClasses: ["tjv-axis"],
+        repeatedItemClass: "tjv-item",
+        requiredItemClasses: ["tjv-axis-dot", "tjv-stem", "tjv-tip-dot", "tjv-label"],
+        requireAlternatingClasses: ["tjv-item--left", "tjv-item--right"],
+      }],
+      guidance: "Use structured milestone props/content to render axis-dot -> stem -> tip-dot -> label rows. Do not hand-roll a simplified axis plus labels.",
+    }
+  }
+
+  return undefined
+}
+
 function inferLayoutSlots(name: string, content: string): string[] {
   const slots = new Set<string>()
   const known = ["fullbleed", "left", "right", "top", "bottom", "main", "footer", "content", "overlay", "center"]

package/lib/prompt-builder.ts

@@ -190,6 +190,10 @@ function buildDesignLayer(designName: string): string {
   const componentIndex = generateComponentIndex(components)
   if (componentIndex) {
     layerParts.push(componentIndex)
+    layerParts.push([
+      "Components marked `✓` in the Contract column have required internal structure.",
+      "Fetch the component details before using them and preserve the required DOM/classes instead of hand-rolling a simpler lookalike.",
+    ].join(" "))
   }
 
   // 5. On-demand note

package/lib/qa/artifact.ts

@@ -1,8 +1,11 @@
 import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "../deck-html/contract"
-import type { DesignClassVocabulary } from "../design/designs"
+import { activeDesign, extractDesignComponentContracts } from "../design/designs"
+import type { DesignClassVocabulary, DesignComponentContract } from "../design/designs"
 import { formatReport, runQA } from "./index"
 import { runComplianceQA } from "./compliance"
+import { runComponentContractQA } from "./component-contracts"
 import type { QAReport } from "./checks"
+import { basename, dirname } from "path"
 
 export interface ArtifactQAReport {
   file: string
@@ -24,6 +27,7 @@ export async function runArtifactQA(input: {
   workspaceRoot: string
   filePath: string
   vocabulary?: DesignClassVocabulary
+  componentContracts?: DesignComponentContract[]
 }): Promise<ArtifactQAReport> {
   const sections: string[] = []
   let hardErrorCount = 0
@@ -39,12 +43,25 @@ export async function runArtifactQA(input: {
     sections.push("**[deck HTML contract]**\n\n" + formatDeckHtmlContractReport(contract))
   }
 
-  const compliance = runComplianceQA(input.filePath, input.vocabulary)
-  const complianceErrors = hardErrors(compliance)
-  if (compliance.totalIssues > 0) {
-    hardErrorCount += complianceErrors
-    warningCount += warnings(compliance)
-    sections.push("**[component compliance]**\n\n" + formatReport(compliance))
+  if (shouldRunArtifactCompliance(input.filePath)) {
+    const compliance = runComplianceQA(input.filePath, input.vocabulary)
+    const complianceErrors = hardErrors(compliance)
+    if (compliance.totalIssues > 0) {
+      hardErrorCount += complianceErrors
+      warningCount += warnings(compliance)
+      sections.push("**[component compliance]**\n\n" + formatReport(compliance))
+    }
+  }
+
+  const componentContracts = input.componentContracts ?? componentContractsForArtifact(input.filePath)
+  if (componentContracts.length > 0) {
+    const componentContractReport = runComponentContractQA(input.filePath, componentContracts)
+    const contractErrors = hardErrors(componentContractReport)
+    if (componentContractReport.totalIssues > 0) {
+      hardErrorCount += contractErrors
+      warningCount += warnings(componentContractReport)
+      sections.push("**[component structure contracts]**\n\n" + formatReport(componentContractReport))
+    }
   }
 
   try {
@@ -69,6 +86,34 @@ export async function runArtifactQA(input: {
   }
 }
 
+function componentContractsForArtifact(filePath: string): DesignComponentContract[] {
+  const designName = designNameFromPreviewPath(filePath)
+  try {
+    return extractDesignComponentContracts(designName || activeDesign())
+  } catch {
+    return []
+  }
+}
+
+export function shouldRunArtifactCompliance(filePath: string): boolean {
+  return !isDesignPreviewFile(filePath)
+}
+
+function isDesignPreviewFile(filePath: string): boolean {
+  const normalizedPath = filePath.replace(/\\/g, "/")
+  if (basename(normalizedPath) !== "preview.html") return false
+  const parts = dirname(normalizedPath).split("/")
+  return parts.length >= 2 && parts[parts.length - 2] === "designs"
+}
+
+function designNameFromPreviewPath(filePath: string): string | undefined {
+  const normalizedPath = filePath.replace(/\\/g, "/")
+  if (basename(normalizedPath) !== "preview.html") return undefined
+  const parts = dirname(normalizedPath).split("/")
+  if (parts.length >= 2 && parts[parts.length - 2] === "designs") return parts[parts.length - 1]
+  return undefined
+}
+
 export function formatArtifactQAReport(report: ArtifactQAReport): string {
   const heading = report.passed ? "Artifact QA: PASSED" : "Artifact QA: FAILED"
   const summary = `**File:** \`${report.file}\`\n\n**Hard errors:** ${report.hardErrorCount}\n**Warnings:** ${report.warningCount}`

package/lib/qa/checks.ts

@@ -30,7 +30,7 @@ export interface LayoutIssue {
       | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
-      | "unknown_class" | "novel_css_rule"
+      | "unknown_class" | "novel_css_rule" | "component_contract"
       | "remote_url" | "refine_proxy" | "missing_file"
   severity: IssueSeverity
   /** Human-readable description for the LLM to act on */

package/lib/qa/component-contracts.ts

@@ -0,0 +1,90 @@
+import { readFileSync } from "fs"
+import type { DesignComponentContract } from "../design/designs"
+import type { LayoutIssue, QAReport, SlideReport } from "./checks"
+
+function stripTags(value: string): string {
+  return value.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim()
+}
+
+function extractTitle(html: string, index: number): string {
+  const match = /<(?:h1|h2|h3|title)\b[^>]*>([\s\S]*?)<\/(?:h1|h2|h3|title)>/i.exec(html)
+  const title = match ? stripTags(match[1]).slice(0, 80) : ""
+  return title || `Slide ${index + 1}`
+}
+
+function htmlHasClass(html: string, className: string): boolean {
+  const classAttrRe = /class\s*=\s*(["'])([\s\S]*?)\1/gi
+  let match: RegExpExecArray | null
+  while ((match = classAttrRe.exec(html)) !== null) {
+    if (match[2].split(/\s+/).includes(className)) return true
+  }
+  return false
+}
+
+function htmlUsesComponent(html: string, contract: DesignComponentContract): boolean {
+  if (new RegExp(`data-preview-component\\s*=\\s*["']${escapeRegExp(contract.component)}["']`, "i").test(html)) return true
+  return contract.requiredRootClasses.some((className) => htmlHasClass(html, className))
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function validateContract(html: string, contract: DesignComponentContract): LayoutIssue[] {
+  if (!htmlUsesComponent(html, contract)) return []
+
+  const variantFailures: string[] = []
+  for (const variant of contract.variants) {
+    const missing = [
+      ...variant.requiredDescendantClasses.filter((className) => !htmlHasClass(html, className)),
+      ...(variant.repeatedItemClass && !htmlHasClass(html, variant.repeatedItemClass) ? [variant.repeatedItemClass] : []),
+      ...(variant.requiredItemClasses ?? []).filter((className) => !htmlHasClass(html, className)),
+      ...(variant.requireAlternatingClasses ?? []).filter((className) => !htmlHasClass(html, className)),
+    ]
+    if (missing.length === 0) return []
+    variantFailures.push(`${variant.name}: missing ${missing.join(", ")}`)
+  }
+
+  return [{
+    type: "compliance",
+    sub: "component_contract",
+    severity: "error",
+    detail: `Component \`${contract.component}\` does not satisfy its design structure contract. ${contract.guidance}`,
+    data: {
+      component: contract.component,
+      variants: variantFailures.join(" | "),
+    },
+  }]
+}
+
+function summarize(filePath: string, slides: SlideReport[]): QAReport {
+  const totalIssues = slides.reduce((sum, slide) => sum + slide.issues.length, 0)
+  const errorCount = slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "error").length, 0)
+  const warningCount = slides.reduce((sum, slide) => sum + slide.issues.filter((issue) => issue.severity === "warning").length, 0)
+  const summary = totalIssues === 0
+    ? "All component structure contracts passed."
+    : `Found ${totalIssues} component contract issue(s): ${errorCount} error(s), ${warningCount} warning(s).`
+  return { file: filePath, slides, totalIssues, errorCount, warningCount, summary }
+}
+
+export function runComponentContractQA(htmlFilePath: string, contracts: DesignComponentContract[]): QAReport {
+  const html = readFileSync(htmlFilePath, "utf-8")
+  const sectionRe = /<section\b[\s\S]*?<\/section>/gi
+  const slides: SlideReport[] = []
+  let match: RegExpExecArray | null
+  let index = 0
+
+  while ((match = sectionRe.exec(html)) !== null) {
+    const chunk = match[0]
+    const issues = contracts.flatMap((contract) => validateContract(chunk, contract))
+    slides.push({ index, title: extractTitle(chunk, index), issues })
+    index++
+  }
+
+  if (slides.length === 0) {
+    const issues = contracts.flatMap((contract) => validateContract(html, contract))
+    slides.push({ index: 0, title: extractTitle(html, 0), issues })
+  }
+
+  return summarize(htmlFilePath, slides)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.18.15",
+  "version": "0.18.16",
   "description": "Codex-first CLI/MCP workspace for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",

package/plugins/revela/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "revela",
-  "version": "0.18.15",
-  "description": "Use Revela in Codex to specify, research, plan, make, review, and export trusted narrative decision artifacts.",
+  "version": "0.18.16",
+  "description": "Use Revela in Codex to specify, research, plan, make, and export trusted narrative decision artifacts.",
   "author": {
     "name": "cyber-dash-tech",
     "url": "https://github.com/cyber-dash-tech"
@@ -20,7 +20,7 @@
   "interface": {
     "displayName": "Revela",
     "shortDescription": "Trusted narrative artifacts from local sources and research.",
-    "longDescription": "Revela helps Codex route workspace workflows, capture requirements in spec.md, ingest local materials, save research findings, plan decks, generate HTML deck artifacts, review them, and export PDF/PPTX/PNG outputs while preserving source traceability.",
+    "longDescription": "Revela helps Codex route workspace workflows, capture requirements in spec.md, ingest local materials, save research findings, plan decks, generate HTML deck artifacts, open them in Codex Browser for annotation, and export PDF/PPTX/PNG outputs while preserving source traceability.",
     "developerName": "cyber-dash-tech",
     "category": "Productivity",
     "capabilities": [
@@ -31,7 +31,7 @@
       "Use Revela to route the next workflow step for this workspace.",
       "Use Revela to write a spec.md for this deck objective.",
       "Use Revela to make a deck from the deck plan.",
-      "Use Revela to review this deck artifact."
+      "Use Revela to export this deck artifact."
     ],
     "brandColor": "#2563EB"
   }

package/plugins/revela/hooks/revela_post_write_notice.ts

@@ -1,4 +1,5 @@
-import { dirname, resolve } from "path"
+import { basename, dirname, resolve } from "path"
+import { existsSync, readFileSync } from "fs"
 import { fileURLToPath, pathToFileURL } from "url"
 import { resolveRevelaRuntime } from "../mcp/runtime-resolver"
 
@@ -9,15 +10,13 @@ interface HookResult {
 
 export function extractDeckHtmlTargets(input: string): string[] {
   const targets = new Set<string>()
-  const patterns = [
-    /\bdecks\/[^\s"'`<>]+\.html\b/g,
-    /(?:^\*\*\* Update File: |^\*\*\* Add File: )([^\r\n]+decks\/[^\r\n]+\.html)\s*$/gm,
-  ]
+  const pattern = /(?:^\*\*\* Update File: |^\*\*\* Add File: )((?:[^\r\n]*\/)?decks\/[^\s"'`<>*?\r\n]+\.html)\s*$/gm
 
-  for (const pattern of patterns) {
+  for (const patch of patchPayloadsFromInput(input)) {
     let match: RegExpExecArray | null
-    while ((match = pattern.exec(input))) {
-      targets.add((match[1] ?? match[0]).trim())
+    while ((match = pattern.exec(patch))) {
+      const target = match[1].trim()
+      if (!target.includes("*") && !target.includes("?")) targets.add(target)
     }
   }
 
@@ -59,6 +58,32 @@ export function workspaceRootFromInput(input: string): string {
   return resolve(process.env.CODEX_WORKSPACE_ROOT || process.env.PWD || process.cwd())
 }
 
+function titleFromDeckHtml(absolutePath: string): string {
+  try {
+    if (!existsSync(absolutePath)) return basename(absolutePath)
+    const html = readFileSync(absolutePath, "utf-8")
+    const title = html.match(/<title[^>]*>([^<]+)<\/title>/i)?.[1]?.trim()
+    return title || basename(absolutePath)
+  } catch {
+    return basename(absolutePath)
+  }
+}
+
+export function formatDeckWebsiteCardHandoffNotice(workspaceRoot: string, target: string): string {
+  const absolutePath = resolve(workspaceRoot, target)
+  const deckUrl = pathToFileURL(absolutePath).href
+  const title = titleFromDeckHtml(absolutePath)
+  return [
+    "**Deck website card ready**",
+    "",
+    `Artifact QA passed for \`${target}\`. Reply with this standalone deck link so Codex renders an Open in Browser website card:`,
+    "",
+    `[${title}](${deckUrl})`,
+    "",
+    `If the card or direct \`file://\` navigation is unavailable, start a read-only local static server from the workspace root and link to \`http://127.0.0.1:<port>/${target}\` instead.`,
+  ].join("\n")
+}
+
 export async function runPostWriteChecks(input: string): Promise<HookResult> {
   const messages: string[] = []
   const deckTargets = extractDeckHtmlTargets(input)
@@ -97,11 +122,16 @@ export async function runPostWriteChecks(input: string): Promise<HookResult> {
   }
 
   for (const target of deckTargets) {
+    if (!existsSync(resolve(workspaceRoot, target))) continue
     const result = await runtimeModule.runDeckQa({ workspaceRoot, file: target })
     messages.push(result.markdown ?? JSON.stringify(result, null, 2))
     const notice = runtimeModule.formatArtifactQaUserNotice?.(result.report)
     if (notice) messages.push(notice)
-    if (!result.ok) ok = false
+    if (result.ok) {
+      messages.push(formatDeckWebsiteCardHandoffNotice(workspaceRoot, target))
+    } else {
+      ok = false
+    }
   }
 
   return { ok, messages }

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

@@ -296,7 +296,7 @@ const tools = [
   },
   {
     name: "revela_review_deck_read",
-    description: "Read-only aggregate Review diagnostics for a Revela HTML deck: artifact QA, deck-plan diagnostics, and export/readiness signals.",
+    description: "Compatibility-only read of aggregate Review diagnostics for a Revela HTML deck: artifact QA, deck-plan diagnostics, and export/readiness signals.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       file: requiredStringProp("Workspace-relative or absolute HTML deck path."),
@@ -305,7 +305,7 @@ const tools = [
   },
   {
     name: "revela_review_deck_open",
-    description: "Open a local Codex-backed Review UI for a Revela HTML deck from the current MCP server process.",
+    description: "Compatibility-only opener for the legacy local Codex-backed Review UI for a Revela HTML deck.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       file: requiredStringProp("Workspace-relative or absolute HTML deck path."),

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

@@ -11,7 +11,7 @@ Use this skill as the main Revela entrypoint in Codex. It should inspect intent
 
 - This is a non-mutating router.
 - It may inspect runtime, active design/domain, and workspace artifact status.
-- It must not write `spec.md`, save research findings, write `deck-plan.md`, generate deck HTML, open Review UI, or export artifacts.
+- It must not write `spec.md`, save research findings, write `deck-plan.md`, generate deck HTML, open deck browser views, or export artifacts.
 - Route quickly once the next workflow is clear.
 
 ## Required Tools
@@ -29,7 +29,7 @@ Use this skill as the main Revela entrypoint in Codex. It should inspect intent
 - `spec.md` exists but source support, material review, or findings are missing: use `revela-research`.
 - `spec.md` and sufficient findings exist but `deck-plan.md` is missing or needs normal authoring: use `revela-research` Planning Handoff.
 - Valid `deck-plan.md` exists and the user asks to make, generate, render, or update a deck: use `revela-make-deck`.
-- Existing deck artifact and the user asks to review, diagnose, QA, or refine: use `revela-review`.
+- Existing deck artifact and the user asks to review, annotate, diagnose, QA, or refine: use Codex Browser's native browsing/annotation flow. If the deck was not just generated, reply with the existing deck as a website card/link and use native annotations after it opens; route export requests to `revela-export`.
 - Existing deck artifact and the user asks for PDF, PPTX, or PNG output: use `revela-export`.
 - If the next step is still ambiguous after inspection, ask the smallest missing question and recommend the safest next specialist skill.
 
@@ -47,5 +47,5 @@ Report:
 - Do not write or patch files.
 - Do not do external web research.
 - Do not create or repair `spec.md` or `deck-plan.md`.
-- Do not generate, review, patch, or export deck artifacts.
+- Do not generate, annotate, patch, or export deck artifacts.
 - Do not install or activate designs or domains; route those requests to `revela-design` or `revela-domain`.

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

@@ -10,6 +10,7 @@ Use this skill when the user asks to create, customize, edit, validate, package,
 ## Contract
 
 - Designs define deck visual systems: rules, foundation, layouts, components, chart rules, and preview coverage.
+- Designs should define executable visual contracts, not only mood, fonts, and palettes. Capture grid/safe-area, spacing scale, type scale, surface behavior, chart tokens, component states, and preview fixtures in the design package.
 - Designs may include package-owned `assets/**` such as cover or closing backgrounds; design tools surface these as design elements, not source evidence.
 - When the user uploads or provides logo, cover, closing, background, texture, brand image, or similar design material, store it inside the design package with `revela_design_draft_create.assets`; use paths under `assets/**` only.
 - Generated `preview.html` must actually reference uploaded design assets with package-relative `assets/...` paths rather than describing them only in text.
@@ -53,11 +54,16 @@ Use `revela_design_create` only when the user explicitly requests direct local c
 - Use a kebab-case design name.
 - `DESIGN.md` must include valid frontmatter and complete design marker sections.
 - Include design rules, foundation guidance, at least one layout, and at least one component.
+- In `@design:foundation`, document the design contract: grid columns or layout rails, safe area, spacing/baseline scale, typography scale, surfaces/borders/shadows, and chart tokens when charts are supported.
+- Layouts must declare stable slots and use grid/flex structure as the source of alignment. Avoid one-off absolute positioning that bypasses the declared layout contract.
+- Components should describe normal, dense, and long-copy behavior where relevant. Chart, table, media, and source-note components need stable container dimensions.
 - Optional assets must live under `assets/**`; reference them as package-relative paths like `assets/cover-background.png`.
 - `DESIGN.md` may reference package assets in rules, layouts, or components with `assets/...`; do not reference workspace `assets/` media manifest entries for design-owned visuals.
 - `preview.html` must use the fixed Revela preview canvas contract and visibly preview the design.
 - If design assets are present, `preview.html` must visibly use the saved `assets/...` files, for example a cover hero background or logo image.
 - Preview must include cover and closing examples and showcase every component.
+- Preview should showcase every layout with `data-preview-layout="<layout-name>"` and every component with `data-preview-component="<component-name>"`.
+- Preview should behave like a design test fixture: include normal content, dense content, mixed-language text where relevant, chart/table examples when supported, readable media, and source-note behavior.
 - Preserve source inspiration and limitations explicitly; do not copy copyrighted design text or assets into the package.
 
 ## Outputs

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

@@ -12,7 +12,7 @@ Use this skill when the user asks what Revela is, what the current workspace sta
 - This is a read-only helper and orientation surface.
 - `revela` is the main workflow router; this skill explains status and capabilities.
 - It may inspect runtime, design, domain, and workspace artifact status.
-- It must not perform research, write files, create `spec.md`, create `deck-plan.md`, generate decks, open Review UI, or export artifacts.
+- It must not perform research, write files, create `spec.md`, create `deck-plan.md`, generate decks, open deck browser views, or export artifacts.
 - Keep the answer short and operational.
 
 ## Preconditions
@@ -46,7 +46,7 @@ Report:
   - `spec.md` exists but no `researches/`: run `revela-research`.
   - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
   - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
-  - Existing deck artifact: run `revela-review` or `revela-export` depending on the user goal.
+  - Existing deck artifact: surface the HTML deck as a website card/link for Codex Browser native annotation, or run `revela-export` for PDF/PPTX/PNG.
 
 ## Must Not
 
@@ -54,5 +54,5 @@ Report:
 - Do not do external web research.
 - Do not generate or repair `spec.md`.
 - Do not generate or repair `deck-plan.md`.
-- Do not generate, review, patch, or export deck artifacts.
+- Do not generate, annotate, patch, or export deck artifacts.
 - Do not create, install, or activate designs or domains; route those requests to `revela-design` or `revela-domain`.