@cyber-dash-tech/revela 0.15.0 → 0.15.1

package/lib/qa/checks.ts

@@ -1,17 +1,18 @@
 /**
  * lib/qa/checks.ts
  *
- * Geometry-based layout quality checks. The active default path only checks
- * overflow; softer visual heuristics are kept here for future opt-in use.
+ * Browser-measured slide quality checks. The active default path checks hard
+ * artifact failures plus a content-substance warning; older soft visual
+ * heuristics are kept here for future opt-in use.
  *
- * Dimension 1: Overflow    — elements exceed canvas bounds (correctness)
- * Dimension 2: Balance     — content centroid & distribution (fill, sparsity)
- * Dimension 3: Rhythm      — spacing regularity & internal whitespace
+ * Dimension 1: Canvas      — exact 1920x1080 slide/canvas size
+ * Dimension 2: Overflow    — scrollbars, element overflow, and text clipping
+ * Dimension 3: Density     — claim/evidence/source substance warnings
  * Dimension 4: Compliance  — CSS classes match the active design's vocabulary
  *
  * All checks operate on SlideMetrics produced by measure.ts.
- * Dimensions 1–4 are geometry-only (no CSS class-name assumptions).
- * Dimension 5 requires an allowedClasses vocabulary from the design system.
+ * Design component compliance requires an allowedClasses vocabulary from the
+ * design system and is run by combined artifact QA.
  */
 
 import type { SlideMetrics, ElementInfo, Rect } from "./measure"
