@flamingo-stack/openframe-frontend-core 0.0.848 → 0.0.849

package/src/components/docs/doc-viewer.tsx

@@ -4,15 +4,15 @@ import type React from 'react';
 import { useMemo } from 'react';
 import { useRouter } from '../../embed-shims/next-navigation';
 import type { DocContent, DocNode, DocRenderHandlers, DocSourceId } from '../../types/doc-source';
-import { findDocNodeByPath } from '../../utils/doc-tree-nav';
+import { findDocNodeByPath, rootDocumentPath } from '../../utils/doc-tree-nav';
 import { PageShell } from '../layout/article-detail-layout';
 import { PageLayout } from '../layout/page-layout';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { MultiLevelNavigation, MobileNavigationDropdown } from '../navigation/multi-level-navigation';
 import { StickySectionNav } from '../navigation/sticky-section-nav';
 import { PersistentSidebar, PersistentMobileDropdown } from '../persistent-filter-controls';
 import { DocSearchBar, useDocSearch } from '../shared/doc-search';
 import { DataSyncLine } from '../ui/data-attribution';
+import { LoadingScope } from '../ui/loading-scope';
 import { useDocNavigation } from './doc-navigation-context';
 import { useDocsResolveLink } from './use-docs-resolve-link';
 import { useDocumentTree } from './use-document-tree';
