@cyber-dash-tech/revela 0.18.15 → 0.19.0

package/lib/narrative-state/deck-plan-artifact.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, wri
 import { dirname, join, relative } from "path"
 import { createHash } from "crypto"
 import type { DeckSpec, SlideSpec } from "../decks-state"
+import { listPageTemplates } from "../page-templates"
 import { parseVaultFrontmatter } from "../narrative-vault/frontmatter"
 import { splitMarkdownSections } from "../narrative-vault/markdown"
 import { stableVaultRelationId } from "../narrative-vault/relations"
@@ -92,6 +93,8 @@ export interface DeckPlanSlideProjection {
   slideIndex?: number
   title: string
   chapter: string
+  template?: string
+  templateContent?: Record<string, any>
   layout: string
   components: string[]
   componentPlan: DeckPlanSlideComponentPlan[]
@@ -575,6 +578,8 @@ function readDeckPlanSlideFiles(workspaceRoot: string, knownNodeIds?: Set<string
       slideIndex: numberField(parsed.frontmatter, "slideIndex"),
       title: stringField(parsed.frontmatter, "title") || id,
       chapter: stringField(parsed.frontmatter, "chapter"),
+      template: stringField(parsed.frontmatter, "template"),
+      templateContent: parseTemplateContent(split.sections["template-content"] ?? ""),
       layout: stringField(parsed.frontmatter, "layout"),
       components: arrayField(parsed.frontmatter, "components"),
       componentPlan,
@@ -623,6 +628,8 @@ function readDeckPlanSlidesFromSingleFile(workspaceRoot: string, absolutePath: s
       slideIndex,
       title,
       chapter: fields.chapter || "",
+      template: fields.template || "",
+      templateContent: parseTemplateContent(singleFileSubsection(block, "Template Content")),
       layout: fields.layout || "",
       components: parseCsv(fields.components || componentPlan.map((component) => component.name).join(", ")),
       componentPlan,
@@ -671,6 +678,8 @@ function readDeckPlanSeparatorSlidesFromSingleFile(workspaceRoot: string, absolu
       slideIndex,
       title,
       chapter: stringField(parsed.frontmatter, "chapter") || fields.chapter || "",
+      template: stringField(parsed.frontmatter, "template") || fields.template || "",
+      templateContent: parseTemplateContent(singleFileSubsection(block, "Template Content")),
       layout: stringField(parsed.frontmatter, "layout") || fields.layout || "",
       components: arrayField(parsed.frontmatter, "components").length > 0 ? arrayField(parsed.frontmatter, "components") : parseCsv(fields.components || componentPlan.map((component) => component.name).join(", ")),
       componentPlan,
@@ -702,6 +711,27 @@ function parseSlideBlockFields(block: string): Record<string, string> {
   return fields
 }
 
+function parseTemplateContent(section: string): Record<string, any> | undefined {
+  const trimmed = section.trim()
+  if (!trimmed) return undefined
+  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/i.exec(trimmed)
+  const body = fenced ? fenced[1].trim() : trimmed
+  if (body.startsWith("{")) {
+    try {
+      return JSON.parse(body)
+    } catch {
+      return { raw: body }
+    }
+  }
+  const result: Record<string, any> = {}
+  for (const rawLine of body.split(/\r?\n/)) {
+    const match = /^-\s+([A-Za-z][A-Za-z0-9 _-]*):\s*(.*)$/.exec(rawLine.trim())
+    if (!match) continue
+    result[match[1].trim().replace(/\s+/g, "_").toLowerCase()] = cleanPlanValue(match[2])
+  }
+  return Object.keys(result).length > 0 ? result : { raw: body }
+}
+
 function singleFileSubsection(block: string, heading: string): string {
   const re = new RegExp(`^[ \\t]*####\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "mi")
   const match = re.exec(block)
@@ -906,9 +936,11 @@ function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<str
   const diagnostics: DeckPlanProjectionDiagnostic[] = []
   if (!slide.structural && linksCount(slide.sourceLinks) === 0) diagnostics.push({ severity: "warning", code: "slide_source_link_missing", message: `Non-structural deck-plan slide ${slide.id} has no material, finding, asset, or URL source link.`, file: slide.path, nodeId: slide.id })
   if (!slide.structural && linksCount(slide.sourceLinks) > 0) diagnostics.push(...slideSynthesisDiagnostics(slide))
-  if (!slide.layout) diagnostics.push({ severity: "warning", code: "slide_layout_missing", message: `Deck-plan slide ${slide.id} is missing a layout.`, file: slide.path, nodeId: slide.id })
-  if (slide.components.length === 0) diagnostics.push({ severity: "warning", code: "slide_components_missing", message: `Deck-plan slide ${slide.id} has no component names in frontmatter.`, file: slide.path, nodeId: slide.id })
-  if (slide.componentPlan.length === 0) diagnostics.push({ severity: "warning", code: "slide_component_plan_missing", message: `Deck-plan slide ${slide.id} is missing structured ## Component Plan entries.`, file: slide.path, nodeId: slide.id })
+  if (slide.template && !knownTemplateIds().has(slide.template)) diagnostics.push({ severity: "warning", code: "slide_template_unknown", message: `Deck-plan slide ${slide.id} uses unknown page template '${slide.template}'.`, file: slide.path, nodeId: slide.id })
+  if (slide.template && !slide.templateContent) diagnostics.push({ severity: "warning", code: "slide_template_content_missing", message: `Deck-plan slide ${slide.id} uses template '${slide.template}' but has no #### Template Content section.`, file: slide.path, nodeId: slide.id })
+  if (!slide.template && !slide.layout) diagnostics.push({ severity: "warning", code: "slide_layout_missing", message: `Deck-plan slide ${slide.id} is missing a layout.`, file: slide.path, nodeId: slide.id })
+  if (!slide.template && slide.components.length === 0) diagnostics.push({ severity: "warning", code: "slide_components_missing", message: `Deck-plan slide ${slide.id} has no component names in frontmatter.`, file: slide.path, nodeId: slide.id })
+  if (!slide.template && slide.componentPlan.length === 0) diagnostics.push({ severity: "warning", code: "slide_component_plan_missing", message: `Deck-plan slide ${slide.id} is missing structured ## Component Plan entries.`, file: slide.path, nodeId: slide.id })
   for (const component of slide.componentPlan) {
     for (const key of ["name", "slot", "position", "purpose", "content"] as const) {
       if (!component[key] || (Array.isArray(component[key]) && component[key].length === 0)) diagnostics.push({ severity: "warning", code: "slide_component_plan_incomplete", message: `Deck-plan slide ${slide.id} has incomplete component plan entry for ${component.name || "unnamed component"}: missing ${key}.`, file: slide.path, nodeId: slide.id })
@@ -922,6 +954,10 @@ function slideDiagnostics(slide: DeckPlanSlideProjection, knownNodeIds?: Set<str
   return diagnostics
 }
 
+function knownTemplateIds(): Set<string> {
+  return new Set(listPageTemplates().templates.map((template) => template.id))
+}
+
 function slideSynthesisDiagnostics(slide: DeckPlanSlideProjection): DeckPlanProjectionDiagnostic[] {
   const diagnostics: DeckPlanProjectionDiagnostic[] = []
   const contentPlan = singleFileSubsection(slide.markdown, "Content Plan")
@@ -958,6 +994,7 @@ export function deckPlanDesignDiagnostics(projection: DeckPlanProjection | undef
   const components = new Set(inventory.components)
   const diagnostics: DeckPlanProjectionDiagnostic[] = []
   for (const slide of projection.slides) {
+    if (slide.template) continue
     if (slide.layout && !layouts.has(slide.layout)) diagnostics.push({ severity: "warning", code: "slide_layout_unknown", message: `Deck-plan slide ${slide.id} uses layout '${slide.layout}' outside the active design inventory.`, file: slide.path, nodeId: slide.id })
     for (const component of slide.componentPlan) diagnostics.push(...componentDesignDiagnostics(slide, component, inventory, components))
   }

package/lib/page-templates/built-in-preview.html

@@ -0,0 +1,373 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Revela Page Templates</title>
+    <link rel="stylesheet" href="./design.css">
+</head>
+<body>
+    <!-- revela-slides:start -->
+    <section class="slide template-slide" slide-qa="false" data-slide-index="1" data-slide-role="cover" data-design="built-in-preview" data-template="cover">
+        <div class="slide-canvas">
+            <div class="template-frame template-hero template-hero--cover">
+                <div data-template-slot="hero"><header>
+                    <p class="template-eyebrow">Template 01 / 16</p>
+                    <h1 class="template-title template-hero-title">cover</h1>
+                </header></div>
+                
+            </div>
+            <div class="template-page-number">01</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="false" data-slide-index="2" data-design="built-in-preview" data-template="section-divider">
+        <div class="slide-canvas">
+            <div class="template-frame template-hero template-hero--section-divider">
+                <div data-template-slot="hero"><header>
+                    <p class="template-eyebrow">Template 02 / 16</p>
+                    <h1 class="template-title template-hero-title">section-divider</h1>
+                </header></div>
+                
+            </div>
+            <div class="template-page-number">02</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="false" data-slide-index="3" data-slide-role="closing" data-design="built-in-preview" data-template="closing">
+        <div class="slide-canvas">
+            <div class="template-frame template-hero template-hero--closing">
+                <div data-template-slot="hero"><header>
+                    <p class="template-eyebrow">Template 03 / 16</p>
+                    <h1 class="template-title template-hero-title">closing</h1>
+                </header></div>
+                
+            </div>
+            <div class="template-page-number">03</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="4" data-design="built-in-preview" data-template="agenda">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <div class="template-body template-agenda-panel" data-template-slot="agenda">
+                    <div class="template-agenda-inner">
+                        <div class="template-agenda-header">
+                            <p class="template-eyebrow">Template 04 / 16</p>
+                            <h1 class="template-title">agenda</h1>
+                            <p class="template-agenda-footer">Structure-First-Design</p>
+                        </div>
+                        <ol class="template-agenda-list" data-template-slot="agenda-list"><li class="template-agenda-item"><span>01</span><strong>Frame the decision</strong></li><li class="template-agenda-item"><span>02</span><strong>Show the evidence</strong></li><li class="template-agenda-item"><span>03</span><strong>Compare options</strong></li><li class="template-agenda-item"><span>04</span><strong>Close with action</strong></li></ol>
+                    </div>
+                </div>
+                
+            </div>
+            <div class="template-page-number">04</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="5" data-design="built-in-preview" data-template="executive-summary">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 05 / 16</p>
+                    <h1 class="template-title">executive-summary</h1>
+                </header><div class="template-body template-grid cols-3" data-template-slot="summary-cards"><article class="template-card"><h2>Decision is ready</h2><p>The facts support moving from discussion to selection without adding another analysis cycle.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article><article class="template-card"><h2>Risk is bounded</h2><p>Known caveats are visible, named, and can be managed through rollout gates.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article><article class="template-card"><h2>Next step is narrow</h2><p>A pilot decision creates more learning without overcommitting capital or team capacity.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article></div>
+                
+            </div>
+            <div class="template-page-number">05</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="6" data-design="built-in-preview" data-template="problem-context">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 06 / 16</p>
+                    <h1 class="template-title">problem-context</h1>
+                </header><div class="template-body template-grid cols-2"><div class="template-card" data-template-slot="context"><p>Use this template when the audience needs the situation, tension, and implication before seeing recommendations.</p></div><div class="template-card" data-template-slot="supporting-points"><ul class="template-list"><li><strong>Situation</strong> A shift has changed the operating baseline.</li><li><strong>Tension</strong> Current process cannot absorb the new variance cleanly.</li><li><strong>Implication</strong> Delay increases rework and weakens decision confidence.</li></ul></div></div>
+                
+            </div>
+            <div class="template-page-number">06</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="7" data-design="built-in-preview" data-template="key-message-evidence">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 07 / 16</p>
+                    <h1 class="template-title">key-message-evidence</h1>
+                </header><div class="template-body template-grid cols-2"><div class="template-key-message-panel" data-template-slot="key-message">
+                    <h2 class="template-key-message-kicker">Key message</h2>
+                    <p>This key message stays large and readable, while the supporting evidence is separated into traceable slots for source-backed proof.</p>
+                </div><div class="template-evidence-grid" data-template-slot="evidence"><article class="template-card template-evidence-card"><h3>Evidence 1</h3><p>The generated HTML separates the key-message panel from the evidence grid, so the claim cannot collapse into generic card content.</p></article><article class="template-card template-evidence-card"><h3>Evidence 2</h3><p>Each evidence slot has a stable title and explanation area, giving the agent a predictable place for proof, caveat, or source-backed detail.</p></article><article class="template-card template-evidence-card"><h3>Evidence 3</h3><p>QA can inspect the DOM contract before visual styling, which keeps template structure from depending on a design skin.</p></article></div></div>
+                
+            </div>
+            <div class="template-page-number">07</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="8" data-design="built-in-preview" data-template="claim-supporting-visual">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 08 / 16</p>
+                    <h1 class="template-title">claim-supporting-visual</h1>
+                </header><div class="template-body template-grid cols-2"><div class="template-claim-text-panel" data-template-slot="claim">
+                    <h2 class="template-claim-text-title">A single visual should carry one argument.</h2>
+                    <p class="template-claim-text-body">The template reserves a stable visual region while keeping explanatory copy close enough to guide interpretation.</p>
+                    <ul class="template-list"><li><strong>Anchor</strong> State what the reader should inspect first.</li><li><strong>Callout</strong> Use short labels instead of a second paragraph.</li></ul>
+                </div><div class="template-chart-panel template-visual-slot-panel" data-template-slot="visual"><span class="template-visual-slot-label">image / chart slot (optional)</span></div></div>
+                
+            </div>
+            <div class="template-page-number">08</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="9" data-design="built-in-preview" data-template="metric-highlight">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 09 / 16</p>
+                    <h1 class="template-title">metric-highlight</h1>
+                </header><div class="template-body"><div class="template-metric-layout template-metric-layout--insight-bottom"><div class="template-stat-grid" data-template-slot="metrics"><article class="template-card"><div class="template-stat-value">67%</div><h2>Adoption signal</h2><p>Primary number plus interpretation.</p></article><article class="template-card"><div class="template-stat-value">3x</div><h2>Review speed</h2><p>Comparison is stated beside the metric.</p></article><article class="template-card"><div class="template-stat-value">14d</div><h2>Pilot window</h2><p>Time bound keeps the ask concrete.</p></article></div><div class="template-insight-panel">
+                    <h2 class="template-insight-title"><i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i><span>Read the signal</span></h2>
+                    <p class="template-insight-body">Treat the metric row as the evidence surface, then use this panel to state the decision implication, caveat, or next reading step.</p>
+                </div></div></div>
+                
+            </div>
+            <div class="template-page-number">09</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="10" data-design="built-in-preview" data-template="chart-takeaways">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 10 / 16</p>
+                    <h1 class="template-title">chart-takeaways</h1>
+                </header><div class="template-body template-grid template-chart-layout"><div class="template-chart-panel template-visual-slot-panel" data-template-slot="visual"><span class="template-visual-slot-label">image / chart slot (optional)</span></div><div class="template-text-panel template-chart-takeaway-panel" data-template-slot="takeaways">
+                    <h2 class="template-text-panel-title">What to read</h2>
+                    <div class="template-chart-takeaway-list"><section class="template-chart-takeaway-item"><h3>Trend</h3><p>Call out the movement or comparison the chart is meant to prove, including the direction and the comparison baseline.</p></section><section class="template-chart-takeaway-item"><h3>Driver</h3><p>Name the likely reason without overclaiming; separate observed movement from the interpretation or hypothesis.</p></section><section class="template-chart-takeaway-item"><h3>Decision use</h3><p>Explain how the chart changes the recommendation, what threshold matters, and what follow-up evidence would reduce risk.</p></section></div>
+                </div></div>
+                
+            </div>
+            <div class="template-page-number">10</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="11" data-design="built-in-preview" data-template="table-comparison">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 11 / 16</p>
+                    <h1 class="template-title">table-comparison</h1>
+                </header><div class="template-body" data-template-slot="table"><div class="template-table-wrap"><table class="template-table"><thead><tr><th>Layer</th><th>Owns</th><th>Agent task</th></tr></thead><tbody><tr><td>Template</td><td>Structure and DOM contract</td><td>Select the page pattern</td></tr><tr><td>Content</td><td>Claim, evidence, caveat</td><td>Fill the meaning</td></tr><tr><td>Design</td><td>Color, type, surfaces</td><td>Skin stable classes</td></tr></tbody></table><div class="template-insight-panel">
+                    <h2 class="template-insight-title"><i class="template-insight-icon" data-lucide="lightbulb" aria-hidden="true"></i><span>Insight</span></h2>
+                    <p class="template-insight-body">The template layer owns structure, while the design layer owns visual treatment. This keeps agent edits bounded without freezing the final look.</p>
+                </div></div></div>
+                
+            </div>
+            <div class="template-page-number">11</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="12" data-design="built-in-preview" data-template="timeline-roadmap">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 12 / 16</p>
+                    <h1 class="template-title">timeline-roadmap</h1>
+                </header><div class="template-body"><div class="template-timeline template-timeline--horizontal" data-template-slot="timeline" style="--timeline-count:5"><article class="template-timeline-item">
+                        <div class="template-timeline-copy template-card">
+                            <i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i>
+                            <h3>Signal</h3>
+                            <p>Map the baseline.</p>
+                        </div>
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <p class="template-timeline-date">2022</p>
+                    </article><article class="template-timeline-item">
+                        <div class="template-timeline-copy template-card">
+                            <i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i>
+                            <h3>Proof</h3>
+                            <p>Validate the evidence threshold.</p>
+                        </div>
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <p class="template-timeline-date">2023</p>
+                    </article><article class="template-timeline-item">
+                        <div class="template-timeline-copy template-card">
+                            <i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i>
+                            <h3>Inflection</h3>
+                            <p>Use the pivotal moment to frame the shift.</p>
+                        </div>
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <p class="template-timeline-date">2024</p>
+                    </article><article class="template-timeline-item template-timeline-item--highlight">
+                        <div class="template-timeline-copy template-card">
+                            <i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i>
+                            <h3>Scale</h3>
+                            <p>Use a taller card for the highlighted milestone.</p>
+                        </div>
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <p class="template-timeline-date">2025</p>
+                    </article><article class="template-timeline-item">
+                        <div class="template-timeline-copy template-card">
+                            <i class="template-insight-icon" data-lucide="scan-search" aria-hidden="true"></i>
+                            <h3>Decision</h3>
+                            <p>Commit to the next path.</p>
+                        </div>
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <p class="template-timeline-date">2026</p>
+                    </article></div></div>
+                
+            </div>
+            <div class="template-page-number">12</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="13" data-design="built-in-preview" data-template="timeline-roadmap">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 13 / 16</p>
+                    <h1 class="template-title">timeline-roadmap-vertical</h1>
+                </header><div class="template-body"><div class="template-timeline-layout template-timeline-layout--left"><div class="template-side-panel template-text-panel" data-template-slot="insight"><h2 class="template-side-panel-title template-text-panel-title">Reading the journey</h2><p class="template-side-panel-body template-text-panel-body">The timeline should show sequence and decision rhythm, while the side panel explains why the milestones matter.</p></div><div class="template-timeline template-timeline--vertical" data-template-slot="timeline" style="--timeline-count:4"><article class="template-timeline-item">
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <div class="template-timeline-copy">
+                            <p class="template-timeline-date">Mar 2019</p>
+                            <h3>Launch</h3>
+                            <p>Baseline mapping.</p>
+                        </div>
+                    </article><article class="template-timeline-item">
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <div class="template-timeline-copy">
+                            <p class="template-timeline-date">Nov 2019</p>
+                            <h3>Audit</h3>
+                            <p>Evidence sprint.</p>
+                        </div>
+                    </article><article class="template-timeline-item">
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <div class="template-timeline-copy">
+                            <p class="template-timeline-date">May 2020</p>
+                            <h3>Scale</h3>
+                            <p>Operating cadence.</p>
+                        </div>
+                    </article><article class="template-timeline-item">
+                        <span class="template-timeline-dot" aria-hidden="true"></span>
+                        <div class="template-timeline-copy">
+                            <p class="template-timeline-date">Feb 2021</p>
+                            <h3>Review</h3>
+                            <p>QA before export.</p>
+                        </div>
+                    </article></div></div></div>
+                
+            </div>
+            <div class="template-page-number">13</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="14" data-design="built-in-preview" data-template="process-steps">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 14 / 16</p>
+                    <h1 class="template-title">process-steps</h1>
+                </header><div class="template-body"><div class="template-steps" data-template-slot="steps"><article class="template-card"><div class="template-step-number">1</div><h2>Choose</h2><p>Select the page template that matches the communication job.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article><article class="template-card"><div class="template-step-number">2</div><h2>Fill</h2><p>Provide only the content fields the template needs.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article><article class="template-card"><div class="template-step-number">3</div><h2>Style</h2><p>Let the active design control type, color, and surfaces.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article><article class="template-card"><div class="template-step-number">4</div><h2>QA</h2><p>Run contract and visual checks before export.</p><figure class="template-visual-placeholder"><div class="template-visual-placeholder-frame"><span class="template-visual-placeholder-label">image / chart slot (optional)</span></div></figure></article></div></div>
+                
+            </div>
+            <div class="template-page-number">14</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="15" data-design="built-in-preview" data-template="recommendation-decision">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 15 / 16</p>
+                    <h1 class="template-title">recommendation-decision</h1>
+                </header><div class="template-body template-grid cols-3"><div class="template-card" data-template-slot="recommendation"><h2>Recommendation</h2><p>Adopt page templates as the structural layer, with designs remaining user-customizable.</p><figure class="template-image-card"><div class="template-image-frame"><img src="./assets/card-lens.jpg" alt="Lucent design asset"></div><figcaption class="template-image-caption">Design asset example</figcaption></figure></div><div data-template-slot="rationale"><article class="template-card"><h3>Rationale</h3><p>This keeps generation reliable while leaving style expressive and replaceable.</p></article></div><div class="template-card" data-template-slot="next-steps"><h2>Next steps</h2><ol class="template-list"><li><strong>Pilot</strong> Use the built-in preview to tune every template.</li><li><strong>Validate</strong> Promote only contracts that pass QA and browser review.</li><li><strong>Ship</strong> Document the add-slide workflow for agents.</li></ol></div></div>
+                
+            </div>
+            <div class="template-page-number">15</div>
+        </div>
+    </section>
+    <section class="slide template-slide" slide-qa="true" data-slide-index="16" data-design="built-in-preview" data-template="risks-tradeoffs">
+        <div class="slide-canvas">
+            <div class="template-frame">
+                <header>
+                    <p class="template-eyebrow">Template 16 / 16</p>
+                    <h1 class="template-title">risks-tradeoffs</h1>
+                </header><div class="template-body template-grid cols-3" data-template-slot="risks"><article class="template-card"><h3>Constraint</h3><p>Templates can over-constrain if they become decorative presets instead of communication jobs.</p><figure class="template-image-card"><div class="template-image-frame"><img src="./assets/report-visual.jpg" alt="Report visual"></div><figcaption class="template-image-caption">Design asset example</figcaption></figure></article><article class="template-card"><h3>Mitigation</h3><p>Keep bounded HTML edit flow after scaffold insertion so agents can improve the page directly.</p></article><article class="template-card"><h3>Tradeoff</h3><p>More structure improves QA, but only if template contracts stay small and semantic.</p></article></div>
+                
+            </div>
+            <div class="template-page-number">16</div>
+        </div>
+    </section>
+    <!-- revela-slides:end -->
+    <script>
+class SlidePresentation {
+    constructor() {
+        this.slides = document.querySelectorAll('.slide');
+        this.currentSlide = 0;
+        this.setupScaling();
+        this.setupIntersectionObserver();
+        this.setupKeyboardNav();
+        this.setupTouchNav();
+        this.setupMouseWheel();
+    }
+    setupScaling() {
+        const canvases = document.querySelectorAll('.slide-canvas');
+        const BASE_W = 1920;
+        const BASE_H = 1080;
+        const update = () => {
+            const scale = Math.min(window.innerWidth / BASE_W, window.innerHeight / BASE_H);
+            canvases.forEach((canvas) => { canvas.style.transform = `scale(${scale})`; });
+        };
+        window.addEventListener('resize', update);
+        update();
+    }
+    setupIntersectionObserver() {
+        const observer = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                if (entry.isIntersecting) entry.target.querySelectorAll('.reveal').forEach((el) => el.classList.add('visible'));
+            });
+        }, { threshold: 0.2 });
+        this.slides.forEach((slide) => observer.observe(slide));
+    }
+    setupKeyboardNav() {
+        document.addEventListener('keydown', (event) => {
+            if (['ArrowDown', 'ArrowRight', ' ', 'PageDown'].includes(event.key)) { event.preventDefault(); this.goTo(this.currentSlide + 1); }
+            else if (['ArrowUp', 'ArrowLeft', 'PageUp'].includes(event.key)) { event.preventDefault(); this.goTo(this.currentSlide - 1); }
+        });
+    }
+    setupTouchNav() {
+        let startY = 0;
+        document.addEventListener('touchstart', (event) => { startY = event.touches[0].clientY; }, { passive: true });
+        document.addEventListener('touchend', (event) => {
+            const deltaY = startY - event.changedTouches[0].clientY;
+            if (Math.abs(deltaY) > 40) this.goTo(this.currentSlide + (deltaY > 0 ? 1 : -1));
+        }, { passive: true });
+    }
+    setupMouseWheel() {
+        let last = 0;
+        document.addEventListener('wheel', (event) => {
+            const now = Date.now();
+            if (now - last < 800) return;
+            last = now;
+            this.goTo(this.currentSlide + (event.deltaY > 0 ? 1 : -1));
+        }, { passive: true });
+    }
+    goTo(index) {
+        const clamped = Math.max(0, Math.min(this.slides.length - 1, index));
+        this.slides[clamped].scrollIntoView({ behavior: 'smooth' });
+        this.currentSlide = clamped;
+    }
+}
+if (document.querySelector(".slide")) { new SlidePresentation(); }
+    </script>
+    <script>
+function revelaRenderLucideIcons() {
+  var icons = {
+    lightbulb: '<svg xmlns="http://www.w3.org/2000/svg" class="template-insight-icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 14c.2-1 .7-1.7 1.5-2.5A5.5 5.5 0 0 0 18 7.5C18 4.5 15.5 2 12 2S6 4.5 6 7.5c0 1.5.6 2.9 1.5 4 .8.8 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/></svg>',
+    'scan-search': '<svg xmlns="http://www.w3.org/2000/svg" class="template-insight-icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 3H5a2 2 0 0 0-2 2v2"/><path d="M17 3h2a2 2 0 0 1 2 2v2"/><path d="M7 21H5a2 2 0 0 1-2-2v-2"/><path d="M14 14l4 4"/><circle cx="11" cy="11" r="3"/></svg>'
+  };
+  document.querySelectorAll("[data-lucide]").forEach(function (node) {
+    var name = node.getAttribute("data-lucide") || "lightbulb";
+    var svg = icons[name] || icons.lightbulb;
+    var wrapper = document.createElement("span");
+    wrapper.innerHTML = svg;
+    var next = wrapper.firstElementChild;
+    if (next) node.replaceWith(next);
+  });
+}
+revelaRenderLucideIcons();
+</script>
+</body>
+</html>

package/lib/page-templates/contracts.ts

@@ -0,0 +1,2 @@
+export { formatPageTemplateContractReport, validatePageTemplateContracts } from "./render"
+

package/lib/page-templates/css.ts

@@ -0,0 +1,2 @@
+export { templateDeckCss } from "./render"
+

package/lib/page-templates/foundation.ts

@@ -0,0 +1,41 @@
+import { getPageTemplateVocabulary, listPageTemplateVocabulary, type PageTemplateVocabulary } from "./vocabulary"
+
+export interface PageTemplateFoundation {
+  templateId: string
+  html: string
+  cssHooks: string[]
+  slots: PageTemplateVocabulary["slots"]
+  designNotes: string[]
+  contractNotes: string[]
+}
+
+export function listPageTemplateFoundations(): PageTemplateFoundation[] {
+  return listPageTemplateVocabulary().map((item) => getPageTemplateFoundation(item.templateId))
+}
+
+export function getPageTemplateFoundation(templateId: string): PageTemplateFoundation {
+  const vocabulary = getPageTemplateVocabulary(templateId)
+  return {
+    templateId: vocabulary.templateId,
+    html: foundationHtml(vocabulary),
+    cssHooks: [...new Set([...vocabulary.rootClasses, ...vocabulary.requiredClasses, ...vocabulary.optionalClasses])],
+    slots: vocabulary.slots,
+    designNotes: [
+      "Use this foundation as the custom design starting point; style classes, do not remove structural classes.",
+      "Prefer overriding visual treatment in design CSS while keeping data-template-slot attributes intact.",
+      "Visual slots may become image, chart, table, or diagram containers when the semantic container remains clear.",
+    ],
+    contractNotes: vocabulary.contractNotes,
+  }
+}
+
+function foundationHtml(vocabulary: PageTemplateVocabulary): string {
+  const slotHtml = vocabulary.slots.map((slot) => `    <div data-template-slot="${slot.name}">${slot.name}</div>`).join("\n")
+  return `<section class="slide template-slide" data-template="${vocabulary.templateId}">
+  <div class="slide-canvas">
+    <div class="template-frame">
+${slotHtml}
+    </div>
+  </div>
+</section>`
+}

package/lib/page-templates/index.ts

@@ -0,0 +1,6 @@
+export * from "./contracts"
+export * from "./css"
+export * from "./foundation"
+export * from "./registry"
+export * from "./render"
+export * from "./vocabulary"

package/lib/page-templates/registry.ts

@@ -0,0 +1,3 @@
+export { listPageTemplates } from "./render"
+export type { PageTemplateDefinition, PageTemplateField, PageTemplateStatus } from "./render"
+