@@ -22,9 +23,10 @@ import { CANVAS_W, CANVAS_H } from "./measure"
 export type IssueSeverity = "error" | "warning" | "info"
 
 export interface LayoutIssue {
-  type: "overflow" | "balance" | "symmetry" | "rhythm" | "compliance"
+  type: "canvas" | "scrollbar" | "overflow" | "text_overflow" | "density" | "balance" | "symmetry" | "rhythm" | "compliance"
   /** Sub-category within the dimension */
-  sub?: "centroid_offset" | "bottom_gap" | "sparse"
+  sub?: "size_mismatch" | "page_scroll" | "text_clipped" | "thin_content"
+      | "centroid_offset" | "bottom_gap" | "sparse"
       | "height_mismatch" | "density_mismatch"
       | "gap_variance"
       | "unknown_class" | "novel_css_rule"
@@ -75,6 +77,9 @@ const T = {
   GAP_MIN_MEAN: 10,
   // Rhythm — min children count to check gap variance
   GAP_MIN_CHILDREN: 3,
+  CANVAS_TOLERANCE: 1,
+  DENSITY_MIN_TEXT_POINTS: 70,
+  DENSITY_MIN_UNITS: 2,
 }
 
 // ── Geometry helpers ──────────────────────────────────────────────────────────
@@ -172,6 +177,42 @@ function collectLeaves(el: ElementInfo): ElementInfo[] {
 
 // ── Dimension 1: Overflow ─────────────────────────────────────────────────────
 
+function checkCanvas(metrics: SlideMetrics): LayoutIssue[] {
+  const issues: LayoutIssue[] = []
+  const tol = T.CANVAS_TOLERANCE
+  const canvasBad = Math.abs(metrics.canvasRect.width - CANVAS_W) > tol || Math.abs(metrics.canvasRect.height - CANVAS_H) > tol
+  const slideBad = Math.abs(metrics.slideRect.width - CANVAS_W) > tol || Math.abs(metrics.slideRect.height - CANVAS_H) > tol
+
+  if (canvasBad || slideBad) {
+    issues.push({
+      type: "canvas",
+      sub: "size_mismatch",
+      severity: "error",
+      detail: `Slide and canvas must render exactly ${CANVAS_W}x${CANVAS_H}px. Measured slide ${Math.round(metrics.slideRect.width)}x${Math.round(metrics.slideRect.height)}px, canvas ${Math.round(metrics.canvasRect.width)}x${Math.round(metrics.canvasRect.height)}px.`,
+      data: {
+        expectedWidth: CANVAS_W,
+        expectedHeight: CANVAS_H,
+        slideWidth: Math.round(metrics.slideRect.width),
+        slideHeight: Math.round(metrics.slideRect.height),
+        canvasWidth: Math.round(metrics.canvasRect.width),
+        canvasHeight: Math.round(metrics.canvasRect.height),
+      },
+    })
+  }
+
+  return issues
+}
+
+function checkScrollbars(metrics: SlideMetrics): LayoutIssue[] {
+  if (!metrics.hasScrollbars) return []
+  return [{
+    type: "scrollbar",
+    sub: "page_scroll",
+    severity: "error",
+    detail: "Rendered slide/page has scrollbars at 1920x1080. Deck slides must fit the fixed canvas without document, body, or slide scrolling.",
+  }]
+}
+
 /**
  * Check 1: Overflow — elements extending beyond canvas boundaries.
  * Hard correctness check; applies to all slide types.
@@ -205,6 +246,45 @@ function checkOverflow(metrics: SlideMetrics): LayoutIssue[] {
   return issues
 }
 
+function checkTextOverflow(metrics: SlideMetrics): LayoutIssue[] {
+  const issues: LayoutIssue[] = []
+
+  function walk(els: ElementInfo[]) {
+    for (const el of els) {
+      if (!el.visible) continue
+      if (el.textOverflow) {
+        issues.push({
+          type: "text_overflow",
+          sub: "text_clipped",
+          severity: "error",
+          detail: `Text appears clipped inside \`${el.selector}\`${el.text ? `: "${el.text}"` : ""}. Increase container size, reduce copy, or adjust font/line-height.`,
+          data: { selector: el.selector, text: el.text ?? "" },
+        })
+      }
+      if (el.children.length > 0) walk(el.children)
+    }
+  }
+
+  walk(metrics.elements)
+  return issues
+}
+
+function checkContentDensity(metrics: SlideMetrics): LayoutIssue[] {
+  if (!metrics.slideQa) return []
+  const { bodyTextPoints, contentUnits, supportReferences } = metrics.contentStats
+  const thinText = bodyTextPoints < T.DENSITY_MIN_TEXT_POINTS
+  const thinUnits = contentUnits < T.DENSITY_MIN_UNITS
+  if (!thinText && !thinUnits) return []
+
+  return [{
+    type: "density",
+    sub: "thin_content",
+    severity: "warning",
+    detail: `Content slide may not have enough claim/evidence substance: ${bodyTextPoints} non-title text point(s), ${contentUnits} recognizable content unit(s), ${supportReferences} evidence/source/claim reference(s). Add concrete claim points, evidence, metrics, chart/table support, or source/caveat text if this is not a deliberate focus slide.`,
+    data: { bodyTextPoints, contentUnits, supportReferences },
+  }]
+}
+
 // ── Dimension 2: Balance ──────────────────────────────────────────────────────
 
 /**
@@ -542,7 +622,13 @@ export function runChecks(
   const slides: SlideReport[] = []
 
   for (const metrics of allMetrics) {
-    const issues: LayoutIssue[] = [...checkOverflow(metrics)]
+    const issues: LayoutIssue[] = [
+      ...checkCanvas(metrics),
+      ...checkScrollbars(metrics),
+      ...checkOverflow(metrics),
+      ...checkTextOverflow(metrics),
+      ...checkContentDensity(metrics),
+    ]
 
     slides.push({ index: metrics.index, title: metrics.title, issues })
   }
@@ -605,7 +691,11 @@ export function formatReport(report: QAReport): string {
     `### Action Required`,
     ``,
     `Please fix the above hard-error issues in the HTML file. For each issue type:`,
+    `- **canvas**: ensure each slide and .slide-canvas render exactly 1920x1080px, not merely any 16:9 size.`,
+    `- **scrollbar**: remove document/body/slide scrolling; content must fit inside the fixed 1920x1080 canvas.`,
     `- **overflow**: reduce font size, padding, or content amount for the affected element.`,
+    `- **text_overflow**: increase the text container size, reduce copy, or adjust font/line-height so text is not clipped.`,
+    `- **density/thin_content**: add concrete claim/evidence points, metrics, chart/table support, or source/caveat text. This is a warning for content substance, not a blank-space failure.`,
     `- **compliance/unknown_class**: an HTML element uses a CSS class not defined in the active design. Replace it with a class from the Component Index or Layout Index. Fetch the component/layout details with the \`revela-designs\` tool if needed.`,
     `- **compliance/novel_css_rule**: \`<style>\` defines a CSS class that is not part of the active design. Remove the custom rule and use the design's existing component styles. For minor spacing/sizing adjustments, use inline \`style=""\` instead.`,
   )

package/lib/qa/index.ts

@@ -1,9 +1,9 @@
 /**
  * lib/qa/index.ts
  *
- * Public entry point for hard-error slide QA.
- * Runs overflow measurement only. Static design compliance is handled by a
- * separate post-write/post-patch/post-edit hook.
+ * Public entry point for browser-rendered slide QA.
+ * Combined artifact QA, including contract and component compliance, lives in
+ * `lib/qa/artifact.ts`.
  */
 
 import { measureSlides } from "./measure"
@@ -18,12 +18,14 @@ export type { RunChecksOptions } from "./checks"
  * Run hard-error QA on `htmlFilePath`.
  *
  * 1. Opens the file in headless Chrome (puppeteer-core)
- * 2. Measures each .slide element's geometry + CSS class definitions
- * 3. Runs hard-error overflow checks only
+ * 2. Measures each .slide element's geometry, scroll state, text clipping,
+ *    content-density signals, and CSS class definitions
+ * 3. Runs browser QA checks for exact 1920x1080 slides, scrollbars, overflow,
+ *    text clipping, and claim/evidence density warnings
  * 4. Returns a structured QAReport
  *
  * The optional `vocabulary` argument is retained for backward compatibility;
- * compliance is intentionally not part of hard-error QA.
+ * design compliance is handled by combined artifact QA.
  *
  * Throws if the file cannot be opened or Chrome is not found.
  */

package/lib/qa/measure.ts

@@ -49,6 +49,19 @@ export interface ElementInfo {
   children: ElementInfo[]
   /** all CSS class names on this element */
   classList: string[]
+  /** visible text excerpt for text overflow diagnostics */
+  text?: string
+  /** whether text content is clipped inside this element */
+  textOverflow?: boolean
+}
+
+export interface SlideContentStats {
+  /** Non-title effective text points: English words + CJK characters. */
+  bodyTextPoints: number
+  /** Recognizable semantic content units such as boxes, cards, evidence, charts, tables, media, metrics, bullets. */
+  contentUnits: number
+  /** Evidence/source/caveat-like references visible on the slide. */
+  supportReferences: number
 }
 
 export interface SlideMetrics {
@@ -65,10 +78,16 @@ export interface SlideMetrics {
   slideQa: boolean
   /** bounding box of the slide-canvas element itself (post-scale) */
   canvasRect: Rect
+  /** bounding box of the .slide element itself (post-scale) */
+  slideRect: Rect
+  /** whether document/body/slide has scrollbars at 1920x1080 */
+  hasScrollbars: boolean
   /** top-level visible children of .slide-canvas */
   elements: ElementInfo[]
   /** union bounding box of all visible leaf elements */
   contentRect: Rect
+  /** text/content-density signals for content slides */
+  contentStats: SlideContentStats
 }
 
 /**
@@ -207,6 +226,29 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             visible: boolean
             children: EI[]
             classList: string[]
+            text?: string
+            textOverflow?: boolean
+          }
+
+          function textPoints(text: string): number {
+            const normalized = text.replace(/\s+/g, " ").trim()
+            if (!normalized) return 0
+            const cjk = (normalized.match(/[\u3400-\u9fff\uf900-\ufaff]/g) || []).length
+            const words = (normalized.replace(/[\u3400-\u9fff\uf900-\ufaff]/g, " ").match(/[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)*/g) || []).length
+            return cjk + words
+          }
+
+          function isSemanticContentUnit(el: Element): boolean {
+            const tag = el.tagName.toLowerCase()
+            if (["li", "table", "figure", "img", "svg", "canvas", "blockquote"].includes(tag)) return true
+            const cls = Array.from(el.classList).join(" ")
+            return /\b(box|card|claim|evidence|source|caveat|metric|stat|quote|media|chart|echart|table|step|roadmap|toc-item|bullet)\b/i.test(cls)
+          }
+
+          function isSupportReference(el: Element): boolean {
+            const text = (el.textContent || "").replace(/\s+/g, " ").trim()
+            const cls = Array.from(el.classList).join(" ")
+            return /\b(evidence|source|caveat|claim|support|citation|note)\b/i.test(cls) || /\b(source|evidence|caveat|claim|来源|证据|出处|风险|假设)\b/i.test(text)
           }
 
           function collectChildren(
@@ -220,6 +262,11 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             for (const child of Array.from(el.children)) {
               if (!isVisible(child)) continue
               const rawR = child.getBoundingClientRect()
+              const text = (child.textContent || "").replace(/\s+/g, " ").trim()
+              const textOverflow = textPoints(text) > 0 && (
+                (child as HTMLElement).scrollHeight > (child as HTMLElement).clientHeight + 2 ||
+                (child as HTMLElement).scrollWidth > (child as HTMLElement).clientWidth + 2
+              )
               const cls = child.className || ""
               if (
                 typeof cls === "string" &&
@@ -235,6 +282,8 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
                 rect: relR,
                 visible: true,
                 classList: Array.from(child.classList),
+                text: text.slice(0, 160),
+                textOverflow,
                 children: collectChildren(child, offsetTop, offsetLeft, depth + 1),
               })
             }