@@ -46,13 +46,6 @@ export interface DocViewerProps {
    */
   renderContent: (content: DocContent, handlers: DocRenderHandlers) => React.ReactNode;
 
-  /**
-   * Render the loading skeleton. Receives the selected node's `documentType`
-   * (undefined while structure is still loading) so the caller can return a
-   * markdown-shaped skeleton vs an embed-shaped skeleton.
-   */
-  renderSkeleton: (documentType: DocNode['documentType']) => React.ReactNode;
-
   /**
    * Chat-source identifier — passed in by the page shell from server-side
    * `currentPlatform()`. Lib has no platform context; the page shell is the
@@ -88,6 +81,13 @@ export interface DocViewerProps {
   /** Initial doc path (URL `[...path]`). */
   docPath?: string;
 
+  /**
+   * The type of the document at `docPath`, when the page knows it before the tree is read (the host read it on the
+   * server). The content's loading state takes its shape from it on a page's first load (a Figma deck draws the embed
+   * skeleton, not a text page); once the tree is read, the selected node's own type decides.
+   */
+  initialDocumentType?: DocNode['documentType'];
+
   /** Sidebar header copy (`'DOCUMENTATION'`, `'DATA ROOM'`). */
   sidebarLabel?: string;
 
@@ -113,7 +113,7 @@ export interface DocViewerProps {
   /** Base route path for URL navigation. */
   baseRoute: string;
 
-  /** Empty state copy when no doc is selected. */
+  /** What the viewer says when the source holds no documents yet (default "No documents yet."). */
   emptyStateText?: string;
 
   /** Whether to render the doc-search bar (bound to chat). */
@@ -141,12 +141,13 @@ export function DocViewer(props: DocViewerProps) {
 
 /** The "On this page" column's heading: static copy, drawn for real loaded and loading. */
 const ON_THIS_PAGE_LABEL = 'ON THIS PAGE';
+/** The loading section list's click handler: it has no sections to click. */
+const NO_SECTION_CLICK = () => {};
 const ON_THIS_PAGE_HEADING_CLASS = 'mb-4 font-semibold text-ods-text-secondary text-h5';
 
 function DocViewerContent({
   sourceId,
   renderContent,
-  renderSkeleton,
   chatSource,
   title,
   subtitle,
@@ -154,6 +155,7 @@ function DocViewerContent({
   className = '',
   shell = true,
   docPath,
+  initialDocumentType,
   sidebarLabel = 'DOCUMENTATION',
   structureEndpoint,
   contentEndpoint,
@@ -246,11 +248,31 @@ function DocViewerContent({
   //   - the article max-width + sticky-nav visibility (markdown only)
   // `undefined` documentType is treated as `'markdown'` (per the DocNode
   // discriminator's documented default).
+  // Before the tree is read, the host's `initialDocumentType` (the page's own document) stands in. Once it is read, the
+  // root takes the type of the document it shows (`rootDocumentPath`), so a root Figma or PDF never flips to the text
+  // layout between the tree arriving and the document arriving.
+  const selectedNodePath =
+    structure.length > 0 && !selectedPath ? rootDocumentPath(structure, folderIndexFile) : selectedPath;
   const selectedNodeDocType =
-    selectedPath && structure.length > 0 ? findDocNodeByPath(selectedPath, structure)?.documentType : undefined;
-  // During loading, the in-flight content's type isn't known yet — fall back
-  // to the selected node's type (or markdown if neither is set).
-  const activeDocType = content?.documentType ?? selectedNodeDocType;
+    structure.length > 0
+      ? selectedNodePath
+        ? findDocNodeByPath(selectedNodePath, structure)?.documentType
+        : undefined
+      : initialDocumentType;
+  // While a document loads, `content` is still the PREVIOUS document's: the layout (the "On this page" column, the
+  // article width) follows the document being opened, never the one being left, or opening a Figma deck from a text
+  // page draws the text page's column beside the deck's skeleton. Loaded, the content's own type decides.
+  const isLoadingDocument = isLoadingContent || isLoadingStructure;
+  // While a document loads: its renderer with an EMPTY document of its type (the selected node's, or the host's
+  // `initialDocumentType` before the tree is read), drawn in a loading scope, so every renderer shows its own loading
+  // form.
+  const loadingContent = isLoadingDocument
+    ? renderContent(
+        { content: '', sections: [], path: selectedPath ?? '', documentType: selectedNodeDocType },
+        { onInternalLinkClick: navigateToDoc, currentPath: selectedPath ?? '', sourceId },
+      )
+    : null;
+  const activeDocType = isLoadingDocument ? selectedNodeDocType : (content?.documentType ?? selectedNodeDocType);
   const isMarkdownContent = !activeDocType || activeDocType === 'markdown';
   const showStickyNav = isMarkdownContent;
 
@@ -266,11 +288,10 @@ function DocViewerContent({
   const containerBgStyle =
     colorPalette.containerBackground !== 'transparent' ? { backgroundColor: colorPalette.containerBackground } : {};
 
-  const defaultEmptyText =
-    structure.length > 0
-      ? 'Select a document from the sidebar to view'
-      : 'No documents yet. Add content from the admin panel.';
-  const resolvedEmptyText = emptyStateText || defaultEmptyText;
+  // A source with documents and none open asks for one; an empty source says so in the host's words (a reader may
+  // not be the one who adds documents, so the default names no admin screen).
+  const resolvedEmptyText =
+    structure.length > 0 ? 'Select a document from the sidebar to view' : emptyStateText || 'No documents yet.';
 
   // Unified header: title/subtitle route through the canonical (frozen)
   // `PageLayout` `TitleBlock` (text-h2) — same as every other help-center page —
@@ -365,8 +386,10 @@ function DocViewerContent({
                       (app-globals.css) so content wraps instead of overflowing. */}
                   <div className={`w-full min-w-0 ${isMarkdownContent ? 'mx-auto max-w-4xl' : ''}`}>
                     <article className="space-y-2">
-                      {isLoadingContent || isLoadingStructure ? (
-                        renderSkeleton(selectedNodeDocType)
+                      {isLoadingDocument ? (
+                        // The document being opened draws its own loading form: its renderer, in a loading scope,
+                        // with an empty document of its type (no words, no address), never a skeleton picked here.
+                        <LoadingScope>{loadingContent}</LoadingScope>
                       ) : !content ? (
                         <div className="py-16 text-center">
                           <p className="text-ods-text-secondary text-h4">{resolvedEmptyText}</p>
@@ -377,22 +400,20 @@ function DocViewerContent({
                     </article>
                   </div>
 
-                  {isMarkdownContent && (isLoadingContent || isLoadingStructure) && (
+                  {isMarkdownContent && isLoadingDocument && (
                     <div className="hidden content-lg:block">
                       <div className="sticky top-24">
                         <h3 className={ON_THIS_PAGE_HEADING_CLASS}>{ON_THIS_PAGE_LABEL}</h3>
-                        <div className="space-y-0">
-                          {[130, 170, 190, 220, 110, 200, 80, 100, 120, 140, 90].map((w, i) => (
-                            <div
-                              key={i}
-                              className={`border-l-2 py-[13px] pl-3 ${
-                                i === 0 ? 'border-ods-accent' : 'border-transparent'
-                              }`}
-                            >
-                              <UnifiedSkeleton className="h-[13px] rounded" width={w} />
-                            </div>
-                          ))}
-                        </div>
+                        {/* The section list's own loading form (`StickySectionNav` with no sections, in a scope). */}
+                        <LoadingScope>
+                          <StickySectionNav
+                            sections={[]}
+                            activeSection=""
+                            onSectionClick={NO_SECTION_CLICK}
+                            ribbonPosition="left"
+                            ribbonColor="var(--ods-accent)"
+                          />
+                        </LoadingScope>
                       </div>
                     </div>
                   )}

package/src/components/docs/docs-hub-page.tsx

@@ -5,7 +5,6 @@ import { FileDownloadCard } from '../embeds/file-download-card';
 import { GoogleSheetsViewer } from '../embeds/google-sheets-viewer';
 import { PdfViewer } from '../embeds/pdf-viewer';
 import { DocViewer, type DocViewerProps } from './doc-viewer';
-import { MarkdownSkeleton, EmbedSkeleton } from './skeletons';
 
 type DocRenderer = (content: DocContent, handlers: DocRenderHandlers) => React.ReactNode;
 
@@ -20,7 +19,7 @@ type DocRenderer = (content: DocContent, handlers: DocRenderHandlers) => React.R
  */
 export type DocumentTypeRenderers = { markdown: DocRenderer } & Partial<Record<DocumentType, DocRenderer>>;
 
-export interface DocsHubPageProps extends Omit<DocViewerProps, 'renderContent' | 'renderSkeleton' | 'showAIChat'> {
+export interface DocsHubPageProps extends Omit<DocViewerProps, 'renderContent' | 'showAIChat'> {
   /** Per-document-type renderer map. `markdown` is REQUIRED. */
   documentTypeRenderers: DocumentTypeRenderers;
 
@@ -42,32 +41,20 @@ const defaultFallbackRenderer: DocRenderer = () => (
   </div>
 );
 
-// When the DAL hasn't populated the URL field for a rich-content type, the
-// embed-viewer components render a broken iframe (empty src). Fall back to
-// the same lib-styled "Unsupported document type" panel the explicit
-// fallback uses — the surface is honest about the missing data instead of
-// pretending to load. `FileDownloadCard` handles its own missing-URL state
-// (hides the Download button), so it doesn't need this guard.
-const defaultPdfRenderer: DocRenderer = (content, handlers) =>
-  content.fileUrl ? (
-    <PdfViewer src={content.fileUrl} fileName={content.fileName} />
-  ) : (
-    defaultFallbackRenderer(content, handlers)
-  );
+// Each viewer owns both its states without a document: in a loading scope (the document is being read) it draws its
+// own loading form, otherwise its "not available" state when the DAL left the URL empty. So the renderers always
+// render the viewer, and the viewer never mounts a frame without a source.
+const defaultPdfRenderer: DocRenderer = content => (
+  <PdfViewer src={content.fileUrl ?? ''} fileName={content.fileName} />
+);
 
-const defaultGoogleSheetRenderer: DocRenderer = (content, handlers) =>
-  content.externalUrl ? (
-    <GoogleSheetsViewer externalUrl={content.externalUrl} fileName={content.fileName} />
-  ) : (
-    defaultFallbackRenderer(content, handlers)
-  );
+const defaultGoogleSheetRenderer: DocRenderer = content => (
+  <GoogleSheetsViewer externalUrl={content.externalUrl ?? ''} fileName={content.fileName} />
+);
 
-const defaultFigmaRenderer: DocRenderer = (content, handlers) =>
-  content.externalUrl ? (
-    <FigmaEmbed url={content.externalUrl} title={content.fileName} loading="eager" />
-  ) : (
-    defaultFallbackRenderer(content, handlers)
-  );
+const defaultFigmaRenderer: DocRenderer = content => (
+  <FigmaEmbed url={content.externalUrl ?? ''} title={content.fileName} iframeLoading="eager" />
+);
 
 const defaultFileRenderer: DocRenderer = content => (
   <FileDownloadCard
@@ -78,16 +65,6 @@ const defaultFileRenderer: DocRenderer = content => (
   />
 );
 
-/** The page's own loading form per document type: the markdown article's, else the embed viewer's. */
-const documentLoadingForm = (documentType: DocumentType | undefined) =>
-  !documentType || documentType === 'markdown' ? (
-    <MarkdownSkeleton />
-  ) : (
-    // Forward the documentType so the embed skeleton renders the right
-    // shape (PDF=2 buttons, sheets/figma=1 button, file=centered card).
-    <EmbedSkeleton documentType={documentType} />
-  );
-
 /**
  * Embeddable docs-hub page. Bundles `<DocViewer>` with safe defaults so the
  * minimum embed is a one-line mount (consumer only has to supply
@@ -132,7 +109,6 @@ export function DocsHubPage({
       className={className}
       sidebarLabel={sidebarLabel}
       renderContent={renderContent}
-      renderSkeleton={documentLoadingForm}
     />
   );
 }

package/src/components/docs/use-document-tree.ts

@@ -9,6 +9,8 @@ import {
   findDocNodeByPath,
   getDocAncestorNodeIds,
   DEFAULT_FOLDER_INDEX_FILE,
+  findFirstDocPath,
+  rootDocumentPath,
 } from '../../utils/doc-tree-nav';
 import { contentFetch } from '../../utils/embed-content-fetch';
 import { navigateSamePageHash, HUB_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
@@ -34,21 +36,6 @@ function scrollToContent() {
  * its README) instead of a blank panel or a redundant in-page listing — the
  * sidebar tree is the directory browser. Returns null for a folder with no docs.
  */
-function findFirstDocPath(folder: DocNode): string | null {
-  const children = folder.children ?? [];
-  for (const child of children) {
-    if (child.type === 'file' && !child.path.toLowerCase().endsWith('.mmd')) {
-      return child.path;
-    }
-  }
-  for (const child of children) {
-    if (child.type === 'folder') {
-      const nested = findFirstDocPath(child);
-      if (nested) return nested;
-    }
-  }
-  return null;
-}
 
 // ---------------------------------------------------------------------------
 // Wire decoding for the two doc-source endpoints
@@ -220,6 +207,11 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
   const cleanInitialPath = stripFolderIndexFromPath(initialPath?.replace(/\/$/, '') || '', folderIndexFile);
 
   const [structure, setStructure] = useState<DocNode[]>([]);
+  // The latest committed tree, for a request that settles after the tree arrived (its closure holds the old one).
+  const structureRef = useRef(structure);
+  useEffect(() => {
+    structureRef.current = structure;
+  }, [structure]);
   const [selectedPath, setSelectedPath] = useState<string>(cleanInitialPath);
   const [content, setContent] = useState<DocContent | null>(null);
   const [isLoadingStructure, setIsLoadingStructure] = useState(true);
@@ -409,12 +401,16 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
           // No-README FOLDER → stay silent: the content effect resolves it to
           // the folder's first child, so the folder-path 404 from the direct-
           // load speculative fetch is expected, not an error to flash.
-          const probe = findDocNodeByPath(stripFolderIndexFromPath(path, folderIndexFile), structure);
+          // Classified against the LATEST tree (`structureRef`), never the one captured when this request went out: the tree
+          // often arrives while the request is in flight, and judged against the empty tree of the call a missing
+          // document read as "not classified yet, wait", so nothing settled it and the page stayed a skeleton.
+          const latestStructure = structureRef.current;
+          const probe = findDocNodeByPath(stripFolderIndexFromPath(path, folderIndexFile), latestStructure);
           const probeIsNoReadmeFolder = !!probe && probe.type === 'folder' && !probe.hasReadme;
           // Before the structure has loaded to classify the path (`structure`
           // is [] in the speculative call's closure), only silence FOLDER-LIKE
           // paths (no `.md`) — a genuinely missing `*.md` leaf must still error.
-          const preStructureFolderLike = structure.length === 0 && !path.endsWith('.md');
+          const preStructureFolderLike = latestStructure.length === 0 && !path.endsWith('.md');
           if (probeIsNoReadmeFolder || preStructureFolderLike) {
             // Superseded by the targeted fetch (first-child / reclassified path)
             // the structure effect fires. Null the request id so the `finally`
@@ -507,7 +503,15 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
     let pathToFetch: string | null = null;
 
     if (selectedPath === '') {
-      pathToFetch = folderIndexFile;
+      // The root shows its landing document (the folder index); a source with none shows its FIRST document, the
+      // rule a no-README folder follows. Asking for the missing index again would 404 for ever.
+      const rootPath = rootDocumentPath(structure, folderIndexFile);
+      if (!rootPath) {
+        // A tree with folders and no document at all: nothing to fetch; the empty state is derived below.
+        lastFetchedPath.current = null;
+        return;
+      }
+      pathToFetch = rootPath;
     } else {
       const node = findDocNodeByPath(selectedPath, structure);
 
@@ -731,19 +735,25 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
   // the content effect, which reached the same conclusion one commit later and
   // meanwhile left the PREVIOUS document's body on screen.
   const isEmptyFolder = useMemo(() => {
-    if (!selectedPath || structure.length === 0) return false;
+    if (structure.length === 0) return false;
+    // The root of a source whose tree holds no document at all is an empty folder too.
+    if (!selectedPath) return !rootDocumentPath(structure, folderIndexFile);
     const node = findDocNodeByPath(selectedPath, structure);
     return !!node && node.type === 'folder' && !node.hasReadme && !findFirstDocPath(node);
-  }, [selectedPath, structure]);
+  }, [selectedPath, structure, folderIndexFile]);
+  // A source with no documents at all (its tree is read and empty): there is nothing to load, so the viewer shows the
+  // source's empty state instead of waiting for a landing document that does not exist.
+  const isEmptySource = !isLoadingStructure && structure.length === 0;
+  const settled = isEmptyFolder || isEmptySource;
 
   return {
     structure,
     selectedPath,
     setSelectedPath,
-    content: isEmptyFolder ? null : content,
+    content: settled ? null : content,
     isLoadingStructure,
-    isLoadingContent: isEmptyFolder ? false : isLoadingContent,
-    error: isEmptyFolder ? null : error,
+    isLoadingContent: settled ? false : isLoadingContent,
+    error: settled ? null : error,
     expandedNodes,
     toggleNode,
     selectNode,

package/src/components/embeds/claude-embed.tsx

@@ -19,7 +19,7 @@ export interface ClaudeEmbedProps {
   /** iframe height (CSS value), matching `FigmaEmbed`'s prop. */
   height?: string;
   /** iframe loading strategy. Defaults to `lazy`, as `FigmaEmbed` does. */
-  loading?: 'eager' | 'lazy';
+  iframeLoading?: 'eager' | 'lazy';
 }
 
 const KIND_HEADING: Record<ClaudeEmbedKind, string> = {
@@ -51,7 +51,7 @@ const KIND_HEADING: Record<ClaudeEmbedKind, string> = {
  * a Claude Design url (no embed route), an artifact whose author has not
  * allow-listed this host, or an http host (mixed content).
  */
-export function ClaudeEmbed({ url, kind = 'artifact', title, height, loading = 'lazy' }: ClaudeEmbedProps) {
+export function ClaudeEmbed({ url, kind = 'artifact', title, height, iframeLoading = 'lazy' }: ClaudeEmbedProps) {
   // Mirror detection lives in `useClaudeMirrorSrc` (derive from
   // EndpointsRuntime + 1-byte ranged probe + background revalidation) — this
   // component stays presentational.
@@ -70,7 +70,7 @@ export function ClaudeEmbed({ url, kind = 'artifact', title, height, loading = '
       icon={<ClaudeIcon className="h-5 w-5 shrink-0" />}
       title={title?.trim() || KIND_HEADING[kind]}
       titleVariant="h6"
-      isLoading={isProbing}
+      resolving={isProbing}
       actions={
         <Button
           variant="outline"
@@ -89,7 +89,7 @@ export function ClaudeEmbed({ url, kind = 'artifact', title, height, loading = '
       // (unlike Figma's player) — the shell provides the toggle for both
       // the claude.ai `/embed` route and a mirror.
       fullscreenControl
-      loading={loading}
+      iframeLoading={iframeLoading}
       height={height}
       // Same frame contract Figma gets — an artifact is a real app: it copies
       // to the clipboard and can go fullscreen.

package/src/components/embeds/embed-iframe.tsx

@@ -43,8 +43,10 @@ export interface EmbedIframeProps {
   allow?: string;
   /** iframe `referrerPolicy` attribute */
   referrerPolicy?: React.IframeHTMLAttributes<HTMLIFrameElement>['referrerPolicy'];
-  /** iframe `loading` attribute */
-  loading?: 'eager' | 'lazy';
+  /** iframe `loading` attribute (eager or lazy). */
+  iframeLoading?: 'eager' | 'lazy';
+  /** The frame's source is not known yet: the frame draws its loading form. A loading scope does the same. */
+  loading?: boolean;
   /** iframe `allowFullScreen` attribute */
   allowFullScreen?: boolean;
   /**
@@ -74,7 +76,8 @@ export function EmbedIframe({
   height,
   allow,
   referrerPolicy,
-  loading,
+  iframeLoading,
+  loading = false,
   allowFullScreen,
   sandbox,
 }: EmbedIframeProps) {
@@ -87,7 +90,7 @@ export function EmbedIframe({
   const isLoaded = loadedSrc === src;
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const handleLoad = useCallback(() => setLoadedSrc(src), [src]);
-  const held = useLoadingScope();
+  const held = useLoadingScope() || loading;
 
   useEffect(() => {
     const iframe = iframeRef.current;
@@ -123,7 +126,7 @@ export function EmbedIframe({
           onLoad={handleLoad}
           allow={allow}
           referrerPolicy={referrerPolicy}
-          loading={loading}
+          loading={iframeLoading}
           allowFullScreen={allow?.includes('fullscreen') ? undefined : allowFullScreen}
           sandbox={sandbox}
         />

package/src/components/embeds/embed-viewer-frame.tsx

@@ -5,6 +5,7 @@ import type React from 'react';
 import { useEffect, useRef, useState } from 'react';
 import { cn } from '../../utils/cn';
 import { FullscreenSwitchController } from '../../utils/fullscreen-switch';
+import { InteractiveSkeleton, TextLineSkeleton } from '../loading/unified-skeleton';
 import { Button } from '../ui/button/button';
 import { useLoadingScope } from '../ui/loading-scope';
 import { EmbedIframe, EmbedLoadingSkeleton } from './embed-iframe';
@@ -40,21 +41,22 @@ export interface EmbedViewerFrameProps {
   /** Rendered verbatim in the header row — the caller owns its own container/state. */
   actions?: React.ReactNode;
   /** Iframe source; falsy renders the inline empty state (or the loading
-   *  state when `isLoading`) under the header. */
+   *  state when `loading` or `resolving`) under the header. */
   src: string | null | undefined;
-  /** While true AND there is no `src` yet, the body shows the shared embed
-   *  loading skeleton (`EmbedLoadingSkeleton`) instead of the empty state —
-   *  for a viewer that is still resolving where its frame points (e.g.
-   *  ClaudeEmbed probing for a self-hosted mirror), so a cold first view
-   *  reads as "loading" (identical to every other embed), not "nothing here". */
-  isLoading?: boolean;
+  /** The document is being read (the standard `loading` prop; a loading scope does the same): the whole frame is its
+   *  loading form, a skeleton title, its buttons' loading forms and the frame's loading box. */
+  loading?: boolean;
+  /** The document is known (its title shows) but the viewer is still finding where its frame points (ClaudeEmbed
+   *  probing for a self-hosted mirror): only the body is its loading box. */
+  resolving?: boolean;
   /** Large icon for the inline empty state (the viewers pass `w-16 h-16`). */
   emptyIcon?: React.ReactNode;
   emptyMessage?: string;
   height?: string;
   allow?: string;
   allowFullScreen?: boolean;
-  loading?: 'eager' | 'lazy';
+  /** iframe loading strategy (eager or lazy). */
+  iframeLoading?: 'eager' | 'lazy';
   /** iframe `sandbox` — see `EmbedIframe`. Set it for user-authored contents. */
   sandbox?: string;
   /** Wrapper classes; defaults to the sheets/pdf `space-y-4`. */
@@ -66,6 +68,8 @@ export interface EmbedViewerFrameProps {
    *  button (the Figma player) and some cannot (a self-hosted Claude
    *  artifact mirror) — the shell provides the affordance uniformly. */
   fullscreenControl?: boolean;
+  /** How many buttons `actions` draws (PDF: Preview and Download): the header's loading form draws as many. Default 1. */
+  loadingActionCount?: number;
 }
 
 export function EmbedViewerFrame({
@@ -74,19 +78,23 @@ export function EmbedViewerFrame({
   titleVariant = 'h3',
   actions,
   src,
-  isLoading: isLoadingGiven,
+  loading: loadingGiven = false,
+  resolving = false,
   emptyIcon,
   emptyMessage = 'Content not available',
   height,
   allow,
   allowFullScreen,
-  loading,
+  iframeLoading,
   sandbox,
   className,
   fullscreenControl,
+  loadingActionCount = 1,
 }: EmbedViewerFrameProps) {
-  // ONE switch: a page's loading scope, or the viewer still resolving where its frame points.
-  const isLoading = useLoadingScope() || !!isLoadingGiven;
+  // ONE switch for the whole frame (header included): a page's loading scope, or the standard `loading` prop. The body
+  // alone also waits while the viewer resolves where its frame points.
+  const loadingForm = useLoadingScope() || loadingGiven;
+  const isLoading = loadingForm || resolving;
   const frameRef = useRef<HTMLDivElement>(null);
   const [isFullscreen, setIsFullscreen] = useState(false);
 
@@ -127,7 +135,11 @@ export function EmbedViewerFrame({
       <div className="flex flex-col gap-3 content-sm:flex-row content-sm:items-center content-sm:justify-between">
         <div className="flex min-w-0 items-center gap-2">
           {icon}
-          {titleVariant === 'h3' ? (
+          {loadingForm ? (
+            // The document is being read: its name is not known yet. (A viewer still resolving its frame, with a
+            // known title, keeps it.)
+            <TextLineSkeleton type={titleVariant} className="w-48 max-w-full" />
+          ) : titleVariant === 'h3' ? (
             <h2 className="truncate text-ods-text-primary text-h3">{title}</h2>
           ) : (
             <span className="truncate font-semibold text-ods-text-primary text-h6">{title}</span>
@@ -140,7 +152,15 @@ export function EmbedViewerFrame({
             fullscreen toggle, `actions` renders EXACTLY as before — the
             wrapper exists only when the toggle joins it, so pre-existing
             viewers (figma/pdf/sheets) are byte-identical. */}
-        {fullscreenControl && src ? (
+        {loadingForm ? (
+          // The actions point at the document being read: each its button's loading form, in the actions' row.
+          <div className="flex w-full items-center gap-2 content-sm:w-auto">
+            {Array.from({ length: loadingActionCount }, (_, i) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: loading buttons never reorder
+              <InteractiveSkeleton.Button key={i} size="small-legacy" className="flex-1 content-sm:flex-initial" />
+            ))}
+          </div>
+        ) : fullscreenControl && src ? (
           <div className="flex flex-col gap-[var(--spacing-system-xsf)] content-sm:flex-row content-sm:items-center">
             {actions}
             <Button
@@ -169,7 +189,7 @@ export function EmbedViewerFrame({
           height={isFullscreen ? 'calc(100vh - 96px)' : height}
           allow={allow}
           allowFullScreen={allowFullScreen}
-          loading={loading}
+          iframeLoading={iframeLoading}
           sandbox={sandbox}
         />
       ) : isLoading ? (

package/src/components/embeds/figma-embed.tsx

@@ -19,7 +19,9 @@ export interface FigmaEmbedProps {
    */
   height?: string;
   /** iframe loading strategy. Defaults to `"lazy"`; the data-room viewer passes `"eager"`. */
-  loading?: 'eager' | 'lazy';
+  iframeLoading?: 'eager' | 'lazy';
+  /** The document is being read: the embed draws its loading form. A loading scope does the same. */
+  loading?: boolean;
 }
 
 type SlidesView = 'present' | 'browse';
@@ -42,7 +44,9 @@ function SlidesViewToggle({ view, onChange }: { view: SlidesView; onChange: (v:
         if (v && v !== view) onChange(v as SlidesView);
       }}
       aria-label="Figma slides view mode"
-      className="flex shrink-0 items-center gap-0.5 rounded-lg border border-ods-border bg-ods-card p-0.5"
+      // The whole control is one button tall (40px, border and padding included), so the header row is the same height
+      // with or without it, loading and loaded alike.
+      className="flex h-10 shrink-0 items-center gap-0.5 rounded-lg border border-ods-border bg-ods-card p-0.5"
     >
       {options.map(({ key, label, Icon }) => {
         const active = view === key;
@@ -51,7 +55,7 @@ function SlidesViewToggle({ view, onChange }: { view: SlidesView; onChange: (v:
             key={key}
             value={key}
             aria-label={label}
-            className={`flex items-center gap-1.5 rounded-md px-2.5 py-1 transition-colors text-h6 ${
+            className={`flex h-full items-center gap-1.5 rounded-md px-2.5 py-1 transition-colors text-h6 ${
               active
                 ? 'bg-ods-accent text-ods-text-on-accent'
                 : 'text-ods-text-secondary hover:bg-ods-bg-hover hover:text-ods-text-primary'
@@ -80,7 +84,7 @@ function SlidesViewToggle({ view, onChange }: { view: SlidesView; onChange: (v:
  * plain ReactNode) — flipping it recomputes `embedSrc`, and the frame's
  * `EmbedIframe` remounts on the new src exactly as before the extraction.
  */
-export function FigmaEmbed({ url, title, height, loading = 'lazy' }: FigmaEmbedProps) {
+export function FigmaEmbed({ url, title, height, iframeLoading = 'lazy', loading = false }: FigmaEmbedProps) {
   const [view, setView] = useState<SlidesView>('present');
   const isSlides = url ? isFigmaSlidesUrl(url) : false;
   const embedSrc = url ? toFigmaEmbedUrl(url, { slidesView: view }) : null;
@@ -124,6 +128,7 @@ export function FigmaEmbed({ url, title, height, loading = 'lazy' }: FigmaEmbedP
       }
       src={embedSrc}
       allow="clipboard-write; clipboard-read; fullscreen"
+      iframeLoading={iframeLoading}
       loading={loading}
       height={height}
       allowFullScreen