@cyber-dash-tech/revela 0.10.0 → 0.11.0

package/README.md

@@ -2,14 +2,14 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-178%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-302%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
 </p>
 
-Revela is an [OpenCode](https://opencode.ai) plugin that turns your current agent into an HTML slide deck generator.
-Enable it for the current session, assign a presentation task, and the agent can research, structure, write, QA, and export a deck.
+Revela is an [OpenCode](https://opencode.ai) plugin for building trusted narrative artifacts from workspace sources, research, evidence, and user intent.
+Its first render target is still the HTML slide deck: enable Revela for the current session, assign a presentation task, and the agent can research, structure, write, QA, inspect, refine, and export a deck.
 
 **[Live Demo — The AI Power Shift](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -20,8 +20,10 @@ Enable it for the current session, assign a presentation task, and the agent can
 - injects a presentation-specific system prompt into your current agent with `/revela enable`
 - builds that prompt from 3 layers: core skill, active domain, active design
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
-- keeps track of deck context, slide structure, sources, and readiness across the current workspace
+- keeps `DECKS.json` as the current workspace state engine for sources, research actions, findings, claims, evidence, narrative intent, render targets, and readiness
 - checks for missing context, weak evidence, and incomplete structure before writing `decks/*.html`
+- records review snapshots so stale readiness cannot silently authorize new deck HTML after important state changes
+- treats HTML decks, PDF, and PPTX as render targets from shared workspace state rather than isolated output files
 - runs fast design compliance checks whenever the agent writes, patches, or edits `decks/*.html`
 - opens a visual comment editor for existing decks so users can Ctrl/Cmd-click elements and send precise edit requests back to OpenCode
 - exports finished decks to PDF and editable PPTX
@@ -178,6 +180,22 @@ That prompt is built from 3 layers:
 Persistent preferences live in `~/.config/revela/config.json`.
 The enabled or disabled state is session-level only.
 
+### Workspace State
+
+`DECKS.json` is Revela's workspace state engine and compatibility file. It is still stored at the workspace root and remains readable as the current deck project state, but internally Revela now treats it as a lightweight persistence layer for more than a deck checklist.
+
+The state records:
+
+- workspace source materials and reusable extraction cache paths
+- research plans, saved findings, and compact action provenance
+- narrative intent, objections, risks, slide specs, claim candidates, and slide-level evidence trace
+- render targets such as the active HTML deck plus derived PDF and PPTX artifacts
+- review snapshots with input hashes so old readiness results become stale after meaningful state changes
+
+0.11 keeps backward compatibility with existing root `DECKS.json` workspaces. Running `/revela init` or `/revela review` on an older project can normalize and refresh the new projection fields without requiring a manual migration, moving files, or replacing `DECKS.json` with a database.
+
+Decks remain the primary authored artifact, but they are now treated as render targets from the same workspace state that can later support briefs, appendix material, Evidence Inspector views, Q&A, and interactive reading layers without duplicating source/evidence logic.
+
 ---
 
 ## Recommended Workflow
@@ -196,7 +214,7 @@ Use Revela as a guided deck-production mode:
 
 `/revela review` checks for practical readiness problems: unclear audience, missing source material, unfinished research, unsupported claims, weak source trace, incomplete slide structure, missing design/layout information, or lightweight narrative issues such as weak so-what, missing risk/assumption handling, and abrupt transitions. It does not write the final deck.
 
-If Revela blocks a deck write, ask the agent to run `/revela review`, resolve the reported gaps, and try again. This protects the deck file from being overwritten before the plan, evidence, and structure are ready.
+If Revela blocks a deck write, ask the agent to run `/revela review`, resolve the reported gaps, and try again. This protects the deck file from being overwritten before the plan, evidence, and structure are ready. In 0.11, review results are also saved as input-hashed snapshots; if sources, slide specs, evidence, narrative state, or the active render target changes afterward, the old review can no longer silently authorize a write.
 
 To remember long-term preferences, use:
 
@@ -597,6 +615,8 @@ The inspector opens in your browser with the deck on the left and fixed cards on
 
 The inspector is not chat and has no freeform prompt. It does not mutate `DECKS.json` or the deck HTML. It uses recorded slide specs, narrative state, and slide-level evidence trace as grounded context. Deterministic preprocessing appears immediately; lazy LLM judgment then refines the Source and Purpose cards without inventing edits.
 
+Inspection and refinement use the active HTML deck render target recorded in workspace state. The deck HTML must satisfy Revela's slide identity contract: every `<section class="slide">` in the active artifact needs a positive 1-based `data-slide-index` matching the current slide specs. Invalid active artifacts are refused or reported before inspect/refine/export workflows trust them.
+
 ---
 
 ## Export

package/README.zh-CN.md

@@ -2,14 +2,14 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-178%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-302%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
 </p>
 
-Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使用的 agent 变成 HTML 幻灯片生成器。
-在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA 和导出。
+Revela 是一个 [OpenCode](https://opencode.ai) 插件，用来把工作区来源材料、调研、证据和用户意图转成可信的叙事型沟通 artifact。
+它的第一个 render target 仍然是 HTML slide deck：在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA、检查、refine 和导出。
 
 **[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
@@ -20,8 +20,10 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
 - prompt 由 3 层组成：核心 skill、当前 domain、当前 design
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
-- 在当前工作区持续跟踪 deck 背景、页面结构、来源材料和 readiness
+- 将 `DECKS.json` 作为当前 workspace state engine，持续记录来源材料、调研动作、findings、claims、证据、叙事意图、render targets 和 readiness
 - 写入 `decks/*.html` 前检查是否缺上下文、证据或结构
+- 记录 review snapshots，避免重要状态变化后旧的 ready 结果继续默默授权写入 deck HTML
+- 把 HTML deck、PDF 和 PPTX 视为来自同一 workspace state 的 render targets，而不是互相孤立的输出文件
 - agent 每次写入、patch 或 edit `decks/*.html` 时自动执行快速 design compliance 检查
 - 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
@@ -177,6 +179,22 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 持久化配置保存在 `~/.config/revela/config.json`。
 是否启用 Revela 则只在当前会话生效。
 
+### Workspace State
+
+`DECKS.json` 是 Revela 当前的 workspace state engine，也是兼容旧工作流的状态文件。它仍然保存在工作区根目录，也仍然可以理解为当前 deck 项目的状态入口，但 Revela 内部已经不再把它当成单纯的 deck checklist。
+
+状态中会记录：
+
+- 工作区来源材料和可复用的 extraction cache 路径
+- 调研计划、已保存 findings，以及精简的 action provenance
+- narrative intent、objections、risks、slide specs、claim candidates 和 slide-level evidence trace
+- active HTML deck 以及派生 PDF、PPTX 等 render targets
+- 带 input hash 的 review snapshots，使重要状态变化后旧的 readiness 自动变 stale
+
+0.11 继续兼容已有的根目录 `DECKS.json` 工作区。对旧项目运行 `/revela init` 或 `/revela review` 时，可以安全 normalize 并刷新新的 projection 字段；用户不需要手动迁移、不需要移动文件，也不需要把 `DECKS.json` 换成数据库。
+
+Deck 仍然是主要 authored artifact，但现在它是从同一份 workspace state 渲染出来的目标之一。后续 briefs、appendix material、Evidence Inspector views、Q&A 和 interactive reading layers 都可以复用同一套来源/证据逻辑，而不是各自生成孤立内容。
+
 ---
 
 ## 推荐使用流程
@@ -195,7 +213,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 `/revela review` 检查的是实际生产问题：受众是否清楚、是否缺来源材料、调研是否完成、关键 claim 是否有证据、source trace 是否太弱、页面结构是否完整、design/layout 信息是否齐全，以及轻量叙事问题，例如 so-what 不清晰、缺少风险/假设处理或转场突兀。它不会写最终 deck。
 
-如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。
+如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。0.11 还会把 review 结果保存为带 input hash 的 snapshot；如果之后来源材料、slide specs、证据、叙事状态或 active render target 发生变化，旧 review 不能继续默默授权写入。
 
 记住长期偏好请使用：
 
@@ -562,6 +580,8 @@ Inspector 会在浏览器中打开，左侧是 deck，右侧是固定卡片：So
 
 Inspector 不是聊天，也没有自由输入框。它不会修改 `DECKS.json` 或 deck HTML。它使用已记录的 slide spec、narrative state 和 slide-level evidence trace 作为 grounded context。确定性预处理会立即显示；LLM judgment 随后 lazy 更新 Source 和 Purpose 卡片，不会强行生成编辑动作。
 
+Inspect 和 refine 会使用 workspace state 中记录的 active HTML deck render target。Deck HTML 必须满足 Revela 的 slide identity contract：active artifact 中每个 `<section class="slide">` 都需要有正数、1-based 的 `data-slide-index`，并且要匹配当前 slide specs。无效的 active artifact 会在 inspect/refine/export 工作流信任它之前被拒绝或报告。
+
 ---
 
 ## 导出

package/lib/commands/inspect.ts

@@ -11,7 +11,7 @@ export async function handleInspect(
       workspaceRoot: options.workspaceRoot,
     })
     await send(
-      `Opened Evidence Inspector for the only deck in \`decks/\`.\n` +
+      `Opened Evidence Inspector for the active HTML deck.\n` +
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +

package/lib/commands/pdf.ts

@@ -8,28 +8,41 @@
  */
 
 import { resolve } from "path"
+import { hasDecksState, readDecksState } from "../decks-state"
 import { exportToPdf } from "../pdf/export"
 import { assertExportQAPassed } from "../qa/export-gate"
+import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
+import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export async function handlePdf(
   filePath: string,
   send: (text: string) => Promise<void>,
+  workspaceRoot = process.cwd(),
 ): Promise<void> {
-  if (!filePath) {
+  const root = resolve(workspaceRoot)
+  const resolvedFile = resolvePdfDeckFile(root, filePath)
+
+  if (!resolvedFile) {
     await send(
-      "**Usage:** `/revela pdf <file_path>`\n\n" +
+      "**Usage:** `/revela pdf [file_path]`\n\n" +
       "Example: `/revela pdf decks/my-deck.html`"
     )
     return
   }
 
-  const abs = resolve(filePath)
+  const abs = resolvedFile.absoluteFile
   await send(`Running pre-export QA for \`${abs}\`...`)
 
   try {
-    await assertExportQAPassed(abs)
+    await assertExportQAPassed(abs, { workspaceRoot: root })
     await send(`Exporting \`${abs}\` to PDF...`)
-    const result = await exportToPdf(filePath)
+    const result = await exportToPdf(abs)
+    recordRenderedArtifact(root, {
+      sourceHtmlPath: resolvedFile.file,
+      outputPath: result.outputPath,
+      type: "pdf",
+      actor: "revela-pdf",
+    })
     const secs = (result.durationMs / 1000).toFixed(1)
     await send(
       `**PDF exported successfully**\n\n` +
@@ -42,3 +55,18 @@ export async function handlePdf(
     await send(`**PDF export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
   }
 }
+
+function resolvePdfDeckFile(workspaceRoot: string, filePath: string): { file: string; absoluteFile: string } | undefined {
+  const explicit = filePath.trim()
+  if (explicit) {
+    const absoluteFile = resolve(workspaceRoot, explicit)
+    return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+  }
+
+  if (!hasDecksState(workspaceRoot)) return undefined
+  const state = readDecksState(workspaceRoot)
+  const activePath = resolveActiveHtmlDeckPath(state)
+  if (!activePath) return undefined
+  const absoluteFile = resolve(workspaceRoot, activePath)
+  return { file: workspaceRelative(workspaceRoot, absoluteFile), absoluteFile }
+}

package/lib/commands/pptx.ts

@@ -10,7 +10,10 @@
 import { existsSync, readdirSync } from "fs"
 import { relative, resolve, sep } from "path"
 import { hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { exportToPptx } from "../pptx/export"
+import { recordRenderedArtifact } from "../workspace-state/rendered-artifacts"
+import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export interface PptxArgs {
   filePath: string
@@ -20,7 +23,7 @@ export interface PptxArgs {
 export interface ResolvedPptxDeck {
   file: string
   absoluteFile: string
-  source: "decks-state" | "fallback" | "file-path"
+  source: "render-target" | "decks-state" | "fallback" | "file-path"
 }
 
 function formatSecs(ms: number): string {
@@ -46,12 +49,12 @@ export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedP
 
   if (hasDecksState(root)) {
     const state = readDecksState(root)
-    const key = state.activeDeck || singleDeckKey(state.decks)
-    const outputPath = key ? state.decks[key]?.outputPath : undefined
+    const outputPath = resolveActiveHtmlDeckPath(state)
     if (outputPath && isDeckHtmlPath(outputPath)) {
       const absoluteFile = resolve(root, outputPath)
       if (existsSync(absoluteFile)) {
-        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "decks-state" }
+        const source = state.renderTargets.some((target) => target.type === "html_deck" && target.outputPath === outputPath) ? "render-target" : "decks-state"
+        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source }
       }
     }
   }
@@ -114,6 +117,7 @@ export async function handlePptx(
     const deck = resolvePptxDeck(workspaceRoot, args.filePath)
     const abs = deck.absoluteFile
 
+    assertDeckHtmlContractValid(workspaceRoot, abs)
     await send(`Exporting \`${abs}\` to PPTX...`)
     let lastSlideUpdate = 0
     let longDeckThreshold: number | null = null
@@ -141,6 +145,12 @@ export async function handlePptx(
         await send(`Editable export progress: slide ${current}/${total}`)
       },
     })
+    recordRenderedArtifact(workspaceRoot, {
+      sourceHtmlPath: deck.file,
+      outputPath: result.outputPath,
+      type: "pptx",
+      actor: "revela-pptx",
+    })
 
     await send(
       `**PPTX exported successfully**\n\n` +
@@ -159,11 +169,6 @@ export async function handlePptx(
   }
 }
 
-function singleDeckKey(decks: Record<string, unknown>): string | undefined {
-  const keys = Object.keys(decks)
-  return keys.length === 1 ? keys[0] : undefined
-}
-
 function listDeckHtmlFiles(workspaceRoot: string): string[] {
   const dir = resolve(workspaceRoot, "decks")
   if (!existsSync(dir)) return []

package/lib/commands/refine.ts

@@ -14,7 +14,7 @@ export async function handleRefine(
     })
 
     await send(
-      `Opened Revela Refine for the only deck in \`decks/\`.\n` +
+      `Opened Revela Refine for the active HTML deck.\n` +
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +

package/lib/deck-html/contract.ts

@@ -0,0 +1,252 @@
+import { existsSync, readFileSync } from "fs"
+import { relative, resolve, sep } from "path"
+import { hasDecksState, readDecksState, type DeckSpec } from "../decks-state"
+import { resolveActiveHtmlDeckPath, normalizeWorkspacePath } from "../workspace-state/render-targets"
+
+export type DeckHtmlContractStatus = "valid" | "invalid" | "skipped"
+
+export type DeckHtmlContractIssueType =
+  | "file_not_found"
+  | "no_matching_deck_spec"
+  | "missing_slide_section"
+  | "slide_count_mismatch"
+  | "missing_data_slide_index"
+  | "invalid_data_slide_index"
+  | "duplicate_data_slide_index"
+  | "slide_index_mismatch"
+  | "legacy_data_index_noncanonical"
+
+export interface DeckHtmlContractIssue {
+  type: DeckHtmlContractIssueType
+  severity: "error" | "warning"
+  message: string
+  slidePosition?: number
+  expectedIndex?: number
+  actualIndex?: number
+}
+
+export interface DeckHtmlContractReport {
+  status: DeckHtmlContractStatus
+  ok: boolean
+  workspaceRoot: string
+  filePath: string
+  deckSlug?: string
+  activeHtmlPath?: string
+  expectedIndexes: number[]
+  actualIndexes: number[]
+  issues: DeckHtmlContractIssue[]
+  warnings: DeckHtmlContractIssue[]
+}
+
+interface SlideSectionAttrs {
+  position: number
+  dataSlideIndex?: string
+  dataIndex?: string
+}
+
+export function validateDeckHtmlContract(workspaceRoot: string, filePath: string): DeckHtmlContractReport {
+  const root = resolve(workspaceRoot)
+  const absoluteFile = resolve(root, filePath)
+  const relativeFile = workspaceRelative(root, absoluteFile)
+  const base: Omit<DeckHtmlContractReport, "status" | "ok"> = {
+    workspaceRoot: root,
+    filePath: relativeFile,
+    expectedIndexes: [],
+    actualIndexes: [],
+    issues: [],
+    warnings: [],
+  }
+
+  if (!hasDecksState(root)) return skipped(base, "No DECKS.json exists; deck HTML contract validation is skipped.")
+
+  const state = readDecksState(root)
+  const activeHtmlPath = resolveActiveHtmlDeckPath(state)
+  const activeKey = state.activeDeck || singleDeckKey(state.decks)
+  const deck = activeKey ? state.decks[activeKey] : undefined
+  const normalizedActive = normalizeWorkspacePath(activeHtmlPath ?? "")
+  const normalizedTarget = normalizeWorkspacePath(relativeFile)
+
+  base.activeHtmlPath = normalizedActive || undefined
+  base.deckSlug = deck?.slug
+
+  if (!deck || !normalizedActive || normalizedActive !== normalizedTarget) {
+    return skipped(base, `No matching active deck spec exists for ${relativeFile}; deck HTML contract validation is skipped.`)
+  }
+
+  if (!existsSync(absoluteFile)) {
+    base.issues.push({
+      type: "file_not_found",
+      severity: "error",
+      message: `Deck HTML file not found: ${relativeFile}`,
+    })
+    return finalize(base)
+  }
+
+  const html = readFileSync(absoluteFile, "utf-8")
+  const sections = extractSlideSections(html)
+  base.expectedIndexes = expectedSlideIndexes(deck)
+
+  if (sections.length === 0) {
+    base.issues.push({
+      type: "missing_slide_section",
+      severity: "error",
+      message: "Deck HTML must contain one <section class=\"slide\"> element per slide spec.",
+    })
+    return finalize(base)
+  }
+
+  if (sections.length !== base.expectedIndexes.length) {
+    base.issues.push({
+      type: "slide_count_mismatch",
+      severity: "error",
+      message: `Deck HTML has ${sections.length} slide sections, but DECKS.json expects ${base.expectedIndexes.length}.`,
+    })
+  }
+
+  const seen = new Set<number>()
+  sections.forEach((section, offset) => {
+    const expectedIndex = base.expectedIndexes[offset]
+    if (section.dataIndex !== undefined) {
+      base.warnings.push({
+        type: "legacy_data_index_noncanonical",
+        severity: "warning",
+        message: `Slide ${section.position} has legacy data-index; use data-slide-index as the canonical slide identity.`,
+        slidePosition: section.position,
+      })
+    }
+
+    if (section.dataSlideIndex === undefined) {
+      base.issues.push({
+        type: "missing_data_slide_index",
+        severity: "error",
+        message: `Slide ${section.position} is missing data-slide-index.`,
+        slidePosition: section.position,
+        expectedIndex,
+      })
+      return
+    }
+
+    const actualIndex = Number(section.dataSlideIndex)
+    if (!Number.isInteger(actualIndex) || actualIndex < 1 || String(actualIndex) !== section.dataSlideIndex.trim()) {
+      base.issues.push({
+        type: "invalid_data_slide_index",
+        severity: "error",
+        message: `Slide ${section.position} has invalid data-slide-index=${JSON.stringify(section.dataSlideIndex)}; expected a positive 1-based integer.`,
+        slidePosition: section.position,
+        expectedIndex,
+      })
+      return
+    }
+
+    base.actualIndexes.push(actualIndex)
+    if (seen.has(actualIndex)) {
+      base.issues.push({
+        type: "duplicate_data_slide_index",
+        severity: "error",
+        message: `Slide ${section.position} repeats data-slide-index=${actualIndex}.`,
+        slidePosition: section.position,
+        actualIndex,
+      })
+    }
+    seen.add(actualIndex)
+
+    if (expectedIndex !== undefined && actualIndex !== expectedIndex) {
+      base.issues.push({
+        type: "slide_index_mismatch",
+        severity: "error",
+        message: `Slide ${section.position} has data-slide-index=${actualIndex}, but DECKS.json expects ${expectedIndex}.`,
+        slidePosition: section.position,
+        expectedIndex,
+        actualIndex,
+      })
+    }
+  })
+
+  return finalize(base)
+}
+
+export function assertDeckHtmlContractValid(workspaceRoot: string, filePath: string): void {
+  const report = validateDeckHtmlContract(workspaceRoot, filePath)
+  if (report.status !== "invalid") return
+  throw new Error(
+    "Deck HTML contract validation failed. Fix slide identity before inspection or export.\n\n" +
+    formatDeckHtmlContractReport(report)
+  )
+}
+
+export function formatDeckHtmlContractReport(report: DeckHtmlContractReport): string {
+  const lines = [
+    `Status: ${report.status}`,
+    `File: ${report.filePath}`,
+  ]
+  if (report.deckSlug) lines.push(`Deck: ${report.deckSlug}`)
+  if (report.activeHtmlPath) lines.push(`Active HTML target: ${report.activeHtmlPath}`)
+  if (report.expectedIndexes.length > 0) lines.push(`Expected slide indexes: ${report.expectedIndexes.join(", ")}`)
+  if (report.actualIndexes.length > 0) lines.push(`Actual slide indexes: ${report.actualIndexes.join(", ")}`)
+
+  if (report.issues.length > 0) {
+    lines.push("", "Errors:")
+    for (const issue of report.issues) lines.push(`- ${issue.message}`)
+  }
+  if (report.warnings.length > 0) {
+    lines.push("", "Warnings:")
+    for (const warning of report.warnings) lines.push(`- ${warning.message}`)
+  }
+  if (report.status === "skipped" && report.warnings.length > 0) {
+    lines.push("", "Note: skipped reports do not block standalone HTML files.")
+  }
+
+  return lines.join("\n")
+}
+
+function extractSlideSections(html: string): SlideSectionAttrs[] {
+  const sections: SlideSectionAttrs[] = []
+  const sectionTagPattern = /<section\b([^>]*)>/gi
+  let match: RegExpExecArray | null
+  while ((match = sectionTagPattern.exec(html))) {
+    const attrs = match[1] ?? ""
+    if (!/\bclass\s*=\s*(["'])[^"']*\bslide\b[^"']*\1/i.test(attrs)) continue
+    sections.push({
+      position: sections.length + 1,
+      dataSlideIndex: readAttr(attrs, "data-slide-index"),
+      dataIndex: readAttr(attrs, "data-index"),
+    })
+  }
+  return sections
+}
+
+function readAttr(attrs: string, name: string): string | undefined {
+  const pattern = new RegExp(`\\b${escapeRegExp(name)}\\s*=\\s*(["'])(.*?)\\1`, "i")
+  return pattern.exec(attrs)?.[2]
+}
+
+function expectedSlideIndexes(deck: DeckSpec): number[] {
+  return deck.slides.map((slide) => slide.index)
+}
+
+function finalize(base: Omit<DeckHtmlContractReport, "status" | "ok">): DeckHtmlContractReport {
+  const status: DeckHtmlContractStatus = base.issues.length > 0 ? "invalid" : "valid"
+  return { ...base, status, ok: status === "valid" }
+}
+
+function skipped(base: Omit<DeckHtmlContractReport, "status" | "ok">, message: string): DeckHtmlContractReport {
+  return {
+    ...base,
+    status: "skipped",
+    ok: true,
+    warnings: [{ type: "no_matching_deck_spec", severity: "warning", message }],
+  }
+}
+
+function singleDeckKey(decks: Record<string, DeckSpec>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+function workspaceRelative(root: string, target: string): string {
+  return relative(root, target).split(sep).join("/")
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}