@cyber-dash-tech/revela 0.14.0 → 0.15.1

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.14.0",
+  "version": "0.15.1",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",