@@ -273,6 +322,7 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
           if (!canvas) return null
 
           const canvasRaw = canvas.getBoundingClientRect()
+          const slideRaw = (slide as HTMLElement).getBoundingClientRect()
           // Use canvas top-left as the coordinate origin
           const offsetTop = canvasRaw.top
           const offsetLeft = canvasRaw.left
@@ -286,8 +336,40 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             height: canvasRaw.height,
           }
 
+          const slideRect = {
+            left: 0,
+            top: 0,
+            right: slideRaw.width,
+            bottom: slideRaw.height,
+            width: slideRaw.width,
+            height: slideRaw.height,
+          }
+
           const elements = collectChildren(canvas, offsetTop, offsetLeft)
 
+          let bodyTextPoints = 0
+          let contentUnits = 0
+          let supportReferences = 0
+          for (const el of Array.from(canvas.querySelectorAll("*"))) {
+            if (!isVisible(el)) continue
+            if (/^H[1-2]$/.test(el.tagName)) continue
+            const text = (el.textContent || "").replace(/\s+/g, " ").trim()
+            if (text) bodyTextPoints += textPoints(text)
+            if (isSemanticContentUnit(el)) contentUnits++
+            if (isSupportReference(el)) supportReferences++
+          }
+
+          const doc = document.documentElement
+          const body = document.body
+          const slideEl = slide as HTMLElement
+          const hasScrollbars =
+            doc.scrollWidth > window.innerWidth + 2 ||
+            doc.scrollHeight > window.innerHeight + 2 ||
+            body.scrollWidth > window.innerWidth + 2 ||
+            body.scrollHeight > window.innerHeight + 2 ||
+            slideEl.scrollWidth > slideEl.clientWidth + 2 ||
+            slideEl.scrollHeight > slideEl.clientHeight + 2
+
           const titleEl = canvas.querySelector("h1, h2")
           const title = titleEl
             ? (titleEl.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80)
