@flamingo-stack/openframe-frontend-core 0.0.765 → 0.0.767

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"

package/src/components/embeds/og-link-preview.tsx

@@ -6,7 +6,10 @@ import Image from '../../embed-shims/next-image';
 import Link from '../../embed-shims/next-link';
 import { useImageEdgeColor } from '../../hooks';
 import { useOgPlaceholderUrl } from '../../hooks/use-og-placeholder-url';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { ICON_SIZE, MEDIA_ASPECT, TILE_SIZE } from '../../styles/component-sizes';
+import { cn } from '../../utils/cn';
+import { TextLineSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from '../ui/loading-scope';
 import { TruncateText } from '../ui/truncate-text';
 
 /**
@@ -169,22 +172,122 @@ const Favicon = ({ src, size = 'w-6 h-6' }: { src: string; size?: string }) => (
   />
 );
 
+/** The cards' layout, read by the cards and by their skeleton, so the skeleton is the card's size. */
+const COMPACT_OUTER_CLASS = 'my-4';
+const COMPACT_FRAME_CLASS = 'flex h-[120px] flex-row overflow-hidden rounded-lg border border-ods-border bg-ods-card';
+const COMPACT_MEDIA_CLASS = 'h-full w-[200px] flex-shrink-0';
+const COMPACT_BODY_CLASS = 'flex min-w-0 flex-1 flex-col justify-center p-3';
+/** The compact card with no image: one row of a favicon box, the title and description lines, the link mark. */
+const COMPACT_ROW_CLASS =
+  'flex flex-row items-center gap-3 overflow-hidden rounded-lg border border-ods-border bg-ods-card px-4 py-3';
+const COMPACT_ICON_BOX_CLASS = `flex ${TILE_SIZE.sm} flex-shrink-0 items-center justify-center rounded-lg bg-ods-bg-surface`;
+/** The no-image compact row's favicon, read by the row and by its skeleton. */
+const COMPACT_FAVICON_CLASS = 'w-5 h-5';
+/** The default card's publication logo beside the title, read by the card and by its skeleton. */
+const DEFAULT_LOGO_CLASS = `mt-0.5 ${ICON_SIZE.lg} flex-shrink-0 rounded`;
+const COMPACT_ROW_TEXT_CLASS = 'min-w-0 flex-1';
+const COMPACT_ROW_LINE_CLASS = 'truncate text-h6';
+const DEFAULT_OUTER_CLASS = 'my-6 flex flex-1 flex-col';
+const DEFAULT_FRAME_CLASS = 'flex flex-1 flex-col overflow-hidden rounded-lg border border-ods-border bg-ods-card';
+const DEFAULT_MEDIA_CLASS = `${MEDIA_ASPECT.video} w-full flex-none rounded-lg`;
+const DEFAULT_BODY_CLASS = 'flex-1 p-4';
+const DEFAULT_ROW_CLASS = 'flex items-start gap-3';
+
+/**
+ * A link preview while its page is scraped (or drawn in a loading scope): the `compact` (120px row) or `default`
+ * (16:9 hero) card's frame, the media box, and bars for the title, description and source line.
+ */
+export function OGLinkPreviewSkeleton({
+  variant = 'default',
+  image = true,
+}: {
+  variant?: 'compact' | 'default';
+  /** `false`: the compact card's no-image row (a curated title with no curated image). */
+  image?: boolean;
+}) {
+  if (variant === 'compact' && !image)
+    return (
+      <div className={COMPACT_OUTER_CLASS} aria-hidden>
+        <div className={COMPACT_ROW_CLASS}>
+          <div className={COMPACT_ICON_BOX_CLASS}>
+            <UnifiedSkeleton className={cn(COMPACT_FAVICON_CLASS, 'rounded')} />
+          </div>
+          <div className={COMPACT_ROW_TEXT_CLASS}>
+            <p className={COMPACT_ROW_LINE_CLASS}>
+              <TextLineSkeleton type="inherit" as="span" className="w-2/3" />
+            </p>
+            <p className={COMPACT_ROW_LINE_CLASS}>
+              <TextLineSkeleton type="inherit" as="span" className="w-1/2" />
+            </p>
+          </div>
+          <ExternalLinkIcon size={14} />
+        </div>
+      </div>
+    );
+  if (variant === 'compact')
+    return (
+      <div className={COMPACT_OUTER_CLASS} aria-hidden>
+        <div className={COMPACT_FRAME_CLASS}>
+          <UnifiedSkeleton className={cn(COMPACT_MEDIA_CLASS, 'rounded-lg')} />
+          <div className={COMPACT_BODY_CLASS}>
+            {/* The tile's own lines: a one-line `text-h6` title, a two-line description, the source line. */}
+            <TextLineSkeleton type="h6" className="w-3/4" />
+            <TextLineSkeleton type="h6" lines={2} className="mt-1 w-full" />
+            <TextLineSkeleton type="h6" className="mt-1 w-1/3" />
+          </div>
+        </div>
+      </div>
+    );
+  return (
+    <div className={DEFAULT_OUTER_CLASS} aria-hidden>
+      <div className={DEFAULT_FRAME_CLASS}>
+        <UnifiedSkeleton className={DEFAULT_MEDIA_CLASS} />
+        <div className={DEFAULT_BODY_CLASS}>
+          <div className={DEFAULT_ROW_CLASS}>
+            <UnifiedSkeleton className={DEFAULT_LOGO_CLASS} />
+            <div className="min-w-0 flex-1">
+              {/* The title and the description each reserve two `text-h4` lines (the loaded `TruncateText`s). */}
+              <TextLineSkeleton type="h4" lines={2} className="mb-2 w-full" />
+              <TextLineSkeleton type="h4" lines={2} className="mb-2 w-5/6" />
+              {/* The source line: the site name and the domain, at the line's own type. */}
+              <div className="flex min-h-[var(--font-line-space-h4-body)] items-center gap-2 text-h6">
+                <TextLineSkeleton type="inherit" as="span" className="w-24" />
+                <TextLineSkeleton type="inherit" as="span" className="w-20" />
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 /**
  * The `tile` card while its list loads: the tile's exact geometry (the `p-3`
  * card, the source row with a favicon dot, two headline lines, the excerpt
  * line), owned here so the tile and its loading state cannot drift apart.
  */
+/** The tile's layout, read by the tile and by its skeleton. */
+const TILE_FRAME_CLASS = 'flex min-w-0 flex-col gap-1.5 rounded-lg border border-ods-border bg-ods-card p-3';
+const TILE_SOURCE_ROW_CLASS = 'flex min-w-0 items-center gap-1.5 text-h6';
+/** The headline's and the excerpt's type (the loaded `TruncateText`s take them as their `variant`). */
+const TILE_HEADLINE_CLASS = 'text-h3';
+const TILE_EXCERPT_CLASS = 'text-h6';
+
 export function OGLinkTileSkeleton() {
   return (
-    <div className="flex min-w-0 flex-col gap-1.5 rounded-lg border border-ods-border bg-ods-card p-3">
-      <div className="flex items-center gap-1.5">
+    <div className={TILE_FRAME_CLASS} aria-hidden>
+      <div className={TILE_SOURCE_ROW_CLASS}>
         <UnifiedSkeleton className="h-4 w-4 flex-shrink-0 rounded" />
-        <UnifiedSkeleton className="h-3 w-20 rounded" />
-        <UnifiedSkeleton className="ml-auto h-3 w-9 rounded" />
+        <TextLineSkeleton type="inherit" as="span" className="w-20" />
+        <TextLineSkeleton type="inherit" as="span" className="ml-auto w-9" />
+      </div>
+      <div className={TILE_HEADLINE_CLASS}>
+        <TextLineSkeleton type="inherit" lines={2} className="w-full" />
+      </div>
+      <div className={TILE_EXCERPT_CLASS}>
+        <TextLineSkeleton type="inherit" className="w-5/6" />
       </div>
-      <UnifiedSkeleton className="h-3.5 w-full rounded" />
-      <UnifiedSkeleton className="h-3.5 w-3/4 rounded" />
-      <UnifiedSkeleton className="h-3 w-5/6 rounded" />
     </div>
   );
 }
@@ -261,10 +364,12 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
   }
 
   const isTile = variant === 'tile';
+  // In a loading scope the preview is not scraped: it stays its own loading state.
+  const held = useLoadingScope();
 
   useEffect(() => {
     // A tile is drawn from its props alone: no scrape.
-    if (!isValidUrl || isLocalhost || isTile) return undefined;
+    if (!isValidUrl || isLocalhost || isTile || held) return undefined;
 
     // A `url` change starts a second fetch while the first is still in flight.
     // Without this guard the SUPERSEDED response can land last and paint the
@@ -323,7 +428,7 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
     return () => {
       cancelled = true;
     };
-  }, [url, isValidUrl, isLocalhost, isTile, apiBaseUrl, ogEndpointPath]);
+  }, [url, isValidUrl, isLocalhost, isTile, held, apiBaseUrl, ogEndpointPath]);
 
   const isCompact = variant === 'compact';
   const domain = getDomain(url);
