From cb697049529d549c9b12936ac9d841d1f102a3b7 Mon Sep 17 00:00:00 2001
From: Jeroen De Dauw <jeroendedauw@proton.me>
Date: Fri, 17 Jul 2026 01:16:49 +0200
Subject: [PATCH 1/6] Promote solitary thumbnail embeds out of their paragraph

For https://github.com/ProfessionalWiki/NativeMarkdown/issues/15

A `thumb` embed alone on a line rendered as `<p><figure>...</figure></p>`. A
`<figure>` is flow content, invalid inside a phrasing-only `<p>`, so browsers
auto-close the paragraph and leave a stray empty `<p>` behind it. The HTML is
set directly on ParserOutput, so it never passes through RemexHtml to be fixed.

After parsing, a paragraph whose only content is a thumbnail file embed is now
replaced by the embed node itself, so its `<figure>` is emitted as a sibling of
the surrounding blocks, the way wikitext renders a standalone thumbnail. Embeds
sharing their paragraph with other content, and inline non-thumbnail embeds, are
left untouched, since they render as valid phrasing content in place.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/Application/MarkdownRenderer.php          | 50 +++++++++++++++++++
 .../Application/MarkdownRendererTest.php      | 19 +++++++
 2 files changed, 69 insertions(+)

diff --git a/src/Application/MarkdownRenderer.php b/src/Application/MarkdownRenderer.php
index e0c7a1b..77712c1 100644
--- a/src/Application/MarkdownRenderer.php
+++ b/src/Application/MarkdownRenderer.php
@@ -20,6 +20,7 @@
 use League\CommonMark\Extension\Table\TableCell;
 use League\CommonMark\Node\Block\AbstractBlock;
 use League\CommonMark\Node\Block\Document;
+use League\CommonMark\Node\Block\Paragraph;
 use League\CommonMark\Node\Inline\Newline;
 use League\CommonMark\Node\Inline\Text;
 use League\CommonMark\Node\Node;
