@cyber-dash-tech/revela 0.17.4 → 0.17.6

package/designs/monet/DESIGN.md

@@ -481,6 +481,8 @@ These rules are mandatory for Monet.
 - **No glass cards, neon KPI styling, or startup-product chrome.** Monet is editorial and print-adjacent.
 - **Visual hierarchy is strict:** eyebrow -> heading -> body -> caption.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
+- **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
+- **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
 
 ### Common Mistakes
 
@@ -2805,3 +2807,30 @@ Rules:
 <!-- @component:roadmap-vertical:end -->
 
 <!-- @design:components:end -->
+
+<!-- @design:chart-rules:start -->
+
+### Data Visualization (ECharts)
+
+- Chart system is ECharts. Data charts should use `echarts.init()` with an `echart-panel` container, not hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts.
+- Monet charts should feel calm and art-book-like: soft contrast, restrained labels, limited series count, and no dashboard chrome, glow, or excessive gridlines.
+- Use `--accent-earth`, `--accent-olive`, `--accent-stone`, and `--accent-sage` for primary/supporting series. Use `--accent-danger` only for negative indicators. Derive colors from CSS variables with `getComputedStyle(document.documentElement)` instead of hard-coding unrelated palettes.
+- Keep chart containers inside `echart-panel` so QA can measure stable geometry. `.echart-container` must have stable sizing through explicit width/height or flex sizing with `min-height: 0`.
+- Give every chart a unique id. Initialise with `echarts.init()` after `SlidePresentation` is instantiated, and call `chart.resize()` on window resize.
+- Set `backgroundColor: "transparent"` in chart options. Set text, axis, legend, grid, and tooltip colors explicitly; ECharts canvas text does not inherit CSS reliably.
+- Always include a short chart caption or source note when data is shown.
+- Do not use fake chart fallback when ECharts runtime or chart rules are missing. Report the missing runtime/rules or use an approved local/runtime dependency.
+
+Recommended ECharts defaults:
+
+```javascript
+const styles = getComputedStyle(document.documentElement);
+const chartText = styles.getPropertyValue('--text-secondary').trim();
+const chartMuted = styles.getPropertyValue('--text-muted').trim();
+const chartLine = styles.getPropertyValue('--line').trim();
+const primary = styles.getPropertyValue('--accent-earth').trim();
+const secondary = styles.getPropertyValue('--accent-olive').trim();
+const soft = styles.getPropertyValue('--accent-sage').trim();
+```
+
+<!-- @design:chart-rules:end -->

package/designs/starter/DESIGN.md

@@ -234,6 +234,8 @@ new SlidePresentation();
 - **Reusable class vocabulary.** New classes must be documented in this DESIGN.md. Avoid many one-off selectors in generated decks.
 - **SVG is exceptional.** Use decorative SVG only when the user explicitly asks for an illustration/icon-like visual or when design authoring requires a motif.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
+- **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
+- **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
 - **Images for photographic references.** Use image treatment rules rather than fake SVG when the reference is photographic, UI, webpage, or product imagery.
 - **Content pages need a stable title block.** Except cover, TOC, closing, section divider, and full-bleed hero slides, every normal content slide should include a visible title block from the upper-left safe area. It should contain a compact chapter/section label plus a slide title written as the page's claim or takeaway.
 - **Do not hide the page title inside a card.** Body components may have their own headings, but the slide-level title block should remain separate and easy to scan unless the chosen layout explicitly defines a compact side-title variant.
@@ -881,11 +883,14 @@ Rules:
 
 ### Data Visualization (ECharts)
 
-- Use neutral chart styling by default: clean axes, limited series count, and restrained labels.
-- Use `--accent-primary` for the main series and `--accent-secondary` for supporting series.
-- Avoid dashboard chrome, glowing charts, and excessive gridlines.
+- Chart system is ECharts. Data charts should use `echarts.init()` with an `echart-panel` container, not hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts.
+- Use neutral chart styling by default: clean axes, limited series count, restrained labels, and transparent backgrounds.
+- Use `--accent-primary` for the main series and `--accent-secondary` for supporting series. Derive colors from CSS variables with `getComputedStyle(document.documentElement)` instead of hard-coding unrelated palettes.
+- Keep chart containers inside `echart-panel` so QA can measure stable geometry. `.echart-container` must have stable sizing through explicit width/height or flex sizing with `min-height: 0`.
+- Give every chart a unique id. Initialise with `echarts.init()` after `SlidePresentation` is instantiated, and call `chart.resize()` on window resize.
+- Set `backgroundColor: "transparent"` in chart options. Set text, axis, legend, grid, and tooltip colors explicitly; ECharts canvas text does not inherit CSS reliably.
 - Always include a short chart caption or source note when data is shown.