@@ -375,51 +480,16 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
   const isPlaceholder = resolvedImage?.source === 'placeholder';
   const bgColor = useImageEdgeColor(resolvedImageUrl ?? null, 'var(--color-bg-surface)');
 
-  const renderSkeleton = () =>
-    isCompact ? (
-      <div className="my-4">
-        <div className="flex h-[120px] flex-row overflow-hidden rounded-lg border border-ods-border bg-ods-card">
-          <UnifiedSkeleton className="h-full w-[200px] flex-shrink-0" />
-          <div className="flex flex-1 flex-col justify-center p-3">
-            <UnifiedSkeleton className="mb-2 h-4 w-3/4 rounded" />
-            <UnifiedSkeleton className="mb-1 h-3 w-full rounded" />
-            <UnifiedSkeleton className="mb-2 h-3 w-2/3 rounded" />
-            <UnifiedSkeleton className="h-3 w-1/3 rounded" />
-          </div>
-        </div>
-      </div>
-    ) : (
-      <div className="my-6">
-        <div className="block overflow-hidden rounded-lg border border-ods-border bg-ods-card">
-          <UnifiedSkeleton className="relative aspect-video w-full overflow-hidden rounded-none" />
-          <div className="p-4">
-            <div className="flex items-start gap-3">
-              <UnifiedSkeleton className="mt-0.5 h-6 w-6 flex-shrink-0 rounded" />
-              <div className="min-w-0 flex-1">
-                {/* Two rows of exactly one h4 line each (the bar centred inside), the
-                    height of the loaded card's two-line title and description. */}
-                {[
-                  ['w-full', 'w-3/4'],
-                  ['w-full', 'w-5/6'],
-                ].map(widths => (
-                  <div key={widths[1]} className="mb-2">
-                    {widths.map(width => (
-                      <div key={width} className="flex h-[var(--font-line-space-h4-body)] items-center">
-                        <UnifiedSkeleton className={`h-4 ${width} rounded`} />
-                      </div>
-                    ))}
-                  </div>
-                ))}
-                <div className="flex min-h-[var(--font-line-space-h4-body)] items-center gap-2">
-                  <UnifiedSkeleton width="6rem" height="0.75rem" className="rounded" />
-                  <UnifiedSkeleton width="5rem" height="0.75rem" className="rounded" />
-                </div>
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    );
+  const renderSkeleton = () => (
+    <OGLinkPreviewSkeleton
+      variant={isCompact ? 'compact' : 'default'}
+      // A curated title with no curated image paints the no-image row while the scrape refines it.
+      image={!(curatedTitle && !curatedImage)}
+    />
+  );
+
+  // In a loading scope the card is its skeleton (a tile: the tile's own).
+  if (held) return isTile ? <OGLinkTileSkeleton /> : renderSkeleton();
 
   if (isTile) {
     const name = publicationName || domainToTitle(domain);
@@ -428,11 +498,11 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
         href={url}
         target="_blank"
         rel="noopener noreferrer"
-        className="group flex min-w-0 flex-col gap-1.5 rounded-lg border border-ods-border bg-ods-card p-3 transition-colors hover:border-ods-accent"
+        className={cn(TILE_FRAME_CLASS, 'group transition-colors hover:border-ods-accent')}
       >
-        <div className="flex min-w-0 items-center gap-1.5 text-xs">
+        <div className={TILE_SOURCE_ROW_CLASS}>
           <Favicon src={`https://www.google.com/s2/favicons?domain=${domain}&sz=32`} size="w-4 h-4" />
-          <TruncateText as="span" className="font-sans text-xs font-medium">
+          <TruncateText as="span" variant="h6" className="text-current">
             {name}
           </TruncateText>
           {meta != null && (
@@ -440,22 +510,20 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
           )}
         </div>
         {kicker != null && (
-          <div
-            className="overflow-hidden font-sans text-xs font-bold uppercase tracking-wide text-ods-accent"
-            style={lineClamp(1)}
-          >
+          <div className="overflow-hidden text-ods-accent text-h5" style={lineClamp(1)}>
             {kicker}
           </div>
         )}
         <TruncateText
           lines={2}
-          className="font-sans text-[15px] font-semibold leading-snug transition-colors group-hover:text-ods-accent"
+          variant="h3"
+          className="transition-colors group-hover:text-ods-accent"
           triggerClassName="-mt-0.5"
         >
           {curatedTitle || domainToTitle(domain)}
         </TruncateText>
         {curatedDescription && (
-          <TruncateText lines={2} tone="secondary" className="font-sans text-xs leading-normal">
+          <TruncateText lines={2} variant="h6" tone="secondary">
             {curatedDescription}
           </TruncateText>
         )}
@@ -536,17 +604,17 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
   if (isCompact) {
     if (!hasImage) {
       return (
-        <div className="my-4">
+        <div className={COMPACT_OUTER_CLASS}>
           <Link
             href={effectiveData.url}
             target="_blank"
             rel="noopener noreferrer"
-            className="group flex flex-row items-center gap-3 overflow-hidden rounded-lg border border-ods-border bg-ods-card px-4 py-3 transition-all duration-200 hover:border-ods-accent"
+            className={cn(COMPACT_ROW_CLASS, 'group transition-all duration-200 hover:border-ods-accent')}
           >
-            <div className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-lg bg-ods-bg-surface">
-              <Favicon src={faviconSrc} size="w-5 h-5" />
+            <div className={COMPACT_ICON_BOX_CLASS}>
+              <Favicon src={faviconSrc} size={COMPACT_FAVICON_CLASS} />
             </div>
-            <div className="min-w-0 flex-1">
+            <div className={COMPACT_ROW_TEXT_CLASS}>
               <h3 className="truncate font-semibold text-ods-text-primary transition-colors text-h6 group-hover:text-ods-accent">
                 {title}
               </h3>
@@ -563,15 +631,18 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
           href={effectiveData.url}
           target="_blank"
           rel="noopener noreferrer"
-          className="group flex h-[120px] flex-row overflow-hidden rounded-lg border border-ods-border bg-ods-card transition-colors hover:border-ods-accent"
+          className={cn(COMPACT_FRAME_CLASS, 'group transition-colors hover:border-ods-accent')}
         >
           <div
-            className="relative flex h-full w-[200px] flex-shrink-0 items-center justify-center overflow-hidden rounded-lg transition-colors duration-300"
+            className={cn(
+              COMPACT_MEDIA_CLASS,
+              'relative flex items-center justify-center overflow-hidden rounded-lg transition-colors duration-300',
+            )}
             style={{ backgroundColor: bgColor }}
           >
             {renderImage()}
           </div>
-          <div className="flex min-w-0 flex-1 flex-col justify-center p-3">
+          <div className={COMPACT_BODY_CLASS}>
             <h3
               className="overflow-hidden font-semibold text-ods-text-primary transition-colors text-h6 group-hover:text-ods-accent"
               style={{ display: '-webkit-box', WebkitLineClamp: 1, WebkitBoxOrient: 'vertical' }}
@@ -618,25 +689,28 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
   return (
     // `flex-1` lets the card stretch when the caller places it in a flex column
     // inside a stretching grid (equal row heights); inert in block flow.
-    <div className="my-6 flex flex-1 flex-col">
+    <div className={DEFAULT_OUTER_CLASS}>
       <Link
         href={effectiveData.url}
         target="_blank"
         rel="noopener noreferrer"
-        className="group flex flex-1 flex-col overflow-hidden rounded-lg border border-ods-border bg-ods-card transition-colors hover:border-ods-accent"
+        className={cn(DEFAULT_FRAME_CLASS, 'group transition-colors hover:border-ods-accent')}
       >
         <div
-          className="relative flex aspect-video w-full flex-none items-center justify-center overflow-hidden rounded-lg transition-colors duration-300"
+          className={cn(
+            DEFAULT_MEDIA_CLASS,
+            'relative flex items-center justify-center overflow-hidden transition-colors duration-300',
+          )}
           style={{ backgroundColor: bgColor }}
         >
           {renderImage()}
         </div>
-        <div className="flex-1 p-4">
-          <div className="flex items-start gap-3">
+        <div className={DEFAULT_BODY_CLASS}>
+          <div className={DEFAULT_ROW_CLASS}>
             <Image
               src={logoSrc}
               alt={publicationName || ''}
-              className="mt-0.5 h-6 w-6 flex-shrink-0 rounded object-contain"
+              className={cn(DEFAULT_LOGO_CLASS, 'object-contain')}
               width={24}
               height={24}
               unoptimized
@@ -663,12 +737,12 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
               >
                 {description}
               </TruncateText>
-              <div className="flex min-w-0 items-center gap-2 text-xs text-ods-text-secondary">
-                <TruncateText as="span" className="text-xs font-medium text-current">
+              <div className="flex min-w-0 items-center gap-2 text-ods-text-secondary text-h6">
+                <TruncateText as="span" variant="h6" className="text-current">
                   {effectiveData.siteName}
                 </TruncateText>
                 <span>•</span>
-                <TruncateText as="span" className="text-xs text-current">
+                <TruncateText as="span" variant="h6" className="text-current">
                   {ogDomain}
                 </TruncateText>
                 {meta}

package/src/components/embeds/rich-markdown-runtime.tsx

@@ -41,7 +41,10 @@ const DEFAULT_RUNTIME: RichMarkdownRuntime = {
 const RichMarkdownRuntimeContext = createContext<RichMarkdownRuntime>(DEFAULT_RUNTIME);
 
 /**
- * Provider that fills in defaults for any prop the caller didn't pass.
+ * Provider that fills in any prop the caller didn't pass from the provider ABOVE it (the host's, mounted once at the
+ * root), and from the defaults only where there is none. `RichMarkdownRenderer` mounts one of these around every
+ * document; filling from the defaults there replaced the host's runtime with `transformImageSrc: () => null`, so each
+ * in-article image's size probe downloaded the full original file on every markdown page (CU-17tkuw5xp4q).
  * Memoizes the resolved runtime so satellites don't re-render when an
  * unrelated parent state ticks.
  */
@@ -52,14 +55,15 @@ export function RichMarkdownRuntimeProvider({
   transformImageSrc,
   children,
 }: Partial<RichMarkdownRuntime> & { children: ReactNode }) {
+  const outer = useContext(RichMarkdownRuntimeContext);
   const value = useMemo<RichMarkdownRuntime>(
     () => ({
-      redditProxyUrl: redditProxyUrl ?? DEFAULT_RUNTIME.redditProxyUrl,
-      twitterProxyUrl: twitterProxyUrl ?? DEFAULT_RUNTIME.twitterProxyUrl,
-      ogScraperUrl: ogScraperUrl ?? DEFAULT_RUNTIME.ogScraperUrl,
-      transformImageSrc: transformImageSrc ?? DEFAULT_RUNTIME.transformImageSrc,
+      redditProxyUrl: redditProxyUrl ?? outer.redditProxyUrl,
+      twitterProxyUrl: twitterProxyUrl ?? outer.twitterProxyUrl,
+      ogScraperUrl: ogScraperUrl ?? outer.ogScraperUrl,
+      transformImageSrc: transformImageSrc ?? outer.transformImageSrc,
     }),
-    [redditProxyUrl, twitterProxyUrl, ogScraperUrl, transformImageSrc],
+    [redditProxyUrl, twitterProxyUrl, ogScraperUrl, transformImageSrc, outer],
   );
   return <RichMarkdownRuntimeContext.Provider value={value}>{children}</RichMarkdownRuntimeContext.Provider>;
 }