Issue Summary

When a Confluence page containing Forge inline macros (xen:macro) is loaded via direct URL, new tab, or browser refresh, the macros briefly display a "Broken macro" error image before correctly loading ~1 second later. 

Steps to Reproduce

  # Install a Forge app with a xen:macro inline extension.

1. Insert the macro into a Confluence page and publish it, you'll need it in multiple lines.
2. Load the page via direct URL, new tab, or browser refresh

Expected Results

The Macro loads correctly, with no Broken Macros displayed.

Actual Results

The macro briefly renders as "Broken macro" for ~1 second before loading correctly
 
 
Root Cause: The broken macro flash is caused by server-side rendering (SSR) returning a broken macro placeholder image before client-side hydration completes. Specifically:

Pre-hydration, the very first render of the page already contains the broken macro image (/wiki/plugins/servlet/confluence/placeholder/error?i18nKey=editor.placeholder.broken.macro&locale=en_US&version=2)
This is server-side rendered markup, not a client-side rendering failure
After client-side hydration completes, the correct macro content is rendered, replacing the SSR broken macro placeholder
Appending NO_SSR=1 to the page address, the flash does not occur, confirming the issue is on the SSR path
After hydration, SPA navigations no longer reproduce the flash
 
Additional context:
This also affects Word exports and Scroll PDF exports (macro permanently broken in exported document), likely the same SSR/server-side rendering pipeline
It doesn't seem to affect native Confluence PDF export

Workaround

Currently there is no known workaround for this behavior. A workaround will be added here when available