@flamingo-stack/openframe-frontend-core 0.0.764 → 0.0.766

package/src/components/comment-thread.tsx

@@ -2,9 +2,24 @@
 
 import { ChevronDown } from 'lucide-react';
 import { type ReactNode, useState } from 'react';
-import { CommentCard, type CommentCardComment } from './comment-card';
+import { CommentCard, CommentCardSkeleton, type CommentCardComment } from './comment-card';
 import { CommentComposer } from './comment-composer';
+import { TextLineSkeleton } from './loading/unified-skeleton';
 import { Button } from './ui/button';
+import { useLoadingScope } from './ui/loading-scope';
+
+/**
+ * The comment cards a thread's skeleton draws: its first fold (about three root cards fill a section's screen). Never
+ * the number of comments held: in a loading scope those are not read.
+ */
+export const COMMENT_THREAD_SKELETON_COUNT = 3;
+// The thread's and the block's boxes, read by them AND their skeletons.
+const COMMENT_THREAD_LIST = 'flex flex-col gap-[var(--spacing-system-sf)]';
+/** A root's actions at the end of its footer (Reply, then the surface's own), loaded and loading. */
+const COMMENT_THREAD_ACTIONS = 'ml-auto flex flex-wrap gap-[var(--spacing-system-xsf)]';
+const COMMENTS_BLOCK = 'space-y-[var(--spacing-system-sf)]';
+const COMMENTS_BLOCK_HEADER = 'px-0 text-ods-text-secondary hover:text-ods-text-primary';
+const commentsBlockChevron = (open: boolean) => `h-4 w-4 transition-transform ${open ? 'rotate-180' : ''}`;
 
 /** A root comment with its replies. Replies never nest further (single-level threads). */
 export interface ThreadComment extends CommentCardComment {
@@ -55,11 +70,14 @@ export function CommentThread({
   leadWith,
   onViewProduct,
 }: CommentThreadProps) {
+  if (useLoadingScope()) {
+    return <CommentThreadSkeleton count={COMMENT_THREAD_SKELETON_COUNT} leadWith={leadWith} reply={Boolean(onReply)} />;
+  }
   if (comments.length === 0) {
     return emptyLabel ? <p className="text-ods-text-secondary text-h6">{emptyLabel}</p> : null;
   }
   return (
-    <div className="flex flex-col gap-[var(--spacing-system-sf)]">
+    <div className={COMMENT_THREAD_LIST}>
       {comments.map(comment => (
         <CommentThreadRow
           key={comment.id}
@@ -78,6 +96,15 @@ export function CommentThread({
   );
 }
 
+/** A root's Reply button: static copy, drawn for real in the loaded thread and (inert) in its skeleton. */
+function ReplyButton({ onClick, disabled }: { onClick?: () => void; disabled?: boolean }) {
+  return (
+    <Button type="button" variant="outline" size="small-legacy" onClick={onClick} disabled={disabled}>
+      Reply
+    </Button>
+  );
+}
+
 function CommentThreadRow({
   comment,
   onReply,
@@ -101,18 +128,8 @@ function CommentThreadRow({
         </span>
       ) : null}
       {onReply || actions ? (
-        <span className="ml-auto flex flex-wrap gap-[var(--spacing-system-xsf)]">
-          {onReply ? (
-            <Button
-              type="button"
-              variant="outline"
-              size="small-legacy"
-              onClick={() => setReplyOpen(open => !open)}
-              disabled={pending}
-            >
-              Reply
-            </Button>
-          ) : null}
+        <span className={COMMENT_THREAD_ACTIONS}>
+          {onReply ? <ReplyButton onClick={() => setReplyOpen(open => !open)} disabled={pending} /> : null}
           {actions}
         </span>
       ) : null}
@@ -160,6 +177,38 @@ function CommentThreadRow({
   );
 }
 
+/**
+ * A thread while it is read: `count` comment rows, each `CommentCardSkeleton` in the thread's own list, with the
+ * root's Reply button drawn for real when the thread takes replies (a root's reply count, badges and actions are read,
+ * so they are not drawn).
+ */
+export function CommentThreadSkeleton({
+  count = COMMENT_THREAD_SKELETON_COUNT,
+  leadWith = 'commenter',
+  showTitle = true,
+  reply = false,
+}: {
+  count?: number;
+  leadWith?: 'vendor' | 'commenter';
+  /** The rows carry a title line (titled reviews); a design-doc thread's comments have none. */
+  showTitle?: boolean;
+  /** The thread takes replies (`CommentThread`'s `onReply`): each root's footer carries its Reply button. */
+  reply?: boolean;
+}) {
+  const footer = reply ? (
+    <span className={COMMENT_THREAD_ACTIONS}>
+      <ReplyButton />
+    </span>
+  ) : undefined;
+  return (
+    <div className={COMMENT_THREAD_LIST} aria-hidden="true" inert>
+      {Array.from({ length: count }, (_, i) => (
+        <CommentCardSkeleton key={i} leadWith={leadWith} showTitle={showTitle} showDelete={false} footer={footer} />
+      ))}
+    </div>
+  );
+}
+
 export interface CommentsBlockProps {
   /** Header label, e.g. "Comments". */
   title: string;
@@ -180,6 +229,7 @@ export interface CommentsBlockProps {
  * (content behind an accordion is content readers miss).
  */
 export function CommentsBlock({ title, summary, defaultOpen = false, children, composer }: CommentsBlockProps) {
+  const loading = useLoadingScope();
   const [open, setOpen] = useState(defaultOpen);
   // New activity AFTER mount (a colleague's comment arrives) flips `defaultOpen`
   // to true and must expand the block; collapsing again stays the reader's call.
@@ -189,15 +239,29 @@ export function CommentsBlock({ title, summary, defaultOpen = false, children, c
     setSeenDefaultOpen(defaultOpen);
     if (defaultOpen) setOpen(true);
   }
+  // In a scope the header keeps its real title and its summary is a bar; the thread under it draws its own skeleton.
+  if (loading) {
+    return (
+      <div className={COMMENTS_BLOCK}>
+        <CommentsBlockHeader title={title} open={open} />
+        {open ? (
+          <>
+            {children}
+            {composer}
+          </>
+        ) : null}
+      </div>
+    );
+  }
   return (
-    <div className="space-y-[var(--spacing-system-sf)]">
+    <div className={COMMENTS_BLOCK}>
       <Button
         type="button"
         variant="transparent"
         size="small-legacy"
-        className="px-0 text-ods-text-secondary hover:text-ods-text-primary"
+        className={COMMENTS_BLOCK_HEADER}
         onClick={() => setOpen(value => !value)}
-        rightIcon={<ChevronDown className={`h-4 w-4 transition-transform ${open ? 'rotate-180' : ''}`} />}
+        rightIcon={<ChevronDown className={commentsBlockChevron(open)} />}
       >
         {`${title} · ${summary}`}
       </Button>
@@ -210,3 +274,52 @@ export function CommentsBlock({ title, summary, defaultOpen = false, children, c
     </div>
   );
 }
+
+/** The block's header while its summary is read: the real title, a bar for the summary. */
+function CommentsBlockHeader({ title, open }: { title: string; open: boolean }) {
+  return (
+    <Button
+      type="button"
+      variant="transparent"
+      size="small-legacy"
+      className={COMMENTS_BLOCK_HEADER}
+      rightIcon={<ChevronDown className={commentsBlockChevron(open)} />}
+      tabIndex={-1}
+      aria-hidden
+    >
+      {`${title} · `}
+      <TextLineSkeleton as="span" type="h6" className="inline-block w-20 align-middle" />
+    </Button>
+  );
+}
+
+/**
+ * The comments section while it is read: its real title, the summary as a bar, `count` comment rows (none: the
+ * block is collapsed) and, with `composer`, the root composer's real static controls (inert).
+ */
+export function CommentsBlockSkeleton({
+  title,
+  count = 0,
+  composer = false,
+  leadWith,
+  showTitle,
+}: {
+  title: string;
+  count?: number;
+  composer?: boolean;
+  leadWith?: 'vendor' | 'commenter';
+  showTitle?: boolean;
+}) {
+  const open = count > 0 || composer;
+  return (
+    <div className={COMMENTS_BLOCK} aria-hidden>
+      <CommentsBlockHeader title={title} open={open} />
+      {count > 0 && <CommentThreadSkeleton count={count} leadWith={leadWith} showTitle={showTitle} />}
+      {composer && (
+        <div inert>
+          <CommentComposer onSubmit={() => false} />
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -7,7 +7,6 @@ import type { DocContent, DocNode, DocRenderHandlers, DocSourceId } from '../../
 import { findDocNodeByPath } from '../../utils/doc-tree-nav';
 import { PageShell } from '../layout/article-detail-layout';
 import { PageLayout } from '../layout/page-layout';
-import { CategorySidebarSkeleton } from '../loading/page-layout-skeleton';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
 import { MultiLevelNavigation, MobileNavigationDropdown } from '../navigation/multi-level-navigation';
 import { StickySectionNav } from '../navigation/sticky-section-nav';
@@ -140,6 +139,10 @@ export function DocViewer(props: DocViewerProps) {
   return <DocViewerContent {...props} />;
 }
 
+/** The "On this page" column's heading: static copy, drawn for real loaded and loading. */
+const ON_THIS_PAGE_LABEL = 'ON THIS PAGE';
+const ON_THIS_PAGE_HEADING_CLASS = 'mb-4 font-semibold text-ods-text-secondary text-h5';
+
 function DocViewerContent({
   sourceId,
   renderContent,
@@ -279,7 +282,10 @@ function DocViewerContent({
       <PageLayout title={title} subtitle={subtitle} titleSize="h1" titleWrap backButton={backCfg ?? undefined}>
         <div className="flex w-full flex-col gap-10">
           {/* Where the document is mirrored from: the first row under the title, as on every synced page. */}
-          {synced && <DataSyncLine sync={content?.sync} loading={isLoadingContent && !content} />}
+          {/* Loading until the document is here: the structure read comes first, so the server's HTML holds the line too. */}
+          {synced && (
+            <DataSyncLine sync={content?.sync} loading={!content && (isLoadingContent || isLoadingStructure)} />
+          )}
           {showAIChat && (
             <DocSearchBar
               placeholder={`Search ${sidebarLabel?.toLowerCase() || 'documents'}...`}
@@ -305,40 +311,36 @@ function DocViewerContent({
             <div className="flex flex-1 flex-col items-start gap-6 content-lg:flex-row content-lg:gap-10">
               <div className="w-full content-lg:w-[320px] content-lg:shrink-0">
                 <div className="content-lg:sticky content-lg:top-20">
-                  {isLoadingStructure ? (
-                    <CategorySidebarSkeleton />
-                  ) : (
-                    <>
-                      <PersistentMobileDropdown isLoading={false}>
-                        <MobileNavigationDropdown
+                  {/* While the tree is read, the dropdown and the sidebar are their own skeletons (`isLoading`), each at
+                      its breakpoint, so the loading state is the loaded tree's frame. */}
+                  <PersistentMobileDropdown isLoading={false}>
+                    <MobileNavigationDropdown
+                      nodes={structure}
+                      selectedPath={selectedPath}
+                      expandedNodes={expandedNodes}
+                      onNodeClick={selectNode}
+                      onToggleExpand={toggleNode}
+                      isLoading={isLoadingStructure}
+                      folderIndexFile={folderIndexFile}
+                    />
+                  </PersistentMobileDropdown>
+
+                  <PersistentSidebar isLoading={false}>
+                    <div className="hidden content-lg:block">
+                      <div className="space-y-4">
+                        <h3 className="font-semibold text-ods-text-secondary text-h5">{sidebarLabel}</h3>
+                        <MultiLevelNavigation
                           nodes={structure}
                           selectedPath={selectedPath}
                           expandedNodes={expandedNodes}
                           onNodeClick={selectNode}
                           onToggleExpand={toggleNode}
-                          isLoading={false}
+                          isLoading={isLoadingStructure}
                           folderIndexFile={folderIndexFile}
                         />
-                      </PersistentMobileDropdown>
-
-                      <PersistentSidebar isLoading={false}>
-                        <div className="hidden content-lg:block">
-                          <div className="space-y-4">
-                            <h3 className="font-semibold text-ods-text-secondary text-h5">{sidebarLabel}</h3>
-                            <MultiLevelNavigation
-                              nodes={structure}
-                              selectedPath={selectedPath}
-                              expandedNodes={expandedNodes}
-                              onNodeClick={selectNode}
-                              onToggleExpand={toggleNode}
-                              isLoading={false}
-                              folderIndexFile={folderIndexFile}
-                            />
-                          </div>
-                        </div>
-                      </PersistentSidebar>
-                    </>
-                  )}
+                      </div>
+                    </div>
+                  </PersistentSidebar>
                 </div>
               </div>
 
@@ -378,7 +380,7 @@ function DocViewerContent({
                   {isMarkdownContent && (isLoadingContent || isLoadingStructure) && (
                     <div className="hidden content-lg:block">
                       <div className="sticky top-24">
-                        <UnifiedSkeleton className="mb-5 h-[14px] w-28 rounded" />
+                        <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
@@ -398,7 +400,7 @@ function DocViewerContent({
                   {showStickyNav && content && stickyNavSections.length > 0 && !isLoadingContent && (
                     <div className="hidden content-lg:block">
                       <div className="sticky top-24">
-                        <h3 className="mb-4 font-semibold text-ods-text-secondary text-h5">ON THIS PAGE</h3>
+                        <h3 className={ON_THIS_PAGE_HEADING_CLASS}>{ON_THIS_PAGE_LABEL}</h3>
                         <StickySectionNav
                           sections={stickyNavSections}
                           activeSection={activeSection}

package/src/components/docs/skeletons.tsx

@@ -1,66 +1,54 @@
+import { cn } from '../../utils/cn';
 import { EmbedLoadingSkeleton } from '../embeds/embed-iframe';
 import { LoadingRegion } from '../loading/loading-region';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { TextLineSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
+import { MARKDOWN_H2_CLASS, MARKDOWN_PARAGRAPH_CLASS } from '../ui/markdown/base-components';
+import { MARKDOWN_RENDERER_CLASS } from '../ui/markdown/engine';
+import { TEXT_SIZE_PRESETS } from '../ui/markdown/text-size';
 /**
  * Text-style skeleton — matches a rendered markdown article layout.
  * Used by `<DocsHubPage>` as the default for `markdown` (and unknown
  * document types). Embedders can override via `renderSkeleton`.
  */
+/** Paragraphs and headings the markdown skeleton draws (a document's first fold), with each paragraph's lines. */
+const MARKDOWN_SKELETON_BLOCKS = [
+  { kind: 'p', lines: 4 },
+  { kind: 'p', lines: 4 },
+  { kind: 'p', lines: 5 },
+  { kind: 'h2' },
+  { kind: 'p', lines: 4 },
+  { kind: 'p', lines: 5 },
+  { kind: 'h2' },
+  { kind: 'p', lines: 3 },
+  { kind: 'p', lines: 4 },
+] as const;
+const MARKDOWN_SKELETON_H2_CLASS = cn(MARKDOWN_H2_CLASS, TEXT_SIZE_PRESETS.default.h2);
+const MARKDOWN_SKELETON_P_CLASS = cn(MARKDOWN_PARAGRAPH_CLASS, TEXT_SIZE_PRESETS.default.p);
+
 export function MarkdownSkeleton({
   region = true,
 }: {
   /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
   region?: boolean;
 } = {}) {
+  // The rendered document's own heading and paragraph elements (the markdown renderer's default preset), each line a
+  // bar of the element's line box.
   return (
-    <LoadingRegion label="Loading the document" announce={region} className="mt-6 space-y-7">
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-3/4 rounded" />
-      </div>
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-5/6 rounded" />
-      </div>
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-2/3 rounded" />
-      </div>
-      <UnifiedSkeleton className="h-[88px] rounded-lg border border-ods-border" />
-      <UnifiedSkeleton className="h-7 w-1/3 rounded" />
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-[72%] rounded" />
-      </div>
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-[58%] rounded" />
-      </div>
-      <UnifiedSkeleton className="h-7 w-2/5 rounded" />
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-[90%] rounded" />
-      </div>
-      <div className="space-y-[14px]">
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-full rounded" />
-        <UnifiedSkeleton className="h-[16px] w-[70%] rounded" />
-      </div>
-      <UnifiedSkeleton className="h-[88px] rounded-lg border border-ods-border" />
+    // The renderer's root class, and its box (no margin of its own, like the rendered body): the document's first fold.
+    <LoadingRegion label="Loading the document" announce={region} className={MARKDOWN_RENDERER_CLASS}>
+      {MARKDOWN_SKELETON_BLOCKS.map((block, i) =>
+        block.kind === 'h2' ? (
+          // biome-ignore lint/suspicious/noArrayIndexKey: skeleton blocks never reorder
+          <h2 key={i} className={MARKDOWN_SKELETON_H2_CLASS} aria-hidden>
+            <TextLineSkeleton type="inherit" as="span" className="w-1/3" />
+          </h2>
+        ) : (
+          // biome-ignore lint/suspicious/noArrayIndexKey: skeleton blocks never reorder
+          <p key={i} className={MARKDOWN_SKELETON_P_CLASS} aria-hidden>
+            <TextLineSkeleton type="inherit" as="span" lines={block.lines} className="w-full" />
+          </p>
+        ),
+      )}
     </LoadingRegion>
   );
 }

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

@@ -13,6 +13,7 @@ import {
 import { contentFetch } from '../../utils/embed-content-fetch';
 import { navigateSamePageHash, HUB_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
 import { scrollElementIntoView } from '../../utils/scroll-into-view';
+import { useLoadingScope } from '../ui/loading-scope';
 import { useDocNavigation } from './doc-navigation-context';
 
 function scrollToContent() {
@@ -226,6 +227,10 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
   const [error, setError] = useState<string | null>(null);
   const [expandedNodes, setExpandedNodes] = useState<Set<string>>(new Set());
   const lastFetchedPath = useRef<string | null>(null);
+  // In a loading scope nothing is fetched: the viewer reports itself loading, so it draws its own skeleton.
+  const held = useLoadingScope();
+  // The first fetch has started: it starts once, when the hook is first out of a loading scope.
+  const startedRef = useRef(false);
 
   const normalizedBaseRoute = baseRoute.replace(/\/$/, '');
 
@@ -471,10 +476,8 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
     latestRef.current = { fetchContent, fetchStructure, cleanInitialPath, folderIndexFile };
   });
 
-  // Mount-only. The `isInitialized` state this used to latch on was read
-  // NOWHERE else: it was a run-once guard that cost a setState in an effect
-  // body (and a second, no-op run of this effect) to say what empty deps say
-  // directly.
+  // Runs once (`startedRef`), when the hook is first outside a loading scope: at mount, or when a scope it
+  // mounted in ends. A ref, not state: nothing renders from it.
   useEffect(() => {
     // Kick off the speculative content fetch IN PARALLEL with the structure
     // fetch — the two endpoints are independent and most landing pages have
@@ -484,6 +487,9 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
     // useEffect issues the correct fetch after structure arrives — the
     // speculative result silently no-ops (the content state update gets
     // overwritten by the targeted fetch).
+    // Starts once, the first time the hook is out of a loading scope (at mount, or when the scope ends).
+    if (held || startedRef.current) return;
+    startedRef.current = true;
     const latest = latestRef.current;
     const speculativeContentPath = latest.cleanInitialPath || latest.folderIndexFile;
     lastFetchedPath.current = speculativeContentPath;
@@ -492,7 +498,7 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
     // independent endpoints stay in parallel.
     void latest.fetchContent(speculativeContentPath);
     void latest.fetchStructure();
-  }, []);
+  }, [held]);
 
   useEffect(() => {
     if (selectedPath === null || selectedPath === undefined) return;
@@ -746,5 +752,3 @@ export function useDocumentTree(config: UseDocumentTreeConfig, initialPath?: str
     setExpandedNodes,
   };
 }
-
-export type { DocNode, DocContent };

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

@@ -3,6 +3,7 @@
 import type React from 'react';
 import { useState, useCallback, useRef, useEffect } from 'react';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from '../ui/loading-scope';
 
 /** Loading skeleton for iframe embeds: a clean iframe-sized `UnifiedSkeleton`
  *  rectangle. No fake inner placeholder cruft: a real loading iframe shows a
@@ -86,6 +87,7 @@ export function EmbedIframe({
   const isLoaded = loadedSrc === src;
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const handleLoad = useCallback(() => setLoadedSrc(src), [src]);
+  const held = useLoadingScope();
 
   useEffect(() => {
     const iframe = iframeRef.current;
@@ -102,6 +104,9 @@ export function EmbedIframe({
 
   const resolvedHeight = height || 'calc(100vh - 250px)';
 
+  // In a loading scope the embed is its loading box, and nothing is framed.
+  if (held) return <EmbedLoadingSkeleton height={resolvedHeight} />;
+
   return (
     <>
       {!isLoaded && <EmbedLoadingSkeleton height={resolvedHeight} />}

package/src/components/embeds/index.ts

@@ -14,7 +14,7 @@ export type { FigmaEmbedProps } from './figma-embed';
 export { ClaudeEmbed } from './claude-embed';
 export type { ClaudeEmbedProps, ClaudeEmbedKind } from './claude-embed';
 
-export { OGLinkPreview, OGLinkErrorBoundary, OGLinkTileSkeleton } from './og-link-preview';
+export { OGLinkPreview, OGLinkErrorBoundary, OGLinkPreviewSkeleton, OGLinkTileSkeleton } from './og-link-preview';
 export type { OGLinkPreviewProps, OGData } from './og-link-preview';
 
 export { FileDownloadCard } from './file-download-card';

package/src/components/embeds/markdown-image.tsx

@@ -3,6 +3,7 @@
 import { useEffect, useState } from 'react';
 import Image from '../../embed-shims/next-image';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from '../ui/loading-scope';
 import { useRichMarkdownRuntime } from './rich-markdown-runtime';
 
 /**
@@ -32,6 +33,8 @@ const DISPLAY_W = 768; // logical width hint; the optimizer handles srcset + ret
 
 export function MarkdownImage({ src, alt }: { src: string; alt?: string }) {
   const { transformImageSrc } = useRichMarkdownRuntime();
+  // In a loading scope the image is the box it reserves while probing, and nothing is fetched.
+  const held = useLoadingScope();
   // Tagged with the src it was measured from. That tag IS the reset: a reused
   // instance handed a new `src` stops matching immediately, so it can never
   // size the new image with the previous image's ratio — where the old explicit
@@ -41,6 +44,7 @@ export function MarkdownImage({ src, alt }: { src: string; alt?: string }) {
   const ratio = probed?.src === src ? probed.ratio : null; // width / height
 
   useEffect(() => {
+    if (held) return undefined;
     let cancelled = false;
     // Probe a tiny aspect-preserving variant so we learn the real ratio without
     // downloading the full image; the display copy is then fetched once, at the right size.
@@ -59,10 +63,10 @@ export function MarkdownImage({ src, alt }: { src: string; alt?: string }) {
     return () => {
       cancelled = true;
     };
-  }, [src, transformImageSrc]);
+  }, [src, transformImageSrc, held]);
 
   // Reserve a neutral box while probing so the layout doesn't jump when the image appears.
-  if (!ratio) {
+  if (!ratio || held) {
     return (
       <UnifiedSkeleton
         as="span"