Implement eager image loading optimization in Markdown component and add tests

Author: LadyBluenotes

src/components/markdown/Markdown.tsx

@@ -1,7 +1,11 @@
 import { renderMarkdownReact } from '@tanstack/markdown/react'
 import * as React from 'react'
 import { InlineCode, MarkdownImg } from '~/ui'
-import { parseSiteMarkdown, type MarkdownDocument } from '~/utils/markdown'
+import {
+  findFirstImageSrc,
+  parseSiteMarkdown,
+  type MarkdownDocument,
+} from '~/utils/markdown'
 import { isSafeHttpUrl } from '~/utils/url-boundary'
 import { CodeBlock } from './CodeBlock'
 import { MarkdownLink } from './MarkdownLink'
@@ -13,7 +17,6 @@ import {
 
 type MarkdownRenderOptions = {
   preserveTabPanels?: boolean
-  eagerFirstImage?: boolean
 }
 
 export type MarkdownProps = {
@@ -34,16 +37,17 @@ export function Markdown({
     () => document ?? parseSiteMarkdown(content ?? ''),
     [content, document],
   )
-  const heroConsumedRef = React.useRef(false)
-  heroConsumedRef.current = false
 
   return React.useMemo(() => {
+    const firstImageSrc = eagerFirstImage
+      ? findFirstImageSrc(parsed)
+      : undefined
+
     return renderMarkdownReact(parsed, {
       allowHtml: true,
       components: createMarkdownComponents({
         preserveTabPanels,
-        eagerFirstImage,
-        heroConsumedRef,
+        firstImageSrc,
       }),
       headingAnchors,
     })
@@ -169,9 +173,7 @@ function TableElement({
 }
 
 function createMarkdownComponents(
-  options: MarkdownRenderOptions & {
-    heroConsumedRef?: React.RefObject<boolean>
-  } = {},
+  options: MarkdownRenderOptions & { firstImageSrc?: string } = {},
 ) {
   function MdCommentComponentWithOptions(
     props: React.ComponentProps<typeof MdCommentComponent>,
@@ -185,13 +187,9 @@ function createMarkdownComponents(
   }
 
   function ImgElement(props: React.ComponentProps<typeof MarkdownImg>) {
-    const heroConsumedRef = options.heroConsumedRef
     const isFirstImage =
-      options.eagerFirstImage && heroConsumedRef && !heroConsumedRef.current
-
-    if (isFirstImage) {
-      heroConsumedRef.current = true
-    }
+      options.firstImageSrc !== undefined &&
+      props.src === options.firstImageSrc
 
     return <MarkdownImg {...props} priority={isFirstImage} />
   }

src/utils/markdown/findFirstImageSrc.ts

@@ -0,0 +1,30 @@
+import type { InlineNode } from '@tanstack/markdown'
+import type { MarkdownDocument } from './processor'
+
+export function findFirstImageSrc(
+  document: MarkdownDocument,
+): string | undefined {
+  for (const block of document.children) {
+    if (block.type === 'paragraph' || block.type === 'heading') {
+      const found = findFirstImageSrcInInline(block.children)
+      if (found) return found
+    } else if (block.type !== 'thematicBreak' && block.type !== 'html') {
+      // Every current blog post's hero image is a bare top-level paragraph;
+      // stop rather than reach into lists/tables/blockquotes/tab panels,
+      // where a "first" image may not even be visible on initial paint.
+      return undefined
+    }
+  }
+  return undefined
+}
+
+function findFirstImageSrcInInline(nodes: InlineNode[]): string | undefined {
+  for (const node of nodes) {
+    if (node.type === 'image') return node.src
+    if ('children' in node) {
+      const found = findFirstImageSrcInInline(node.children)
+      if (found) return found
+    }
+  }
+  return undefined
+}

src/utils/markdown/index.ts

@@ -1,3 +1,4 @@
+export { findFirstImageSrc } from './findFirstImageSrc'
 export {
   parseSiteMarkdown,
   type MarkdownDocument,

tests/blog-hero-image.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findFirstImageSrc, parseSiteMarkdown } from '../src/utils/markdown'
+
+// Guards the eagerFirstImage optimization (blog.$.tsx -> Markdown ->
+// findFirstImageSrc): if a future post's structure stops the walker before
+// its first image (e.g. a list/table/blockquote appears earlier in the
+// document), the post silently falls back to lazy-loading its hero image
+// instead of failing loudly. This test makes that regression visible.
+
+const blogDir = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../src/blog',
+)
+
+function stripFrontmatter(content: string) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n?/)
+  return match ? content.slice(match[0].length) : content
+}
+
+const postFiles = fs
+  .readdirSync(blogDir)
+  .filter((file) => file.endsWith('.md'))
+
+assert.ok(
+  postFiles.length > 0,
+  'expected to find blog posts in src/blog',
+)
+
+for (const file of postFiles) {
+  const raw = fs.readFileSync(path.join(blogDir, file), 'utf-8')
+  const body = stripFrontmatter(raw)
+  const hasBodyImage = /!\[[^\]]*\]\([^)]+\)/.test(body)
+
+  if (!hasBodyImage) continue
+
+  const document = parseSiteMarkdown(body)
+  const firstImageSrc = findFirstImageSrc(document)
+
+  assert.notEqual(
+    firstImageSrc,
+    undefined,
+    `${file} contains a body image but findFirstImageSrc() returned ` +
+      `undefined - its first image is no longer reachable through plain ` +
+      `paragraphs/headings, so the blog hero eager-load optimization is ` +
+      `silently disabled for this post`,
+  )
+}
+
+console.log('blog-hero-image tests passed')