-- Keep chart containers inside `echart-panel` so QA can measure stable geometry.
+- Do not use fake chart fallback when ECharts runtime or chart rules are missing. Report the missing runtime/rules or use an approved local/runtime dependency.
 
 Recommended ECharts defaults:
 

package/designs/summit/DESIGN.md

@@ -444,6 +444,8 @@ These rules are mandatory for Summit.
 - **Titles are Title Case.** Do not set `text-transform:uppercase` on `h1`, `h2`, `h3`, or `h4` titles. Uppercase is reserved for eyebrows, captions, metadata labels, short codes, and date/code-like markers.
 - **Components are transparent by default.** Component primitives should not bring their own paper/background fill. Let `.page`, layout containers, or explicit modifier variants provide background color when needed.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
+- **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
+- **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
 
 ### Common Mistakes
 
@@ -2608,3 +2610,30 @@ Rules:
 <!-- @component:roadmap-vertical:end -->
 
 <!-- @design:components:end -->
+
+<!-- @design:chart-rules:start -->
+
+### Data Visualization (ECharts)
+
+- Chart system is ECharts. Data charts should use `echarts.init()` with an `echart-panel` container, not hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts.
+- Summit charts should feel editorial and report-like: calm typography, limited series count, restrained labels, and no dashboard chrome, glow, or excessive gridlines.
+- Use `--accent-earth`, `--accent-olive`, and `--accent-gold` for primary/supporting series. Use `--accent-danger` only for negative indicators. Derive colors from CSS variables with `getComputedStyle(document.documentElement)` instead of hard-coding unrelated palettes.
+- Keep chart containers inside `echart-panel` so QA can measure stable geometry. `.echart-container` must have stable sizing through explicit width/height or flex sizing with `min-height: 0`.
+- Give every chart a unique id. Initialise with `echarts.init()` after `SlidePresentation` is instantiated, and call `chart.resize()` on window resize.
+- Set `backgroundColor: "transparent"` in chart options. Set text, axis, legend, grid, and tooltip colors explicitly; ECharts canvas text does not inherit CSS reliably.
+- Always include a short chart caption or source note when data is shown.
+- Do not use fake chart fallback when ECharts runtime or chart rules are missing. Report the missing runtime/rules or use an approved local/runtime dependency.
+
+Recommended ECharts defaults:
+
+```javascript
+const styles = getComputedStyle(document.documentElement);
+const chartText = styles.getPropertyValue('--text-secondary').trim();
+const chartMuted = styles.getPropertyValue('--text-muted').trim();
+const chartLine = styles.getPropertyValue('--line').trim();
+const primary = styles.getPropertyValue('--accent-earth').trim();
+const secondary = styles.getPropertyValue('--accent-olive').trim();
+const highlight = styles.getPropertyValue('--accent-gold').trim();
+```
+
+<!-- @design:chart-rules:end -->

package/lib/commands/review.ts

