fix(web): make deck thumbnails drive deck-stage previews (#6950)

* fix(web): sync deck-stage thumbnail navigation

* fix(web): keep prototype annotations out of deck navigation

* fix(web): distinguish legacy deck slides from annotations

Author: lefarcen

apps/web/src/components/FileViewer.tsx

@@ -154,6 +154,7 @@ import {
   planDeckImageCapture,
   requestPreviewSnapshot,
   sourceLooksLikeExportableDeck,
+  sourceLooksLikeNavigableDeck,
   type ExportProgress,
   type ImageExportFormat,
 } from '../runtime/exports';
@@ -3242,7 +3243,7 @@ function sourceLooksLikeDeckPreview(source: string | null | undefined): boolean
   if (!source) return false;
   return (
     /class\s*=\s*['"](?:[^'"]*\s)?slide(?:\s|['"])/i.test(source) ||
-    sourceLooksLikeExportableDeck(source)
+    sourceLooksLikeNavigableDeck(source)
   );
 }
 

apps/web/src/runtime/deck-slide-structure.ts

@@ -0,0 +1,107 @@
+import {
+  DECK_LEGACY_SCREEN_SLIDE_SELECTOR,
+  legacyDeckScreenNumber,
+} from '@open-design/contracts/runtime/deck-stage-fallback';
+
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+function hasDistinctScreenNumbers(elements: Element[]): boolean {
+  const numbers = new Set<number>();
+  for (const element of elements) {
+    const number = legacyDeckScreenNumber(element.getAttribute('data-screen-label'));
+    if (number !== null) numbers.add(number);
+  }
+  return numbers.size > 1;
+}
+
+/**
+ * Find the compatibility-only shape used by older containerless decks. A
+ * collection is valid only when numbered, page-like sections are direct
+ * siblings; arbitrary annotation nodes elsewhere in a prototype never join it.
+ */
+export function collectLegacyDeckScreenSlides(root: ParentNode): Element[] {
+  const groups = new Map<ParentNode, Element[]>();
+  for (const element of root.querySelectorAll(DECK_LEGACY_SCREEN_SLIDE_SELECTOR)) {
+    if (legacyDeckScreenNumber(element.getAttribute('data-screen-label')) === null) continue;
+    const parent = element.parentNode;
+    if (!parent) continue;
+    const group = groups.get(parent);
+    if (group) group.push(element);
+    else groups.set(parent, [element]);
+  }
+
+  let best: Element[] = [];
+  for (const group of groups.values()) {
+    if (group.length > best.length && hasDistinctScreenNumbers(group)) best = group;
+  }
+  return best;
+}
+
+function screenLabelFromTag(tag: string): string | null {
+  const match = /\bdata-screen-label\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/i.exec(tag);
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+
+/**
+ * SSR-safe source equivalent of collectLegacyDeckScreenSlides. This deliberately
+ * tokenizes only enough HTML to preserve direct-parent identity; scripts,
+ * styles, and comments are removed first so markup-looking strings cannot
+ * manufacture slides.
+ */
+export function sourceHasLegacyDeckScreenSlides(source: string): boolean {
+  const sanitized = source
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '');
+  const tagPattern = /<\s*(\/?)\s*([a-z][\w:-]*)\b[^>]*>/gi;
+  const stack: Array<{ id: number; tag: string }> = [];
+  const groups = new Map<number, Set<number>>();
+  let nextId = 1;
+  let match: RegExpExecArray | null;
+
+  while ((match = tagPattern.exec(sanitized))) {
+    const closing = match[1] === '/';
+    const tagName = match[2]!.toLowerCase();
+    const tag = match[0];
+    if (closing) {
+      for (let index = stack.length - 1; index >= 0; index -= 1) {
+        if (stack[index]!.tag !== tagName) continue;
+        stack.length = index;
+        break;
+      }
+      continue;
+    }
+
+    const parentId = stack.at(-1)?.id ?? 0;
+    if (tagName === 'section') {
+      const number = legacyDeckScreenNumber(screenLabelFromTag(tag));
+      if (number !== null) {
+        const numbers = groups.get(parentId) ?? new Set<number>();
+        numbers.add(number);
+        groups.set(parentId, numbers);
+        if (numbers.size > 1) return true;
+      }
+    }
+
+    if (!VOID_ELEMENTS.has(tagName) && !/\/\s*>$/.test(tag)) {
+      stack.push({ id: nextId, tag: tagName });
+      nextId += 1;
+    }
+  }
+
+  return false;
+}

apps/web/src/runtime/deck-thumbnail-parser.ts