@@ -436,6 +437,8 @@ private function preloadFileLookups( array $files, bool $generateHtml ): void {
 	 * @param Section[] $sections
 	 */
 	private function renderHtml( Document $document, array $sections ): string {
+		$this->promoteSolitaryThumbnailEmbeds( $document );
+
 		if ( $this->tocPlaceholderHtml !== null && $sections !== [] ) {
 			$this->insertTocPlaceholder( $document );
 		}
@@ -443,6 +446,53 @@ private function renderHtml( Document $document, array $sections ): string {
 		return $this->htmlRenderer->renderDocument( $document )->getContent();
 	}
 
+	/**
+	 * A thumbnail embed renders a block-level `<figure>`, which is invalid inside
+	 * the phrasing-only `<p>` that CommonMark wraps a solitary inline node in:
+	 * browsers auto-close the paragraph, shipping invalid HTML5 with a stray empty
+	 * `<p>` behind it. When such an embed is a paragraph's only content, replace the
+	 * paragraph with the embed so its `<figure>` becomes a sibling of the
+	 * surrounding blocks, the way wikitext emits a standalone thumbnail. Embeds that
+	 * share their paragraph with other content are left wrapped, since they render
+	 * inline there.
+	 */
+	private function promoteSolitaryThumbnailEmbeds( Document $document ): void {
+		foreach ( $this->nodesOfType( $document, Paragraph::class ) as $paragraph ) {
+			$embed = $this->solitaryThumbnailEmbed( $paragraph );
+
+			if ( $embed !== null ) {
+				$paragraph->replaceWith( $embed );
+			}
+		}
+	}
+
+	/**
+	 * The thumbnail embed that is a paragraph's sole content, ignoring surrounding
+	 * whitespace, or null when the paragraph holds anything else: other text, a
+	 * second embed, or a non-thumbnail embed (which renders inline and needs no
+	 * promotion).
+	 */
+	private function solitaryThumbnailEmbed( Paragraph $paragraph ): ?FileEmbedNode {
+		$embed = null;
+
+		foreach ( $paragraph->children() as $child ) {
+			if ( $child instanceof FileEmbedNode && $child->embed->thumbnail ) {
+				if ( $embed !== null ) {
+					return null;
+				}
+
+				$embed = $child;
+				continue;
+			}
+
+			if ( !$this->isBlankInline( $child ) ) {
+				return null;
+			}
+		}
+
+		return $embed;
+	}
+
 	/**
 	 * Puts the ToC placeholder before the top-level block containing the first
 	 * heading, mirroring where the wikitext parser places the table of contents.
diff --git a/tests/phpunit/Application/MarkdownRendererTest.php b/tests/phpunit/Application/MarkdownRendererTest.php
index 93fec75..6f154c7 100644
--- a/tests/phpunit/Application/MarkdownRendererTest.php
+++ b/tests/phpunit/Application/MarkdownRendererTest.php
@@ -544,6 +544,25 @@ public function testFileEmbedRendersImageAndIsCollectedAsFile(): void {
 		$this->assertSame( [], $result->links );
 	}
 
+	public function testStandaloneThumbnailEmbedIsNotWrappedInParagraph(): void {
+		$html = $this->render( '[[File:Cat.png|thumb|A cat]]' )->html;
+
+		$this->assertStringContainsString( 'data-fake-file="Cat.png"', $html );
+		$this->assertStringNotContainsString( '<p>', $html );
+	}
+
+	public function testSolitaryInlineEmbedStaysWrappedInParagraph(): void {
+		$html = $this->render( '[[File:Cat.png|A cat]]' )->html;
+
+		$this->assertStringContainsString( '<p><img data-fake-file="Cat.png"', $html );
+	}
+
+	public function testThumbnailEmbedWithSurroundingTextStaysInParagraph(): void {
+		$html = $this->render( 'Look: [[File:Cat.png|thumb|A cat]]' )->html;
+
+		$this->assertStringContainsString( '<p>Look: <img data-fake-file="Cat.png"', $html );
+	}
+
 	public function testColonPrefixedFileRendersPageLinkInsteadOfEmbedding(): void {
 		$result = $this->render( '[[:File:Cat.png]]' );
 

From 9c26c298257c91e871512fc81331209e272cac71 Mon Sep 17 00:00:00 2001
From: Jeroen De Dauw <jeroendedauw@proton.me>
Date: Fri, 17 Jul 2026 01:17:11 +0200
Subject: [PATCH 2/6] Frame missing-file thumbnail embeds and keep their
 caption

For https://github.com/ProfessionalWiki/NativeMarkdown/issues/15

A `thumb` embed of a missing file fell through to the plain upload red link,
which is labelled only with the alt text, so the caption was silently dropped.

A missing file with `thumb` now goes through the same core thumbnail path as an
existing one, passing a false File. Core frames a broken-thumb box that keeps the
caption visible and puts the upload link inside, the way wikitext renders a
missing thumbnail. Missing files without `thumb` keep the bare upload link.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../MediaWikiFileEmbedRenderer.php            | 19 ++++++--
 .../MediaWikiFileEmbedRendererTest.php        | 45 +++++++++++++++++++
 2 files changed, 61 insertions(+), 3 deletions(-)

diff --git a/src/Persistence/MediaWikiFileEmbedRenderer.php b/src/Persistence/MediaWikiFileEmbedRenderer.php
index c4f5331..1bd9fc4 100644
--- a/src/Persistence/MediaWikiFileEmbedRenderer.php
+++ b/src/Persistence/MediaWikiFileEmbedRenderer.php
@@ -67,11 +67,15 @@ public function renderEmbed( FileEmbed $embed ): string {
 
 	/**
 	 * Delegates to core so the framed markup, magnify link and responsive
-	 * variants match a wikitext `|thumb` exactly. A width is always passed:
-	 * the requested one, or the wiki's default thumbnail size, since
+	 * variants match a wikitext `|thumb` exactly. For a missing file (a false
+	 * `$file`), core frames a broken-thumb box with the same visible caption and an
+	 * upload link inside, the way wikitext renders a missing thumbnail. A width is
+	 * always passed: the requested one, or the wiki's default thumbnail size, since
 	 * makeThumbLink2 would otherwise fall back to a smaller built-in default.
+	 *
+	 * @param File|false $file
 	 */
-	private function thumbnailFrameHtml( FileEmbed $embed, File $file ): string {
+	private function thumbnailFrameHtml( FileEmbed $embed, $file ): string {
 		return Linker::makeThumbLink2(
 			$this->fileTitle( $embed ),
 			$file,
@@ -163,7 +167,16 @@ private function thumbnailOptions( FileEmbed $embed ): array {
 		return $options;
 	}
 
+	/**
+	 * A `thumb` on a missing file frames a broken-thumb box that keeps the caption
+	 * visible, as wikitext does; without it, the embed is a bare upload red link
+	 * labelled with the alt text, and the caption would be silently dropped.
+	 */
 	private function missingFileHtml( FileEmbed $embed ): string {
+		if ( $embed->thumbnail ) {
+			return $this->thumbnailFrameHtml( $embed, false );
+		}
+
 		return $this->wrap(
 			Linker::makeBrokenImageLinkObj(
 				$this->fileTitle( $embed ),
diff --git a/tests/phpunit/Persistence/MediaWikiFileEmbedRendererTest.php b/tests/phpunit/Persistence/MediaWikiFileEmbedRendererTest.php
index b090d49..bbe3c78 100644
--- a/tests/phpunit/Persistence/MediaWikiFileEmbedRendererTest.php
+++ b/tests/phpunit/Persistence/MediaWikiFileEmbedRendererTest.php
@@ -97,6 +97,28 @@ public function testThumbnailUsesExplicitAltTextForImageWhileShowingCaption(): v
 		$this->assertStringContainsString( '<figcaption>Quarterly revenue</figcaption>', $html );
 	}
 
+	public function testMissingThumbnailRendersFramedBoxWithCaptionAndUploadLink(): void {
+		$html = $this->renderMissingFile( thumbnail: true, caption: 'Quarterly revenue' );
+
+		$this->assertStringContainsString( 'typeof="mw:Error mw:File/Thumb"', $html );
+		$this->assertStringContainsString( '<figcaption>Quarterly revenue</figcaption>', $html );
+		$this->assertStringContainsString( 'Special:Upload', $html );
+	}
+
+	public function testMissingThumbnailCaptionIsHtmlEscaped(): void {
+		$html = $this->renderMissingFile( thumbnail: true, caption: '<script>alert(1)</script>' );
+
+		$this->assertStringNotContainsString( '<script>', $html );
+		$this->assertStringContainsString( '&lt;script&gt;', $html );
+	}
+
+	public function testMissingInlineFileStaysPlainBrokenLinkWithoutFrame(): void {
+		$html = $this->renderMissingFile( thumbnail: false, caption: 'Quarterly revenue' );
+
+		$this->assertStringNotContainsString( '<figure', $html );
+		$this->assertStringContainsString( 'Special:Upload', $html );
+	}
+
 	public function testPreloadedFileRendersWithoutPerEmbedLookup(): void {
 		$repoGroup = $this->createMock( RepoGroup::class );
 		$repoGroup->method( 'findFiles' )->willReturn( [ 'Chart.png' => $this->newFileRenderingThumbnails() ] );
@@ -169,6 +191,29 @@ private function renderThumbnail(
 		);
 	}
 
+	private function renderMissingFile(
+		bool $thumbnail,
+		?string $caption,
+		?string $altText = null
+	): string {
+		// The upload red link only appears where uploads are enabled; vanilla
+		// MediaWiki defaults them off, so pin it for a deterministic assertion.
+		$this->overrideConfigValue( MainConfigNames::EnableUploads, true );
+
+		$repoGroup = $this->createStub( RepoGroup::class );
+		$repoGroup->method( 'findFile' )->willReturn( false );
+
+		return $this->newRendererWithRepoGroup( $repoGroup )->renderEmbed(
+			new FileEmbed(
+				title: $this->chartTitle(),
+				width: null,
+				altText: $altText,
+				caption: $caption,
+				thumbnail: $thumbnail
+			)
+		);
+	}
+
 	private function newFileWithFailingTransform(): File {
 		$file = $this->newExistingInlineFile();
 		$file->method( 'transform' )->willReturn(

From 49a0dadbcedefded06c6255a1d1c11833c59be30 Mon Sep 17 00:00:00 2001
From: Jeroen De Dauw <jeroendedauw@proton.me>
Date: Fri, 17 Jul 2026 01:17:47 +0200
Subject: [PATCH 3/6] Load the media module when a thumbnail is embedded

For https://github.com/ProfessionalWiki/NativeMarkdown/issues/15

Core's Linker::makeThumbLink2() registers mediawiki.page.media -- which powers a
thumbnail's magnify affordance -- only when passed a Parser, and the
ContentHandler render path has none, so the module was never loaded.

The FileEmbedRenderer port now exposes the module(s) a rendered thumbnail needs,
and the renderer adds them to the RenderedMarkdown modules whenever the document
embeds a thumbnail, mirroring how the code highlighter's modules are added only
for highlighted blocks. Metadata-only parses, which render no HTML, add nothing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/Application/FileEmbedRenderer.php         | 10 +++++++
 src/Application/MarkdownRenderer.php          | 22 ++++++++++++++-
 .../MediaWikiFileEmbedRenderer.php            |  8 ++++++
 .../Application/MarkdownRendererTest.php      | 27 +++++++++++++++++++
 .../TestDoubles/FakeFileEmbedRenderer.php     |  4 +++
 5 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/src/Application/FileEmbedRenderer.php b/src/Application/FileEmbedRenderer.php
index 903810d..71ec873 100644
--- a/src/Application/FileEmbedRenderer.php
+++ b/src/Application/FileEmbedRenderer.php
@@ -23,4 +23,14 @@ public function preloadFiles( array $titles ): void;
 	 */
 	public function renderEmbed( FileEmbed $embed ): string;
 
+	/**
+	 * ResourceLoader modules a rendered thumbnail needs to be interactive (its
+	 * magnify affordance). The caller adds them only when it actually embedded a
+	 * thumbnail, mirroring how a code highlighter's modules are added only for
+	 * highlighted blocks.
+	 *
+	 * @return string[]
+	 */
+	public function modules(): array;
+
 }
diff --git a/src/Application/MarkdownRenderer.php b/src/Application/MarkdownRenderer.php
index 77712c1..582350e 100644
--- a/src/Application/MarkdownRenderer.php
+++ b/src/Application/MarkdownRenderer.php
@@ -228,6 +228,10 @@ private function renderDocument(
 		// and skipping it avoids the highlighter's cost when the HTML is discarded.
 		$highlighted = $generateHtml && $this->highlightCodeBlocks( $document );
 
+		// Likewise HTML-only: a thumbnail's client-side module matters only once the
+		// thumbnail is actually rendered, which a metadata-only parse never does.
+		$rendersThumbnail = $generateHtml && $this->hasThumbnailEmbed( $files );
+
 		return new RenderedMarkdown(
 			html: $generateHtml ? $this->renderHtml( $document, $sections ) : '',
 			links: $links,
@@ -236,7 +240,10 @@ private function renderDocument(
 			sections: $sections,
 			externalLinks: $this->collectExternalLinks( $document ),
 			frontMatter: $frontMatter,
-			modules: $highlighted ? $this->codeHighlighter->modules() : [],
+			modules: array_merge(
+				$highlighted ? $this->codeHighlighter->modules() : [],
+				$rendersThumbnail ? $this->fileEmbedRenderer->modules() : []
+			),
 			styleModules: $highlighted ? $this->codeHighlighter->styleModules() : []
 		);
 	}
@@ -279,6 +286,19 @@ private function highlightCodeBlocks( Document $document ): bool {
 		return $anyHighlighted;
 	}
 
+	/**
+	 * @param FileEmbed[] $files
+	 */
+	private function hasThumbnailEmbed( array $files ): bool {
+		foreach ( $files as $embed ) {
+			if ( $embed->thumbnail ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
 	/**
 	 * Replaces the raw wikitext of each template call with the expander's HTML,
 	 * up to MAX_TEMPLATE_EXPANSIONS_PER_RENDER calls. Unbalanced block calls, and
diff --git a/src/Persistence/MediaWikiFileEmbedRenderer.php b/src/Persistence/MediaWikiFileEmbedRenderer.php
index 1bd9fc4..ed31117 100644
--- a/src/Persistence/MediaWikiFileEmbedRenderer.php
+++ b/src/Persistence/MediaWikiFileEmbedRenderer.php
@@ -47,6 +47,14 @@ public function preloadFiles( array $titles ): void {
 		}
 	}
 
+	/**
+	 * Core's Linker registers this for a thumbnail only when passed a Parser, which
+	 * the ContentHandler render path has none of, so the caller adds it instead.
+	 */
+	public function modules(): array {
+		return [ 'mediawiki.page.media' ];
+	}
+
 	public function renderEmbed( FileEmbed $embed ): string {
 		$file = $this->findFile( $embed->title->dbKey );
 
diff --git a/tests/phpunit/Application/MarkdownRendererTest.php b/tests/phpunit/Application/MarkdownRendererTest.php
index 6f154c7..fa279c8 100644
--- a/tests/phpunit/Application/MarkdownRendererTest.php
+++ b/tests/phpunit/Application/MarkdownRendererTest.php
@@ -1410,6 +1410,33 @@ public function testNoModulesWhenEveryBlockDeclinesHighlighting(): void {
 		$this->assertSame( [], $result->styleModules );
 	}
 
+	public function testEmbeddedThumbnailReportsTheFileRenderersMediaModules(): void {
+		$result = $this->render( '[[File:Cat.png|thumb]]' );
+
+		$this->assertSame( [ 'test.file.media' ], $result->modules );
+	}
+
+	public function testInlineEmbedReportsNoMediaModules(): void {
+		$result = $this->render( '[[File:Cat.png]]' );
+
+		$this->assertSame( [], $result->modules );
+	}
+
+	public function testMetadataOnlyRenderReportsNoMediaModules(): void {
+		$result = $this->render( '[[File:Cat.png|thumb]]', generateHtml: false );
+
+		$this->assertSame( [], $result->modules );
+	}
+
+	public function testThumbnailAndHighlightedCodeReportBothModuleSets(): void {
+		$result = $this->render(
+			"[[File:Cat.png|thumb]]\n\n```python\nx\n```",
+			codeHighlighter: new FakeCodeHighlighter( modules: [ 'ext.demo.view' ] )
+		);
+
+		$this->assertSame( [ 'ext.demo.view', 'test.file.media' ], $result->modules );
+	}
+
 	/**
 	 * A stack of distinct fenced blocks ```lang1 .. ```lang$count, each with a
 	 * one-word language so every block is a highlight candidate.
diff --git a/tests/phpunit/TestDoubles/FakeFileEmbedRenderer.php b/tests/phpunit/TestDoubles/FakeFileEmbedRenderer.php
index 0c89f86..c173f30 100644
--- a/tests/phpunit/TestDoubles/FakeFileEmbedRenderer.php
+++ b/tests/phpunit/TestDoubles/FakeFileEmbedRenderer.php
@@ -28,4 +28,8 @@ public function renderEmbed( FileEmbed $embed ): string {
 			. '>';
 	}
 
+	public function modules(): array {
+		return [ 'test.file.media' ];
+	}
+
 }

From 7873809f2d30140aa95a122b04c936110f0b6ba5 Mon Sep 17 00:00:00 2001
From: Jeroen De Dauw <jeroendedauw@proton.me>
Date: Fri, 17 Jul 2026 01:17:58 +0200
Subject: [PATCH 4/6] Note the thumbnail embed fixes in the 1.2.0 release notes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/README.md b/README.md
index 823e550..660a31c 100644
--- a/README.md
+++ b/README.md
@@ -228,6 +228,12 @@ php tests/phpunit/phpunit.php extensions/NativeMarkdown/tests/phpunit/
   installed; without it, code blocks keep rendering as plain preformatted text
 * Code blocks no longer get a background pill behind each of their lines, which happened because skins style the
   `code` element for inline use and CommonMark nests it inside `pre`
+* A `thumb` file embed alone on its line now renders as a standalone framed thumbnail rather than being wrapped
+  in a paragraph, which produced invalid HTML5 and a stray empty paragraph
+* A `thumb` embed of a missing file now renders the framed box with its caption and an upload link, the way
+  wikitext does, instead of a bare upload link that silently dropped the caption
+* Thumbnail embeds now load the same media module MediaWiki loads for wikitext thumbnails, so their magnify
+  affordance works
 
 ### Version 1.1.0 - 2026-07-09
 

From 0ab76f083c0c09f0ce82c66c035b7cbaafc9db19 Mon Sep 17 00:00:00 2001
From: Jeroen De Dauw <jeroendedauw@proton.me>
Date: Fri, 17 Jul 2026 01:28:39 +0200
Subject: [PATCH 5/6] Cover the two-embed paragraph case in the promotion tests

For https://github.com/ProfessionalWiki/NativeMarkdown/issues/15

Promotion leaves a paragraph wrapped once it holds a second embed, but no test
exercised that guard, so a mutation dropping it survived. Add a case with two
thumbnail embeds in one paragraph asserting both stay wrapped, since promotion
handles only the solitary case.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tests/phpunit/Application/MarkdownRendererTest.php | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/phpunit/Application/MarkdownRendererTest.php b/tests/phpunit/Application/MarkdownRendererTest.php
index fa279c8..8b36608 100644
--- a/tests/phpunit/Application/MarkdownRendererTest.php
+++ b/tests/phpunit/Application/MarkdownRendererTest.php
@@ -563,6 +563,14 @@ public function testThumbnailEmbedWithSurroundingTextStaysInParagraph(): void {
 		$this->assertStringContainsString( '<p>Look: <img data-fake-file="Cat.png"', $html );
 	}
 
+	public function testParagraphWithTwoThumbnailEmbedsKeepsBothWrapped(): void {
+		$html = $this->render( "[[File:Cat.png|thumb|First]]\n[[File:Dog.png|thumb|Second]]" )->html;
+
+		$this->assertStringContainsString( '<p>', $html );
+		$this->assertStringContainsString( 'data-fake-file="Cat.png"', $html );
+		$this->assertStringContainsString( 'data-fake-file="Dog.png"', $html );
+	}
+
 	public function testColonPrefixedFileRendersPageLinkInsteadOfEmbedding(): void {
 		$result = $this->render( '[[:File:Cat.png]]' );
 

From d70c5a405db4a915b18e0d8430f10859f57cff58 Mon Sep 17 00:00:00 2001
From: Jeroen De Dauw <jeroendedauw@proton.me>
Date: Fri, 17 Jul 2026 01:44:33 +0200
Subject: [PATCH 6/6] Correct the promotion docblock's rationale for
 non-solitary thumbnails

The docblock claimed a thumbnail sharing its paragraph with other content is left
wrapped "since they render inline there". That holds for a plain inline image but
not for a thumbnail, whose block-level <figure> stays invalid inside the <p>. It
is left wrapped because this fix handles only the solitary case, so say that.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/Application/MarkdownRenderer.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/Application/MarkdownRenderer.php b/src/Application/MarkdownRenderer.php
index 582350e..8ce12c0 100644
--- a/src/Application/MarkdownRenderer.php
+++ b/src/Application/MarkdownRenderer.php
@@ -472,9 +472,9 @@ private function renderHtml( Document $document, array $sections ): string {
 	 * browsers auto-close the paragraph, shipping invalid HTML5 with a stray empty
 	 * `<p>` behind it. When such an embed is a paragraph's only content, replace the
 	 * paragraph with the embed so its `<figure>` becomes a sibling of the
-	 * surrounding blocks, the way wikitext emits a standalone thumbnail. Embeds that
-	 * share their paragraph with other content are left wrapped, since they render
-	 * inline there.
+	 * surrounding blocks, the way wikitext emits a standalone thumbnail. Only the
+	 * solitary case is handled: a thumbnail that shares its paragraph with text or a
+	 * second embed is left wrapped, outside this fix's scope.
 	 */
 	private function promoteSolitaryThumbnailEmbeds( Document $document ): void {
 		foreach ( $this->nodesOfType( $document, Paragraph::class ) as $paragraph ) {