@cyber-dash-tech/revela 0.18.16 → 0.19.1

package/lib/design/designs.ts

@@ -3,7 +3,9 @@
  *
  * User designs are stored in ~/.config/revela/designs/<name>/.
  * Built-in designs are shipped read-only with this package under designs/<name>/.
- * Each design directory contains DESIGN.md (required) and optionally preview.html.
+ * Each design directory contains DESIGN.md (required), design.css for CSS-native styling,
+ * and optionally legacy preview.html. Current previews are generated from the built-in
+ * page-template fixture plus the design CSS.
  */
 
 import {
@@ -17,8 +19,9 @@ import {
   statSync,
   writeFileSync,
 } from "fs"
-import { dirname, join, resolve, basename, relative, sep } from "path"
+import { dirname, join, normalize, resolve, basename, relative, sep } from "path"
 import { tmpdir } from "os"
+import { pathToFileURL } from "url"
 import { parseFrontmatter } from "../frontmatter"
 import { collectDirectoryEntries, extractEntriesToDirectory, normalizePackageArchiveEntries, readTarArchive, writeTarArchive } from "./archive"
 import {
@@ -28,11 +31,14 @@ import {
   saveConfig,
 } from "../config"
 import { childLog } from "../log"
+import { PAGE_TEMPLATE_CLASSES, listPageTemplateVocabulary, templateDeckCss } from "../page-templates"
 
 const designLog = childLog("designs")
 
 // Seed directory: built-in designs shipped with this package.
 const SEED_DIR = resolve(__dirname, "../..", "designs")
+const BUILT_IN_PREVIEW_PATH = resolve(__dirname, "..", "page-templates", "built-in-preview.html")
+const PREVIEW_FALLBACK_ASSET_DESIGN = "lucent"
 
 export interface DesignInfo {
   name: string
@@ -51,7 +57,8 @@ export interface CreateDesignPackageArgs {
   name: string
   base?: string
   designMd: string
-  previewHtml: string
+  designCss?: string
+  previewHtml?: string
   assets?: DesignPackageAssetInput[]
   overwrite?: boolean
 }
@@ -85,6 +92,7 @@ export interface ValidateDesignPackageResult {
   name: string
   path: string
   hasDesignMd: boolean
+  hasDesignCss: boolean
   hasPreview: boolean
   hasMarkers: boolean
   sections: string[]
@@ -144,6 +152,43 @@ export interface DesignPreviewInfo {
   hasPreview: boolean
 }
 
+export interface MaterializeDesignPreviewArgs {
+  workspaceRoot: string
+  name: string
+  source?: "draft" | "installed" | "builtin"
+}
+
+export interface MaterializeDesignPreviewResult {
+  ok: true
+  name: string
+  source: "draft" | "installed" | "builtin"
+  designDir: string
+  previewDir: string
+  previewPath: string
+  previewUrl: string
+  browserHandoff: {
+    serveRoot: string
+    path: string
+    urlTemplate: string
+    instructions: string
+  }
+  designCssPath: string
+  files: string[]
+  warnings: string[]
+}
+
+export interface DesignCssSnapshotResult {
+  ok: true
+  design: string
+  sourcePath: string
+  snapshotDir: string
+  cssPath: string
+  href: string
+  assetCount: number
+  generatedFallback: boolean
+  warnings: string[]
+}
+
 // ---------------------------------------------------------------------------
 // Seed
 // ---------------------------------------------------------------------------
@@ -300,6 +345,121 @@ export function resolveDesignPreview(name?: string): DesignPreviewInfo {
   }
 }
 
+export function materializeDesignPreview(args: MaterializeDesignPreviewArgs): MaterializeDesignPreviewResult {
+  const name = normalizeDesignName(args.name)
+  const { designDir, source } = resolveDesignPreviewSourceDir(args.workspaceRoot, name, args.source)
+  const previewDir = resolve(args.workspaceRoot, ".revela", "previews", "designs", name)
+  const previewPath = join(previewDir, "preview.html")
+  const designCssPath = join(previewDir, "design.css")
+  const warnings: string[] = []
+
+  if (!existsSync(BUILT_IN_PREVIEW_PATH)) {
+    throw new Error(`Built-in design preview fixture is missing: ${BUILT_IN_PREVIEW_PATH}`)
+  }
+
+  rmSync(previewDir, { recursive: true, force: true })
+  mkdirSync(previewDir, { recursive: true })
+
+  const previewHtml = readFileSync(BUILT_IN_PREVIEW_PATH, "utf-8").replace(/data-design="built-in-preview"/g, `data-design="${name}"`)
+  writeFileSync(previewPath, previewHtml, "utf-8")
+
+  const cssRead = readDesignCssFromDir(name, designDir)
+  warnings.push(...cssRead.warnings)
+  writeFileSync(designCssPath, `${cssRead.css.trim()}\n`, "utf-8")
+
+  const sourceAssets = join(designDir, "assets")
+  const targetAssets = join(previewDir, "assets")
+  if (existsSync(sourceAssets)) cpSync(sourceAssets, targetAssets, { recursive: true })
+  copyMissingBuiltInPreviewAssets(previewHtml, targetAssets)
+
+  return {
+    ok: true,
+    name,
+    source,
+    designDir,
+    previewDir,
+    previewPath,
+    previewUrl: pathToFileURL(previewPath).href,
+    browserHandoff: {
+      serveRoot: previewDir,
+      path: "preview.html",
+      urlTemplate: "http://127.0.0.1:<port>/preview.html",
+      instructions: "Start a read-only local static server from serveRoot, then reply with the localhost URL so the user can click it open in Codex Browser. Do not open the file:// preview directly.",
+    },
+    designCssPath,
+    files: listDesignPackageFiles(previewDir),
+    warnings,
+  }
+}
+
+export function resolveDesignPackageDir(name?: string): string {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = resolveDesignDir(designName)
+  if (!designDir) throw new Error(`Design '${designName}' is not installed`)
+  return designDir
+}
+
+export function readDesignCss(name?: string): { css: string; path?: string; generatedFallback: boolean; warnings: string[] } {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = resolveDesignPackageDir(designName)
+  const cssPath = join(designDir, "design.css")
+  if (existsSync(cssPath)) {
+    return { css: readFileSync(cssPath, "utf-8"), path: cssPath, generatedFallback: false, warnings: [] }
+  }
+
+  const foundation = getDesignSection("foundation", designName)
+  const cssBlocks = extractCssCodeBlocks(foundation)
+  if (cssBlocks.length === 0) throw new Error(`Design '${designName}' has no design.css and no CSS fallback in @design:foundation.`)
+  return {
+    css: [
+      "/* Generated compatibility CSS from DESIGN.md. Add design.css to make this design fully CSS-package native. */",
+      ...cssBlocks,
+      templateDeckCss({ designName, designAssetBasePath: "./assets" }),
+    ].join("\n\n"),
+    generatedFallback: true,
+    warnings: [`Design '${designName}' has no design.css; generated a deck-local compatibility CSS snapshot from DESIGN.md.`],
+  }
+}
+
+export function materializeDesignCssSnapshot(input: {
+  workspaceRoot: string
+  outputPath: string
+  designName?: string
+}): DesignCssSnapshotResult {
+  const designName = normalizeDesignName(input.designName || activeDesign())
+  const designDir = resolveDesignPackageDir(designName)
+  const outputDir = dirname(normalize(input.outputPath))
+  const snapshotRelDir = normalize(join(outputDir, "_revela-design", designName)).replace(/\\/g, "/")
+  const snapshotDir = resolve(input.workspaceRoot, snapshotRelDir)
+  const cssPath = join(snapshotDir, "design.css")
+  const cssRead = readDesignCss(designName)
+
+  mkdirSync(snapshotDir, { recursive: true })
+  writeFileSync(cssPath, cssRead.css.endsWith("\n") ? cssRead.css : `${cssRead.css}\n`, "utf-8")
+
+  const assetsDir = join(designDir, "assets")
+  let assetCount = 0
+  if (existsSync(assetsDir) && statSync(assetsDir).isDirectory()) {
+    const targetAssets = join(snapshotDir, "assets")
+    rmSync(targetAssets, { recursive: true, force: true })
+    cpSync(assetsDir, targetAssets, { recursive: true })
+    assetCount = listDesignPackageFiles(targetAssets).length
+  }
+
+  const href = normalize(relative(outputDir || ".", normalize(join(snapshotRelDir, "design.css")))).replace(/\\/g, "/")
+  return {
+    ok: true,
+    design: designName,
+    sourcePath: cssRead.path || join(designDir, "DESIGN.md"),
+    snapshotDir,
+    cssPath,
+    href: href.startsWith(".") ? href : `./${href}`,
+    assetCount,
+    generatedFallback: cssRead.generatedFallback,
+    warnings: cssRead.warnings,
+  }
+}
+
 /** Normalize and validate a design package name. */
 export function normalizeDesignName(name: string): string {
   const normalized = name.trim().toLowerCase()
@@ -313,10 +473,10 @@ export function normalizeDesignName(name: string): string {
 export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesignPackageResult {
   const name = normalizeDesignName(args.name)
   const designMd = args.designMd?.trim()
+  const designCss = args.designCss?.trim()
   const previewHtml = args.previewHtml?.trim()
 
   if (!designMd) throw new Error("designMd is required")
-  if (!previewHtml) throw new Error("previewHtml is required")
 
   const target = join(DESIGNS_DIR, name)
   const existed = existsSync(target)
@@ -330,7 +490,8 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
   }
   mkdirSync(target, { recursive: true })
   writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
-  writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+  if (designCss) writeFileSync(join(target, "design.css"), `${designCss}\n`, "utf-8")
+  if (previewHtml) writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
   writeDesignAssets(target, args.assets)
 
   const validation = validateDesignPackage(name)
@@ -353,10 +514,10 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
 export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDesignPackageResult {
   const name = normalizeDesignName(args.name)
   const designMd = args.designMd?.trim()
+  const designCss = args.designCss?.trim()
   const previewHtml = args.previewHtml?.trim()
 
   if (!designMd) throw new Error("designMd is required")
-  if (!previewHtml) throw new Error("previewHtml is required")
 
   const target = designDraftDir(args.workspaceRoot, name)
   const existed = existsSync(target)
@@ -370,7 +531,8 @@ export function createDesignDraftPackage(args: CreateDesignDraftArgs): CreateDes
   }
   mkdirSync(target, { recursive: true })
   writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
-  writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+  if (designCss) writeFileSync(join(target, "design.css"), `${designCss}\n`, "utf-8")
+  if (previewHtml) writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
   writeDesignAssets(target, args.assets)
 
   const validation = validateDesignDraftPackage(args.workspaceRoot, name)
@@ -560,8 +722,10 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
   }
 
   const mdPath = join(dir, "DESIGN.md")
+  const cssPath = join(dir, "design.css")
   const previewPath = join(dir, "preview.html")
   const hasDesignMd = existsSync(mdPath)
+  const hasDesignCss = existsSync(cssPath)
   const hasPreview = existsSync(previewPath)
   let hasMarkers = false
   let sections: string[] = []
@@ -571,7 +735,7 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
 
   if (!existsSync(dir)) errors.push(`Design directory does not exist: ${dir}`)
   if (!hasDesignMd) errors.push("DESIGN.md is missing")
-  if (!hasPreview) errors.push("preview.html is missing")
+  if (!hasDesignCss) warnings.push("design.css is missing; DESIGN.md CSS fallback remains compatibility-only and should be migrated.")
   if (existsSync(dir)) assets = listDesignAssetsInDir(dir)
 
   if (hasDesignMd) {
@@ -595,11 +759,13 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
 
   if (hasPreview) {
     const preview = readFileSync(previewPath, "utf-8")
+    const designCss = hasDesignCss ? readFileSync(cssPath, "utf-8") : ""
     if (!preview.includes('<section class="slide"')) errors.push("preview.html must include slide sections")
     if (!preview.includes("slide-qa=")) errors.push("preview.html slides must include slide-qa attributes")
     if (!preview.includes("slide-canvas")) errors.push("preview.html must include .slide-canvas")
-    if (!hasFixedSizeCssRule(preview, "slide-canvas")) {
-      errors.push("preview.html must define .slide-canvas CSS with width: 1920px and height: 1080px")
+    if (hasDesignCss && !previewReferencesDesignCss(preview)) errors.push("preview.html must reference design.css")
+    if (!hasFixedSizeCssRule(`${preview}\n${designCss}`, "slide-canvas")) {
+      errors.push("preview.html or design.css must define .slide-canvas CSS with width: 1920px and height: 1080px")
     }
     if (!hasSlideRole(preview, "cover")) errors.push('preview.html must include a slide section with data-slide-role="cover"')
     if (!hasSlideRole(preview, "closing")) errors.push('preview.html must include a slide section with data-slide-role="closing"')
@@ -611,16 +777,24 @@ function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesign
     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)
   }
+  if (hasDesignCss) {
+    const designCss = readFileSync(cssPath, "utf-8")
+    const missingCoreClasses = requiredDesignCssClasses().filter((className) => !cssTextHasClassSelector(designCss, className))
+    if (missingCoreClasses.length > 0) errors.push(`design.css must style core template classes; missing: ${missingCoreClasses.map((item) => `.${item}`).join(", ")}`)
+    errors.push(...missingDesignCssAssetErrors(designCss, dir))
+  }
+  const designText = hasDesignMd ? readFileSync(mdPath, "utf-8") : ""
+  const designCss = hasDesignCss ? readFileSync(cssPath, "utf-8") : ""
+  const tokenWarnings = designContractTokenWarnings(`${designText}\n${designCss}`)
+  warnings.push(...tokenWarnings)
 
   return {
     ok: errors.length === 0,
     name,
     path: dir,
     hasDesignMd,
+    hasDesignCss,
     hasPreview,
     hasMarkers,
     sections,
@@ -641,15 +815,128 @@ function designContractTokenWarnings(text: string): string[] {
     { 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`)
+    if (!check.pattern.test(text)) warnings.push(`DESIGN.md/design.css should document ${check.label} design tokens or an equivalent contract`)
   }
   return warnings
 }
 
+function previewReferencesDesignCss(preview: string): boolean {
+  return /<link\b[^>]*href=["'][^"']*design\.css["'][^>]*>/i.test(preview)
+}
+
+function requiredDesignCssClasses(): string[] {
+  return [
+    "slide-canvas",
+    "template-slide",
+    "template-frame",
+    "template-title",
+    "template-card",
+    "template-visual-slot-panel",
+  ]
+}
+
+function cssTextHasClassSelector(css: string, className: string): boolean {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, "")
+  const ruleRe = /([^{}]+)\{[^{}]*\}/g
+  let match: RegExpExecArray | null
+  while ((match = ruleRe.exec(withoutComments)) !== null) {
+    if (cssRuleHasClassSelector(match[1] ?? "", className)) return true
+  }
+  return false
+}
+
+function missingDesignCssAssetErrors(css: string, designDir: string): string[] {
+  const errors: string[] = []
+  const seen = new Set<string>()
+  const urlRe = /url\(\s*["']?([^"')]+)["']?\s*\)/gi
+  let match: RegExpExecArray | null
+  while ((match = urlRe.exec(css)) !== null) {
+    const raw = match[1].trim()
+    if (!raw || raw.startsWith("data:") || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("#")) continue
+    const normalized = raw.replace(/^\.\/+/, "")
+    if (!normalized.startsWith("assets/")) continue
+    if (seen.has(normalized)) continue
+    seen.add(normalized)
+    if (!existsSync(join(designDir, ...normalized.split("/")))) errors.push(`design.css references missing asset: ${normalized}`)
+  }
+  return errors
+}
+
+function extractCssCodeBlocks(markdown: string): string[] {
+  const blocks: string[] = []
+  const fenceRe = /```css\n([\s\S]*?)```/g
+  let match: RegExpExecArray | null
+  while ((match = fenceRe.exec(markdown)) !== null) {
+    const body = match[1].trim()
+    if (body) blocks.push(body)
+  }
+  return blocks
+}
+
 function designDraftDir(workspaceRoot: string, name: string): string {
   return resolve(workspaceRoot, ".revela", "drafts", "designs", name)
 }
 
+function resolveDesignPreviewSourceDir(
+  workspaceRoot: string,
+  name: string,
+  requested?: "draft" | "installed" | "builtin",
+): { designDir: string; source: "draft" | "installed" | "builtin" } {
+  const draftDir = designDraftDir(workspaceRoot, name)
+  if (requested === "draft") {
+    if (!existsSync(draftDir)) throw new Error(`Design draft '${name}' does not exist: ${draftDir}`)
+    return { designDir: draftDir, source: "draft" }
+  }
+
+  const installedDir = resolveDesignDir(name)
+  if (requested === "installed" || requested === "builtin") {
+    if (!installedDir) throw new Error(`Design '${name}' is not installed`)
+    const source = requested === "builtin" ? "builtin" : installedDir.startsWith(SEED_DIR + sep) ? "builtin" : "installed"
+    return { designDir: installedDir, source }
+  }
+
+  if (existsSync(draftDir)) return { designDir: draftDir, source: "draft" }
+  if (!installedDir) throw new Error(`Design '${name}' is not available as a workspace draft or installed design`)
+  return { designDir: installedDir, source: installedDir.startsWith(SEED_DIR + sep) ? "builtin" : "installed" }
+}
+
+function readDesignCssFromDir(name: string, designDir: string): { css: string; warnings: string[] } {
+  const cssPath = join(designDir, "design.css")
+  if (existsSync(cssPath)) return { css: readFileSync(cssPath, "utf-8"), warnings: [] }
+
+  const mdPath = join(designDir, "DESIGN.md")
+  const markdown = existsSync(mdPath) ? readFileSync(mdPath, "utf-8") : ""
+  const cssBlocks = extractCssCodeBlocks(markdown)
+  const css = [
+    "/* Generated preview compatibility CSS from DESIGN.md. Add design.css to make this design CSS-native. */",
+    templateDeckCss(),
+    ...cssBlocks,
+  ].join("\n\n")
+  return {
+    css,
+    warnings: [`Design '${name}' has no design.css; generated preview CSS from DESIGN.md compatibility blocks.`],
+  }
+}
+
+function copyMissingBuiltInPreviewAssets(previewHtml: string, targetAssetsDir: string): void {
+  const fallbackAssetsDir = join(SEED_DIR, PREVIEW_FALLBACK_ASSET_DESIGN, "assets")
+  const assetRefs = new Set<string>()
+  const re = /(?:src|href)=["'](?:\.\/)?assets\/([^"']+)["']/g
+  let match: RegExpExecArray | null
+  while ((match = re.exec(previewHtml)) !== null) assetRefs.add(match[1])
+  if (assetRefs.size === 0) return
+
+  mkdirSync(targetAssetsDir, { recursive: true })
+  for (const rel of assetRefs) {
+    const target = resolve(targetAssetsDir, rel)
+    if (existsSync(target)) continue
+    const source = resolve(fallbackAssetsDir, rel)
+    if (!existsSync(source) || !statSync(source).isFile()) continue
+    mkdirSync(dirname(target), { recursive: true })
+    cpSync(source, target)
+  }
+}
+
 function designDraftExists(workspaceRoot: string, name: string): boolean {
   const dir = designDraftDir(workspaceRoot, name)
   return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, "DESIGN.md"))
@@ -812,6 +1099,12 @@ export interface DesignInventory {
   sections: string[]
   layouts: DesignInventoryLayout[]
   components: DesignInventoryComponent[]
+  pageTemplates: Array<{
+    templateId: string
+    slots: string[]
+    requiredClasses: string[]
+    contractNotes: string[]
+  }>
   assets: DesignPackageAssetInfo[]
   hasMarkers: boolean
 }
@@ -953,6 +1246,12 @@ export function getDesignInventory(designName?: string): DesignInventory {
       nesting: inferComponentNesting(componentName),
       contract: inferComponentContract(componentName, content),
     })),
+    pageTemplates: listPageTemplateVocabulary().map((template) => ({
+      templateId: template.templateId,
+      slots: template.slots.map((slot) => slot.name),
+      requiredClasses: template.requiredClasses,
+      contractNotes: template.contractNotes,
+    })),
     assets: listDesignAssetsInDir(designDir),
     hasMarkers,
   }
@@ -1225,6 +1524,7 @@ const UNIVERSAL_CLASSES = new Set([
   "overlay",
   "alt",
   "strong",
+  ...PAGE_TEMPLATE_CLASSES,
 ])
 
 /**
@@ -1360,6 +1660,9 @@ export function extractDesignClasses(designName?: string): DesignClassVocabulary
     extractFromSection(content)
   }
 
+  const cssPath = join(designDir, "design.css")
+  if (existsSync(cssPath)) extractFromCss(readFileSync(cssPath, "utf-8"))
+
   return { classes, prefixExemptions: DEFAULT_PREFIX_EXEMPTIONS }
 }
 

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))
   }