@@ -19,7 +19,12 @@
 
 import DOMPurify from 'dompurify';
 
-import { DECK_SLIDE_SELECTOR } from '@open-design/contracts/runtime/deck-stage-fallback';
+import {
+  DECK_EXPLICIT_SLIDE_SELECTOR,
+  DECK_SLIDE_SELECTOR,
+  DECK_STRUCTURED_SLIDE_SELECTOR,
+} from '@open-design/contracts/runtime/deck-stage-fallback';
+import { collectLegacyDeckScreenSlides } from './deck-slide-structure';
 
 export type DeckThumbnailFallbackReason =
   | 'no-dom-parser'
@@ -59,16 +64,6 @@ const DEFAULT_DESIGN_WIDTH = 1920;
 const DEFAULT_DESIGN_HEIGHT = 1080;
 const MAX_SLIDES = 200;
 
-// Structured-first slide detection, mirroring the deck bridge's `slides()` in
-// srcdoc.ts: prefer slides that are direct children of a recognized stage so
-// decorative `.slide` markup elsewhere isn't miscounted, then fall back to the
-// shared selector.
-const STRUCTURED_SLIDE_SELECTOR =
-  'deck-stage > .slide, .deck > .slide, .deck-stage > .slide, .deck-shell > .slide, ' +
-  '#deck > .slide, body > .slide, ' +
-  'deck-stage > [data-screen-label], .deck-stage > [data-screen-label], ' +
-  '#deck > [data-screen-label], body > [data-screen-label]';
-
 const FONT_HOSTS = new Set([
   'fonts.googleapis.com',
   'fonts.gstatic.com',
@@ -205,9 +200,18 @@ function rewriteViewportUnits(css: string, width: number, height: number): strin
 }
 
 function collectSlideElements(doc: Document): Element[] {
-  const structured = Array.from(doc.querySelectorAll(STRUCTURED_SLIDE_SELECTOR));
+  const deckStage = doc.querySelector('deck-stage');
+  if (deckStage) {
+    const nested = Array.from(deckStage.querySelectorAll(DECK_SLIDE_SELECTOR));
+    const direct = nested.filter((slide) => slide.parentElement === deckStage);
+    if (direct.length > 0) return direct;
+    if (nested.length > 0) return nested;
+  }
+  const structured = Array.from(doc.querySelectorAll(DECK_STRUCTURED_SLIDE_SELECTOR));
   if (structured.length > 0) return structured;
-  return Array.from(doc.querySelectorAll(DECK_SLIDE_SELECTOR));
+  const explicit = Array.from(doc.querySelectorAll(DECK_EXPLICIT_SLIDE_SELECTOR));
+  if (explicit.length > 0) return explicit;
+  return collectLegacyDeckScreenSlides(doc);
 }
 
 // Walk from the slide's parent up to (but excluding) <body>/<html>, so

apps/web/src/runtime/exports.ts

@@ -24,6 +24,7 @@ import {
   workspaceProjectHeaders,
   workspaceResourceUrl,
 } from '../collab/workspace-identity';
+import { sourceHasLegacyDeckScreenSlides } from './deck-slide-structure';
 
 // Re-exported so app components can gate desktop-only export paths without
 // importing the host package directly.
@@ -1010,10 +1011,9 @@ export async function exportProjectAsPptx(opts: {
 // structure such as `data-title` or a `.deck` wrapper. Deliberately DO NOT treat
 // a plain `.slide` class as proof of a deck: ordinary pages often use that token
 // for carousels/testimonials and still need full-page/scroll-stitch capture.
-export function sourceLooksLikeExportableDeck(source: string | null | undefined): boolean {
-  if (!source) return false;
+function sourceLooksLikeStructuredDeck(source: string): boolean {
   return (
-    /<deck-stage[\s/>]|\bdata-screen-label\s*=|class\s*=\s*['"](?:[^'"]*\s)?(?:deck-slide|ppt-slide)(?:\s|['"])/i.test(
+    /<deck-stage[\s/>]|class\s*=\s*['"](?:[^'"]*\s)?(?:deck-slide|ppt-slide)(?:\s|['"])/i.test(
       source,
     ) ||
     /<[^>]*\bclass\s*=\s*['"](?:[^'"]*\s)?slide(?:\s|['"])[^>]*\bdata-title\s*=|<[^>]*\bdata-title\s*=[^>]*\bclass\s*=\s*['"](?:[^'"]*\s)?slide(?:\s|['"])/i.test(
@@ -1025,6 +1025,23 @@ export function sourceLooksLikeExportableDeck(source: string | null | undefined)
   );
 }
 
+export function sourceLooksLikeExportableDeck(source: string | null | undefined): boolean {
+  if (!source) return false;
+  return sourceLooksLikeStructuredDeck(source) || /\bdata-screen-label\s*=/i.test(source);
+}
+
+/**
+ * Viewer navigation needs stronger evidence than export. `data-screen-label`
+ * is shared with ordinary prototype annotations, so only explicit deck
+ * structure or a numbered sibling collection of legacy slide sections may
+ * turn the live preview into deck mode.
+ */
+export function sourceLooksLikeNavigableDeck(source: string | null | undefined): boolean {
+  if (!source) return false;
+  if (sourceLooksLikeStructuredDeck(source)) return true;
+  return sourceHasLegacyDeckScreenSlides(source);
+}
+
 // Decides how a current-slide / whole-deck / page image capture should run.
 // The off-screen renderer needs a concrete slide `index` for a CURRENT-slide
 // capture (Copy screenshot / annotation), but we only know the active slide when

apps/web/src/runtime/srcdoc.ts

@@ -14,7 +14,14 @@
  *   { type: 'od:slide-state', active: number, count: number }
  * after every navigation so the host can render its own counter / dots.
  */
-import { injectDeckStageFallback } from '@open-design/contracts/runtime/deck-stage-fallback';
+import {
+  DECK_EXPLICIT_SLIDE_SELECTOR,
+  DECK_LEGACY_SCREEN_LABEL_RE_SOURCE,
+  DECK_LEGACY_SCREEN_SLIDE_SELECTOR,
+  DECK_SLIDE_SELECTOR,
+  DECK_STRUCTURED_SLIDE_SELECTOR,
+  injectDeckStageFallback,
+} from '@open-design/contracts/runtime/deck-stage-fallback';
 import { buildPreviewObservabilityBridge } from '@open-design/contracts/runtime/preview-observability';
 
 import {
@@ -2882,15 +2889,97 @@ function injectDeckBridge(
     }, true);
   }
   window.__odDeckBridgeOwnListenerInstall = false;
+  function deckStageSlides(stage){
+    if (!stage) return [];
+    var nested = stage.querySelectorAll(${JSON.stringify(DECK_SLIDE_SELECTOR)});
+    var direct = [];
+    for (var i = 0; i < nested.length; i++) {
+      if (nested[i].parentElement === stage) direct.push(nested[i]);
+    }
+    return direct.length ? direct : nested;
+  }
+  function legacyScreenSlides(){
+    var candidates = document.querySelectorAll(${JSON.stringify(DECK_LEGACY_SCREEN_SLIDE_SELECTOR)});
+    var labelRe = new RegExp(${JSON.stringify(DECK_LEGACY_SCREEN_LABEL_RE_SOURCE)}, 'i');
+    var groups = [];
+    for (var i = 0; i < candidates.length; i++) {
+      var match = labelRe.exec(candidates[i].getAttribute('data-screen-label') || '');
+      if (!match || !candidates[i].parentNode) continue;
+      var group = null;
+      for (var j = 0; j < groups.length; j++) {
+        if (groups[j].parent === candidates[i].parentNode) { group = groups[j]; break; }
+      }
+      if (!group) {
+        group = { parent: candidates[i].parentNode, slides: [], numbers: {} };
+        groups.push(group);
+      }
+      group.slides.push(candidates[i]);
+      group.numbers[String(Number(match[1]))] = true;
+    }
+    var best = [];
+    for (var k = 0; k < groups.length; k++) {
+      if (Object.keys(groups[k].numbers).length > 1 && groups[k].slides.length > best.length) {
+        best = groups[k].slides;
+      }
+    }
+    return best;
+  }
   function slides(){
-    // Structured selectors first so decorative .slide markup in non-deck
-    // pages (icons, badges, code samples) is not counted as deck slides;
-    // fall back to all .slide only when nothing structured matched, so
-    // freeform decks that nest slides under an extra wrapper still report
-    // the real count instead of leaving the host counter at 1 / 0.
-    var structured = document.querySelectorAll('deck-stage > .slide, .deck > .slide, .deck-stage > .slide, .deck-shell > .slide, body > .slide');
+    // An explicit deck-stage owns its descendants, so unrelated annotated
+    // screens elsewhere in the document cannot leak into its count. Otherwise
+    // prefer direct children of recognized legacy containers before falling
+    // back to every supported persisted slide marker.
+    var stageSlides = deckStageSlides(document.querySelector('deck-stage'));
+    if (stageSlides.length) return stageSlides;
+    var structured = document.querySelectorAll(${JSON.stringify(DECK_STRUCTURED_SLIDE_SELECTOR)});
     if (structured.length) return structured;
-    return document.querySelectorAll('.slide');
+    var explicit = document.querySelectorAll(${JSON.stringify(DECK_EXPLICIT_SLIDE_SELECTOR)});
+    if (explicit.length) return explicit;
+    return legacyScreenSlides();
+  }
+  function deckStageForSlides(list){
+    var stage = document.querySelector('deck-stage');
+    if (!stage) return null;
+    if (list && list.length && !stage.contains(list[0])) return null;
+    return stage;
+  }
+  function activeIndexFromDeckStage(list){
+    var stage = deckStageForSlides(list);
+    if (!stage) return -1;
+    var index = Number(stage.index);
+    if (!Number.isFinite(index)) return -1;
+    index = Math.floor(index);
+    return index >= 0 && index < list.length ? index : -1;
+  }
+  function navigateViaDeckStage(list, action, index){
+    if (!list.length) return false;
+    var stage = deckStageForSlides(list);
+    if (!stage) return false;
+    try {
+      if (action === 'go' && typeof index === 'number' && typeof stage.goTo === 'function') {
+        stage.goTo(index);
+      } else if (action === 'next' && typeof stage.next === 'function') {
+        stage.next();
+      } else if (action === 'prev' && typeof stage.prev === 'function') {
+        stage.prev();
+      } else if (action === 'first' && typeof stage.reset === 'function') {
+        stage.reset();
+      } else if (action === 'first' && typeof stage.goTo === 'function') {
+        stage.goTo(0);
+      } else if (action === 'last' && typeof stage.goTo === 'function') {
+        stage.goTo(list.length - 1);
+      } else {
+        return false;
+      }
+      // Public deck-stage methods are synchronous in the authored runtime.
+      // Report here for older implementations that do not emit slidechange;
+      // modern implementations also emit the event and are harmlessly
+      // coalesced by React state equality in the host.
+      report();
+      return true;
+    } catch (_) {
+      return false;
+    }
   }
   function scrollOverflow(el){
     if (!el) return 0;
@@ -2989,6 +3078,8 @@ function injectDeckBridge(
       var w = Math.max(1, window.innerWidth);
       return Math.max(0, Math.min(list.length - 1, Math.round(maxScrollLeft() / w)));
     }
+    var byDeckStage = activeIndexFromDeckStage(list);
+    if (byDeckStage >= 0) return byDeckStage;
     var byTransform = activeIndexFromTransform(list);
     if (byTransform >= 0) return byTransform;
     var byClass = findActiveByClass(list);
@@ -3287,6 +3378,7 @@ function injectDeckBridge(
   function go(action){
     var list = slides();
     if (!list.length) return;
+    if (navigateViaDeckStage(list, action)) return;
     if (isScrollDeck()) {
       scrollGo(Math.max(0, Math.min(list.length - 1, targetFor(action, list))));
       return;
@@ -3307,6 +3399,7 @@ function injectDeckBridge(
     var list = slides();
     if (!list.length) return;
     var target = Math.max(0, Math.min(list.length - 1, i));
+    if (navigateViaDeckStage(list, 'go', target)) return;
     if (isScrollDeck()) { scrollGo(target); return; }
     if (activeIndex(list) === target) { report(); return; }
     stepToIndexViaKeys(target, function(stepped){
@@ -3390,6 +3483,17 @@ function injectDeckBridge(
       }
     } catch (e) {}
   }
+  // Runtime-managed decks can also move themselves through their own tap
+  // zones, keyboard handler, or public API. Normalize both generations of
+  // deck-stage state notification back into the host-owned slide protocol.
+  document.addEventListener('slidechange', function(ev){
+    var stage = document.querySelector('deck-stage');
+    if (stage && ev.target === stage) report();
+  });
+  window.addEventListener('message', function(ev){
+    var data = ev && ev.data;
+    if (data && typeof data.slideIndexChanged === 'number') report();
+  });
   window.__odDeckSlideState = function(){
     var list = slides();
     return { active: activeIndex(list), count: list.length };

apps/web/tests/components/FileViewer.test.tsx

@@ -6003,6 +6003,12 @@ describe('FileViewer SVG artifacts', () => {
       'slides.html',
       '<section class="slide">A</section><section class="slide">B</section>',
     ).deck).toBe(true);
+
+    expect(fileVersionPreviewOptions(
+      'project-1',
+      'prototype.html',
+      '<main><h1 data-screen-label="Hero title">Prototype</h1></main>',
+    ).deck).toBe(false);
   });
 
   it('routes history deck arrow keys to the preview unless a text input is focused', async () => {