@@ -93,11 +93,12 @@ Workflow:
 6. If target slide count, audience, language, output purpose, or visual style is unclear, ask the user for the smallest needed confirmation before writing the plan.
 7. Write \`deck-plan/index.md\` and one file per planned slide under \`deck-plan/slides/*.md\` from the planning packet and requirements. The index must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. Each slide file must include frontmatter with positive 1-based \`slideIndex\` and \`## Narrative Links\` using plain wikilinks to canonical claim/evidence/risk/objection/gap ids. Include a low-fidelity ASCII/text layout sketch for every slide; do not generate visual images or HTML mockups.
 8. Stop after presenting the plan unless the user already asked to proceed. Ask whether to continue, revise the plan, or run more research. Do not require an Approval block or \`confirmDeckPlan\` gate; \`confirmDeckPlan\` is compatibility/provenance only.
-9. Ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
-10. Do not update cached \`DECKS.json\` slide specs for plan authoring. Use \`deck-plan/\` files and artifact files as the execution surface.
-11. Call \`revela-decks\` action \`readDeckPlan\` before artifact review or HTML writing; use it to inspect the current deck-plan projection without regenerating it. Treat stale hashes, missing links, or incomplete coverage as advisory diagnostics unless the user asks to stop.
-12. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
-13. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
+9. Ask for or confirm visual design only after the narrative deck plan exists. For a new deck HTML file, call \`revela-deck-foundation\` first to create the active-design foundation shell; it must not create narrative slide content, choose layouts/components, or read/write \`${DECKS_STATE_FILE}\`.
+10. Fetch active design rules plus required layouts/components with \`revela-designs read\` as needed before patching slides into the foundation shell. Fetch chart rules before ECharts.
+11. Do not update cached \`DECKS.json\` slide specs for plan authoring. Use \`deck-plan/\` files and artifact files as the execution surface.
+12. Call \`revela-decks\` action \`readDeckPlan\` before artifact review or HTML writing; use it to inspect the current deck-plan projection without regenerating it. Treat stale hashes, missing links, or incomplete coverage as advisory diagnostics unless the user asks to stop.
+13. Run artifact diagnostics when useful, but do not treat \`writeReadiness\`, cached slide specs, unconfirmed plans, missing research, or stale coverage as workflow blockers.
+14. Write \`decks/*.html\` when the user chooses to proceed and all deck HTML contract requirements can be satisfied. For new files, patch slide sections between the \`revela-slides\` markers created by \`revela-deck-foundation\`. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Partial decks are allowed during chapter-by-chapter authoring when written slide sections have unique, increasing 1-based \`data-slide-index\` values and valid canvases; do not pad missing planned chapters with filler to match cached \`DECKS.json.slides[]\` length. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
 15. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
 16. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
 
@@ -142,6 +143,7 @@ Report format before any HTML write:
 - Start with \`Deck handoff: <status>\`.
 - Include which deck-plan projection and narrative hash are guiding artifact work.
 - State that \`revela-decks readDeckPlan\` was called and the current \`deck-plan/\` Chapter Writing Batches are being followed.
+- For new HTML files, state that \`revela-deck-foundation\` created the foundation shell and identify the output path/design before slide content is patched.
 - Include the chapter currently being generated and confirm already-written slides are being preserved.
 - If technical artifact checks cannot be satisfied, list those blockers separately from narrative/deck-plan diagnostics.
 - After writing HTML, read the appended \`Artifact QA\` report from the tool output. If it failed, fix hard errors before considering the deck ready for Review.
@@ -149,6 +151,7 @@ Report format before any HTML write:
 Rules:
 - \`compileDeckPlan\` prepares the canonical narrative claim/evidence packet and deck-plan requirements. The LLM authors \`deck-plan/index.md\` and \`deck-plan/slides/*.md\` from that packet and asks the user for page count, audience, language, output purpose, or visual style when unclear.
 - \`deck-plan/\` is the execution blueprint for HTML generation when present. It must be read before writing HTML and followed chapter by chapter; \`DECKS.json.slides[]\` is compatibility/cache data, not the HTML slide-count authority.
+- \`revela-deck-foundation\` is the file-native foundation helper for new deck shells. Use it before adding slides to a new \`decks/*.html\` file; do not use \`DECKS.json\` or \`revela-decks\` to create the shell.
 - Visual intent is part of the deck-plan projection. During HTML generation, satisfy the planned component/visual brief using fetched design components; do not collapse planned visuals into prose-only bullets.
 - Cached deck slide specs in \`DECKS.json\` are legacy projections only. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, and risks.
 - Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.

package/lib/deck-html/foundation.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs"
+import { dirname, isAbsolute, normalize, resolve } from "path"
+import { activeDesign, getDesignSection } from "../design/designs"
+
+export type DeckFoundationMode = "create" | "repair"
+export type DeckFoundationStatus = "created" | "updated"
+
+export interface CreateDeckFoundationInput {
+  workspaceRoot: string
+  outputPath: string
+  title: string
+  language: string
+  designName?: string
+  mode?: DeckFoundationMode
+  overwrite?: boolean
+}
+
+export interface CreateDeckFoundationResult {
+  ok: true
+  outputPath: string
+  design: string
+  includedSections: string[]
+  status: DeckFoundationStatus
+  next: string[]
+}
+
+interface FoundationParts {
+  fontLinks: string[]
+  cssBlocks: string[]
+  scriptBlocks: string[]
+}
+
+const SLIDES_START = "<!-- revela-slides:start -->"
+const SLIDES_END = "<!-- revela-slides:end -->"
+
+export function createDeckFoundation(input: CreateDeckFoundationInput): CreateDeckFoundationResult {
+  const outputPath = normalizeOutputPath(input.outputPath)
+  const targetPath = safeWorkspaceFilePath(input.workspaceRoot, outputPath)
+  const mode = input.mode ?? "create"
+  const canOverwrite = input.overwrite === true || mode === "repair"
+  const existed = existsSync(targetPath)
+
+  if (existed && !canOverwrite) {
+    throw new Error(`Deck HTML already exists at ${outputPath}. Pass overwrite=true or mode=repair to replace the foundation shell.`)
+  }
+
+  const design = input.designName || activeDesign()
+  const foundation = getDesignSection("foundation", design)
+  const parts = parseFoundationParts(foundation)
+  if (parts.cssBlocks.length === 0) throw new Error(`Design '${design}' foundation does not include a CSS code block.`)
+  if (parts.scriptBlocks.length === 0) throw new Error(`Design '${design}' foundation does not include a SlidePresentation JavaScript code block.`)
+
+  const html = renderFoundationHtml({
+    language: input.language || "en",
+    title: input.title || "Revela Deck",
+    fontLinks: parts.fontLinks,
+    css: parts.cssBlocks.join("\n\n"),
+    script: parts.scriptBlocks.map(guardEmptyDeckNavigation).join("\n\n"),
+  })
+
+  mkdirSync(dirname(targetPath), { recursive: true })
+  writeFileSync(targetPath, html, "utf-8")
+
+  return {
+    ok: true,
+    outputPath,
+    design,
+    includedSections: [
+      "design:foundation",
+      parts.fontLinks.length > 0 ? "foundation:font-links" : "foundation:font-links:none",
+      "foundation:css",
+      "foundation:SlidePresentation",
+    ],
+    status: existed ? "updated" : "created",
+    next: [
+      "Fetch active design rules before patching slides.",
+      "Fetch required layouts and components from the design before adding slide content.",
+      "Patch slides between the revela-slides markers chapter by chapter, then run artifact QA.",
+    ],
+  }
+}
+
+export function normalizeOutputPath(outputPath: string): string {
+  const trimmed = outputPath.trim()
+  if (!trimmed) throw new Error("outputPath is required")
+  if (!trimmed.endsWith(".html")) throw new Error("Deck foundation outputPath must end in .html")
+  if (isAbsolute(trimmed)) throw new Error("Deck foundation outputPath must be workspace-relative")
+  const segments = trimmed.split(/[\\/]+/)
+  if (segments.includes("..")) throw new Error("Deck foundation outputPath must not contain parent-directory traversal")
+  return normalize(trimmed).replace(/\\/g, "/")
+}
+
+function safeWorkspaceFilePath(workspaceRoot: string, outputPath: string): string {
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, outputPath)
+  if (target !== root && !target.startsWith(`${root}/`)) {
+    throw new Error("Deck foundation outputPath must stay inside the workspace")
+  }
+  return target
+}
+
+function parseFoundationParts(foundation: string): FoundationParts {
+  const fontLinks = extractFontLinks(foundation)
+  const cssBlocks: string[] = []
+  const scriptBlocks: string[] = []
+  const fenceRe = /```([\w-]*)\n([\s\S]*?)```/g
+  let match: RegExpExecArray | null
+
+  while ((match = fenceRe.exec(foundation)) !== null) {
+    const lang = (match[1] || "").toLowerCase()
+    const body = match[2].trim()
+    if (!body) continue
+    if (lang === "css") cssBlocks.push(body)
+    if ((lang === "javascript" || lang === "js") && body.includes("class SlidePresentation")) {
+      scriptBlocks.push(body)
+    }
+  }
+
+  return { fontLinks, cssBlocks, scriptBlocks }
+}
+
+function extractFontLinks(foundation: string): string[] {
+  const links: string[] = []
+  const seen = new Set<string>()
+  const linkRe = /<link\b[^>]*(?:fonts\.googleapis|fonts\.gstatic|rel=["']preconnect["'])[^>]*>/gi
+  let match: RegExpExecArray | null
+  while ((match = linkRe.exec(foundation)) !== null) {
+    const link = match[0].trim()
+    if (seen.has(link)) continue
+    seen.add(link)
+    links.push(link)
+  }
+  return links
+}
+
+function guardEmptyDeckNavigation(script: string): string {
+  return script.replace(
+    /new\s+SlidePresentation\s*\(\s*\)\s*;?/g,
+    'if (document.querySelector(".slide")) { new SlidePresentation(); }',
+  )
+}
+
+function renderFoundationHtml(input: {
+  language: string
+  title: string
+  fontLinks: string[]
+  css: string
+  script: string
+}): string {
+  const fontLinks = input.fontLinks.map((link) => `    ${link}`).join("\n")
+  return [
+    "<!DOCTYPE html>",
+    `<html lang="${escapeAttribute(input.language)}">`,
+    "<head>",
+    "    <meta charset=\"UTF-8\">",
+    "    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">",
+    `    <title>${escapeHtml(input.title)}</title>`,
+    fontLinks,
+    "    <style>",
+    input.css,
+    "    </style>",
+    "</head>",
+    "<body>",
+    `    ${SLIDES_START}`,
+    `    ${SLIDES_END}`,
+    "    <script>",
+    input.script,
+    "    </script>",
+    "</body>",
+    "</html>",
+    "",
+  ].filter((line) => line !== "").join("\n")
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+}
+
+function escapeAttribute(value: string): string {
+  return escapeHtml(value.trim() || "en")
+}
+
+export function deckFoundationMarkers(): { start: string; end: string } {
+  return { start: SLIDES_START, end: SLIDES_END }
+}

package/lib/edit/prompt.ts

@@ -79,6 +79,9 @@ Instructions:
 - Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, runtime JavaScript fixes, or deck HTML contract fixes may remain an artifact-level edit.
 - If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
+- Before patching ${"`decks/*.html`"}, call ${"`revela-designs`"} with ${"`action: \"read\"`"} and ${"`section: \"rules\"`"} to fetch the active design rules for this edit pass.
+- If the edit changes layout, component structure, typography scale, visual hierarchy, chart usage, icon usage, media treatment, or design-system classes, fetch the relevant ${"`revela-designs`"} layout/component details before editing. Fetch ${"`section: \"chart-rules\"`"} before changing or adding ECharts.
+- Follow the fetched design rules and vocabulary exactly. Do not invent layout classes, component names, CSS variables, icon systems, or visual effects from model memory or the existing deck alone.
 - If an asset/drop payload is present, this is an asset placement request. Use only the saved local asset path from the asset payload in deck HTML. Prefer asset.deckPath when present because it is relative to the target HTML file; otherwise use asset.path.
 - Do not write remote imageUrl, thumbnailUrl, source page URLs, or ${"`/__revela_asset`"} proxy URLs into deck HTML.
 - Logo assets should remain small, clear, and brand-like; do not use logos as decorative backgrounds.

package/lib/edit/server.ts

@@ -2,6 +2,8 @@ import { randomBytes } from "crypto"
 import { existsSync, readFileSync, statSync } from "fs"
 import { fileURLToPath } from "url"
 import { dirname, extname, isAbsolute, resolve, sep } from "path"
+import { ctx } from "../ctx"
+import { buildPrompt } from "../prompt-builder"
 import type { EditableDeck } from "./resolve-deck"
 import { buildEditPrompt, type EditCommentPayload } from "./prompt"
 
@@ -405,6 +407,9 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
   const elements = Array.isArray(body.elements) ? body.elements : []
   if (!comment && comments.length === 0) return jsonResponse({ ok: false, error: "Comment is required" }, 400)
 
+  ctx.enabled = true
+  buildPrompt({ mode: "deck-render" })
+
   const prompt = buildEditPrompt({
     ...body,
     deck: session.deck,

package/lib/qa/index.ts

@@ -79,6 +79,7 @@ function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
     const ref = raw.trim()
     if (!ref || ref.startsWith("data:") || ref.startsWith("#") || ref.startsWith("mailto:") || ref.startsWith("tel:")) continue
     if (/^https?:\/\//i.test(ref) || ref.startsWith("//")) {
+      if (isAllowedRemoteRuntimeRef(ref)) continue
       issues.push({ type: "asset", sub: "remote_url", severity: "error", detail: `Deck HTML references remote asset URL \`${ref}\`. Save network images to workspace assets and reference the local file instead.` })
       continue
     }
@@ -96,6 +97,17 @@ function scanAssetRefs(htmlFilePath: string): LayoutIssue[] {
   return issues
 }
 
+function isAllowedRemoteRuntimeRef(ref: string): boolean {
+  try {
+    const url = new URL(ref.startsWith("//") ? `https:${ref}` : ref)
+    if (url.hostname === "fonts.googleapis.com" || url.hostname === "fonts.gstatic.com") return true
+    if (url.hostname === "cdn.jsdelivr.net" && url.pathname.startsWith("/npm/echarts@")) return true
+  } catch {
+    return false
+  }
+  return false
+}
+
 function looksLikeImageRef(ref: string): boolean {
   return /\.(?:png|jpe?g|webp|gif|svg)(?:[?#].*)?$/i.test(ref)
 }

package/lib/refine/server.ts

@@ -2,8 +2,10 @@ import { randomBytes } from "crypto"
 import { existsSync, readFileSync, statSync } from "fs"
 import { fileURLToPath } from "url"
 import { dirname, extname, isAbsolute, relative, resolve, sep } from "path"
+import { ctx } from "../ctx"
 import type { EditableDeck } from "../edit/resolve-deck"
 import { buildEditPrompt, type EditCommentPayload } from "../edit/prompt"
+import { buildPrompt } from "../prompt-builder"
 import type { InspectionElementSnapshot } from "../inspection-context/match"
 import { buildInspectionPrompt } from "../inspect/prompt"
 import { projectWorkspaceElement } from "../inspect/request"
@@ -715,6 +717,9 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
   const elements = Array.isArray(body.elements) ? body.elements : []
   if (!comment && comments.length === 0) return jsonResponse({ ok: false, error: "Comment is required" }, 400)
 
+  ctx.enabled = true
+  buildPrompt({ mode: "deck-render" })
+
   const prompt = buildEditPrompt({
     ...body,
     deck: session.deck,

package/package.json

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

package/plugin.ts

@@ -81,6 +81,7 @@ import decksTool from "./tools/decks"
 import designsAuthorTool from "./tools/designs-author"
 import designsTool from "./tools/designs"
 import domainsTool from "./tools/domains"
+import deckFoundationTool from "./tools/deck-foundation"
 import mediaBatchSaveTool from "./tools/media-batch-save"
 import mediaSaveTool from "./tools/media-save"
 import researchImagesListTool from "./tools/research-images-list"
@@ -586,6 +587,7 @@ const server: Plugin = (async (pluginCtx) => {
     tool: {
       "revela-decks": decksTool,
       "revela-designs": designsTool,
+      "revela-deck-foundation": deckFoundationTool,
       "revela-designs-author": designsAuthorTool,
       "revela-domains": domainsTool,
       "revela-media-batch-save": mediaBatchSaveTool,

package/skill/SKILL.md

@@ -64,8 +64,13 @@ handoff exactly:
 5. Use `readDeckPlan` to inspect the current `deck-plan/` projection before
    artifact review or HTML generation. Diagnostics are advisory unless they are
    artifact validity errors handled by QA.
-6. Fetch the required design layouts/components with `revela-designs read`.
-7. Write HTML when the user proceeds and the deck contract can be satisfied.
+6. For a new deck HTML file, call `revela-deck-foundation` to create the
+   active-design foundation shell. The helper is file-native and must not create
+   narrative slide content, choose layouts/components, or read/write `DECKS.json`.
+7. Fetch the required design rules, layouts, and components with
+   `revela-designs read`.
+8. Patch slides between the foundation shell's `revela-slides` markers when the
+   user proceeds and the deck contract can be satisfied.
 
 Before any HTML generation, call `revela-decks` action `readDeckPlan` and follow
 the current `deck-plan/`: Source Authority, deck parameters, Chapter Writing
@@ -164,7 +169,8 @@ one broad `write`, `edit`, or `apply_patch` call.
 
 For decks with 5 or more slides:
 
-- First create a stable HTML shell plus structural slides and the first chapter.
+- First call `revela-deck-foundation` for new files, then patch structural
+  slides and the first chapter between the `revela-slides` markers.
 - Then fill or revise exactly one chapter range at a time.
 - Do not mix multiple central-claim chapters in the same write.
 - Chapter divider or chapter TOC slides are allowed as structural wayfinding and
@@ -193,14 +199,17 @@ If a write produces QA hard errors, fix them before continuing.
 Before writing or materially changing HTML:
 
 1. Read the deck-plan projection's layout and component names.
-2. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
+2. For a new deck HTML file, call `revela-deck-foundation` before adding slide
+   content. Use `mode: "repair"` only for explicit foundation repair or QA
+   foundation contract fixes, not normal Review Comment edits.
+3. Call `revela-designs` with `action: "read"` and `section: "rules"` to fetch
    the active design's current composition and usage rules.
-3. Call `revela-designs` with `action: "read"` and `layout` set to all required
+4. Call `revela-designs` with `action: "read"` and `layout` set to all required
    layout names, comma-separated.
-4. Call `revela-designs` with `action: "read"` and `component` set to all
+5. Call `revela-designs` with `action: "read"` and `component` set to all
    required component names, comma-separated.
-5. Fetch `section: "chart-rules"` before using ECharts.
-6. Do not update legacy `requiredInputs`; design fetching is an execution step,
+6. Fetch `section: "chart-rules"` before using ECharts.
+7. Do not update legacy `requiredInputs`; design fetching is an execution step,
    not a workflow permission gate.
 
 Never generate HTML from memory or prior knowledge of a design. Copy the fetched

package/tools/deck-foundation.ts

@@ -0,0 +1,48 @@
+import { tool } from "@opencode-ai/plugin"
+import { createDeckFoundation } from "../lib/deck-html/foundation"
+
+export default tool({
+  description:
+    "Create or repair a file-native Revela deck HTML foundation shell from the active design. " +
+    "Writes a deterministic empty deck shell with doctype, html/head/body, active design foundation CSS, complete SlidePresentation JavaScript, and stable slide insertion markers. " +
+    "It does not create narrative slide content, choose layouts/components, or read/write DECKS.json.",
+  args: {
+    outputPath: tool.schema
+      .string()
+      .describe("Workspace-relative HTML output path, usually decks/{name}.html."),
+    title: tool.schema
+      .string()
+      .describe("Presentation title for the HTML <title> tag only; this does not create a cover slide."),
+    language: tool.schema
+      .string()
+      .describe("HTML language tag, e.g. en or zh-CN."),
+    designName: tool.schema
+      .string()
+      .optional()
+      .describe("Optional design name. Defaults to the active design."),
+    mode: tool.schema
+      .enum(["create", "repair"])
+      .optional()
+      .describe("create protects existing files unless overwrite=true; repair may replace an existing foundation shell."),
+    overwrite: tool.schema
+      .boolean()
+      .optional()
+      .describe("Whether create mode may overwrite an existing HTML file. Defaults to false."),
+  },
+  async execute(args, { directory }) {
+    try {
+      const result = createDeckFoundation({
+        workspaceRoot: directory || process.cwd(),
+        outputPath: args.outputPath,
+        title: args.title,
+        language: args.language,
+        designName: args.designName,
+        mode: args.mode,
+        overwrite: args.overwrite ?? false,
+      })
+      return JSON.stringify(result, null, 2)
+    } catch (e: any) {
+      return JSON.stringify({ error: e?.message || String(e) })
+    }
+  },
+})