@@ -298,8 +380,11 @@ export async function measureSlides(htmlFilePath: string): Promise<MeasurementRe
             title,
             slideQa,
             canvasRect,
+            slideRect,
+            hasScrollbars,
             elements,
             contentRect: unionRect(elements),
+            contentStats: { bodyTextPoints, contentUnits, supportReferences },
           }
         },
         idx

package/lib/refine/open.ts

@@ -22,6 +22,10 @@ export interface OpenRefineDeckResult {
   mode: RefineMode
 }
 
+export interface EnsureRefineDeckOpenResult extends OpenRefineDeckResult {
+  skippedReason?: "live-session"
+}
+
 export interface OpenRefineDeckOptions {
   client: any
   sessionID: string
@@ -32,6 +36,21 @@ export interface OpenRefineDeckOptions {
 }
 
 export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
+  return openRefineDeckInternal(target, options, { skipLiveSession: false })
+}
+
+export function ensureRefineDeckOpenForChange(
+  target: string,
+  options: OpenRefineDeckOptions,
+): EnsureRefineDeckOpenResult {
+  return openRefineDeckInternal(target, options, { skipLiveSession: true })
+}
+
+function openRefineDeckInternal(
+  target: string,
+  options: OpenRefineDeckOptions,
+  behavior: { skipLiveSession: boolean },
+): EnsureRefineDeckOpenResult {
   const deck = resolveEditableDeck(options.workspaceRoot, target)
   const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
   assertDeckHtmlContractValid(options.workspaceRoot, deck.absoluteFile)
@@ -53,7 +72,7 @@ export function openRefineDeck(target: string, options: OpenRefineDeckOptions):
     mode,
   })
   const url = `${refineServer.baseUrl}/refine?token=${encodeURIComponent(session.token)}`
-  const shouldOpen = options.openBrowser !== false
+  const shouldOpen = options.openBrowser !== false && !(behavior.skipLiveSession && session.live)
   if (shouldOpen) (options.openUrl ?? openUrl)(url)
 
   return {
@@ -66,5 +85,6 @@ export function openRefineDeck(target: string, options: OpenRefineDeckOptions):
     liveSession: session.live,
     openedBrowser: shouldOpen,
     mode,
+    skippedReason: behavior.skipLiveSession && session.live ? "live-session" : undefined,
   }
 }

package/lib/refine/server.ts

@@ -634,6 +634,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .resize-handle:hover::before, body.resizing .resize-handle::before { height: 52px; background: #94a3b8; box-shadow: 0 0 0 4px rgba(148,163,184,.16); }
     iframe { display: block; width: 100%; height: 100%; border: 0; background: #fff; }
     .hitbox { position: absolute; inset: 0; z-index: 2; cursor: crosshair; background: transparent; }
+    .deck-nav { position: absolute; left: 50%; bottom: 18px; z-index: 4; display: inline-flex; align-items: center; gap: 8px; transform: translateX(-50%); padding: 7px; border: 1px solid rgba(148,163,184,.42); border-radius: 999px; background: rgba(15,23,42,.76); box-shadow: 0 16px 44px rgba(15,23,42,.24); backdrop-filter: blur(14px); -webkit-backdrop-filter: blur(14px); pointer-events: auto; }
+    .deck-nav button { width: auto; min-width: 84px; padding: 8px 12px; border-radius: 999px; background: rgba(255,255,255,.12); color: #fff; box-shadow: none; font-size: 12px; font-weight: 900; }
+    .deck-nav button:hover:not(:disabled) { background: rgba(255,255,255,.22); }
+    .deck-nav button:disabled { opacity: .38; }
+    .deck-nav-status { min-width: 76px; color: #e2e8f0; font-size: 12px; font-weight: 900; text-align: center; font-variant-numeric: tabular-nums; }
     aside { display: flex; flex-direction: column; gap: 16px; padding: 20px; background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%); overflow: auto; }
     h1 { margin: 0; font-size: 18px; line-height: 1.2; letter-spacing: -.01em; color: #0f172a; }
     .wordmark { font-family: Garamond, "Iowan Old Style", Georgia, serif; font-size: 21px; letter-spacing: .08em; font-weight: 600; }
@@ -681,12 +686,12 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     button { width: 100%; padding: 12px 14px; border: 0; border-radius: 12px; background: #2563eb; color: #ffffff; font-weight: 800; cursor: pointer; box-shadow: 0 10px 24px rgba(37,99,235,.22); }
     button:disabled { cursor: not-allowed; opacity: .5; }
     .status { min-height: 20px; color: #475569; font-size: 13px; line-height: 1.45; }
-    @media (max-width: 900px) { .app { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; } .resize-handle { display: none; } aside { max-height: 48vh; } }
+    @media (max-width: 900px) { .app { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; } .resize-handle { display: none; } aside { max-height: 48vh; } .deck-nav { bottom: 10px; } }
   </style>
 </head>
 <body>
   <main class="app">
-    <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div></section>
+    <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div><nav class="deck-nav" aria-label="Deck navigation"><button id="deckPrev" type="button" title="Previous slide (ArrowLeft / ArrowUp / PageUp)">Previous</button><div id="deckCounter" class="deck-nav-status" aria-live="polite">-- / --</div><button id="deckNext" type="button" title="Next slide (ArrowRight / ArrowDown / Space / PageDown)">Next</button></nav></section>
     <div id="resizeHandle" class="resize-handle" role="separator" aria-label="Resize editor panel" aria-orientation="vertical" title="Drag to resize editor. Double-click to reset."></div>
     <aside>
       <div>
@@ -752,6 +757,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         bound: false,
         commentRange: null,
         resizeDrag: null,
+        deckSlideIndex: 0,
+        deckSlideCount: 0,
         mode: defaultMode === 'inspect' ? 'inspect' : 'edit',
         inspecting: false,
         activeInspectRequestId: '',
@@ -762,6 +769,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         frame: null,
         hitbox: null,
         resizeHandle: null,
+        deckPrev: null,
+        deckNext: null,
+        deckCounter: null,
         selectionSummary: null,
         selectionChips: null,
         editTab: null,
@@ -792,6 +802,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           els.frame = document.getElementById('deck');
           els.hitbox = document.getElementById('hitbox');
           els.resizeHandle = document.getElementById('resizeHandle');
+          els.deckPrev = document.getElementById('deckPrev');
+          els.deckNext = document.getElementById('deckNext');
+          els.deckCounter = document.getElementById('deckCounter');
           els.selectionSummary = document.getElementById('selectionSummary');
           els.selectionChips = document.getElementById('selectionChips');
           els.editTab = document.getElementById('editTab');
@@ -808,7 +821,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 
           els.inspectLanguage = document.getElementById('inspectLanguage');
 
-          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.status) {
+          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.deckPrev || !els.deckNext || !els.deckCounter || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.status) {
             throw new Error('Editor boot failed: required DOM nodes are missing.');
           }
 
@@ -828,7 +841,18 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         state.bound = true;
         els.frame.addEventListener('load', initFrame);
         document.addEventListener('keydown', (event) => {
-          if (event.key === 'Escape') clearHover();
+          if (event.key === 'Escape') {
+            clearHover();
+            return;
+          }
+          if (isTextInputTarget(event.target) || event.metaKey || event.ctrlKey || event.altKey) return;
+          if (['ArrowDown', 'ArrowRight', ' ', 'PageDown'].includes(event.key)) {
+            event.preventDefault();
+            nextDeckSlide();
+          } else if (['ArrowUp', 'ArrowLeft', 'PageUp'].includes(event.key)) {
+            event.preventDefault();
+            prevDeckSlide();
+          }
         });
         els.comment.addEventListener('input', () => {
           saveCommentRange();
@@ -854,6 +878,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }, { passive: false });
         els.resizeHandle.addEventListener('pointerdown', startEditorResize);
         els.resizeHandle.addEventListener('dblclick', resetEditorWidth);
+        els.deckPrev.addEventListener('click', prevDeckSlide);
+        els.deckNext.addEventListener('click', nextDeckSlide);
         els.send.addEventListener('click', sendComment);
         els.inspectButton.addEventListener('click', inspectCurrentSelection);
         els.inspectLanguage.addEventListener('change', () => {
@@ -940,6 +966,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             renderReferenceOutlines();
           }, true);
           const slides = getSlides(doc);
+          syncDeckNavigation();
           updateSendState();
           if (state.pendingRefreshMessage) {
             state.pendingRefreshMessage = false;
@@ -952,6 +979,102 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
       }
 
+      function isTextInputTarget(target) {
+        if (!target || !(target instanceof Element)) return false;
+        const tag = target.tagName.toLowerCase();
+        return tag === 'input' || tag === 'textarea' || tag === 'select' || target.isContentEditable || Boolean(target.closest('[contenteditable="true"]'));
+      }
+
+      function syncDeckNavigation() {
+        try {
+          const doc = els.frame.contentDocument;
+          const slides = doc ? getSlides(doc) : [];
+          state.deckSlideCount = slides.length;
+          state.deckSlideIndex = Math.max(0, Math.min(state.deckSlideIndex, Math.max(0, slides.length - 1)));
+          updateDeckNavControls();
+        } catch {
+          state.deckSlideCount = 0;
+          state.deckSlideIndex = 0;
+          updateDeckNavControls();
+        }
+      }
+
+      function updateDeckNavControls() {
+        const total = state.deckSlideCount;
+        const current = total > 0 ? state.deckSlideIndex + 1 : 0;
+        els.deckCounter.textContent = total > 0 ? current + ' / ' + total : '-- / --';
+        els.deckPrev.disabled = total <= 1 || state.deckSlideIndex <= 0;
+        els.deckNext.disabled = total <= 1 || state.deckSlideIndex >= total - 1;
+      }
+
+      function prevDeckSlide() {
+        goToDeckSlide(state.deckSlideIndex - 1);
+      }
+
+      function nextDeckSlide() {
+        goToDeckSlide(state.deckSlideIndex + 1);
+      }
+
+      function goToDeckSlide(index) {
+        try {
+          const doc = els.frame.contentDocument;
+          const win = els.frame.contentWindow;
+          if (!doc || !win) return;
+          const slides = getSlides(doc);
+          if (!slides.length) {
+            syncDeckNavigation();
+            return;
+          }
+          const clamped = Math.max(0, Math.min(slides.length - 1, index));
+          const nav = win.RevelaDeckNav;
+          let handled = false;
+          if (nav && typeof nav.goTo === 'function') {
+            try {
+              nav.goTo(clamped);
+              handled = true;
+            } catch {}
+          } else if (nav && clamped > state.deckSlideIndex && typeof nav.next === 'function') {
+            try {
+              nav.next();
+              handled = true;
+            } catch {}
+          } else if (nav && clamped < state.deckSlideIndex && typeof nav.prev === 'function') {
+            try {
+              nav.prev();
+              handled = true;
+            } catch {}
+          }
+          if (!handled) applyFallbackDeckNavigation(win, doc, slides, clamped);
+          state.deckSlideIndex = clamped;
+          updateDeckNavControls();
+          renderHoverOutline(state.hoverEl);
+          renderReferenceOutlines();
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function applyFallbackDeckNavigation(win, doc, slides, index) {
+        const target = slides[index];
+        const usesOverlaySlides = slides.some((slide) => {
+          const style = win.getComputedStyle(slide);
+          return style.position === 'absolute' || style.position === 'fixed' || style.opacity === '0' || slide.style.opacity !== '';
+        });
+        if (usesOverlaySlides) {
+          slides.forEach((slide, i) => {
+            slide.style.opacity = i === index ? '1' : '0';
+            slide.style.pointerEvents = i === index ? 'auto' : 'none';
+          });
+          win.scrollTo?.(0, 0);
+          return;
+        }
+        if (target && typeof target.scrollIntoView === 'function') {
+          target.scrollIntoView({ block: 'start', inline: 'nearest', behavior: 'auto' });
+          return;
+        }
+        doc.defaultView?.scrollTo?.(0, index * win.innerHeight);
+      }
+
       function startDeckVersionPolling() {
         pollDeckVersion();
         window.setInterval(pollDeckVersion, 2000);

package/lib/workspace-state/types.ts

@@ -98,6 +98,7 @@ export type WorkspaceActionType =
   | "research.gap_closed"
   | "narrative.upserted"
   | "deck.plan_compiled"
+  | "deck.plan_confirmed"
   | "artifact.coverage_backfilled"
   | "evidence.candidate_generated"
   | "evidence.binding_applied"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",