fix(tui): show Mermaid source without image support

Author: 1jehuang

crates/jcode-tui-markdown/src/lib.rs

@@ -150,6 +150,12 @@ pub use jcode_render_core::reasoning_summary_line_markup;
 use render_support::{
     highlight_code_cached, line_plain_text, placeholder_code_block, ranges_overlap, render_table,
 };
+
+fn should_render_mermaid_block(lang: Option<&str>) -> bool {
+    mermaid_rendering_enabled()
+        && lang.map(mermaid::is_mermaid_lang).unwrap_or(false)
+        && mermaid::native_image_protocol_available()
+}
 pub use render_support::{highlight_file_lines, highlight_line, render_table_with_width};
 
 // Syntax highlighting resources (loaded once)

crates/jcode-tui-markdown/src/markdown_latex_image.rs

@@ -508,6 +508,7 @@ mod tests {
         assert_ne!(cache_key("x", false, 240), cache_key("x", false, 312));
     }
 
+    #[cfg(feature = "mermaid-renderer")]
     #[test]
     fn image_placeholder_extracts_math_copy_target_with_source_delimiters() {
         let hash = 0x1a7e_c0de_u64;

crates/jcode-tui-markdown/src/markdown_mermaid_fallback.rs

@@ -20,6 +20,15 @@ pub fn image_protocol_available() -> bool {
     false
 }
 
+pub fn native_image_protocol_available() -> bool {
+    false
+}
+
+#[cfg(test)]
+pub fn with_image_protocol_override<T>(_enabled: Option<bool>, f: impl FnOnce() -> T) -> T {
+    f()
+}
+
 pub fn get_font_size() -> Option<(u16, u16)> {
     None
 }

crates/jcode-tui-markdown/src/markdown_render_full.rs

@@ -408,26 +408,13 @@ pub fn render_markdown_with_width(text: &str, max_width: Option<usize>) -> Vec<L
             }
             Event::End(TagEnd::CodeBlock) => {
                 // Check if this is a mermaid diagram
-                let is_mermaid = mermaid_rendering_enabled()
-                    && code_block_lang
-                        .as_ref()
-                        .map(|l| mermaid::is_mermaid_lang(l))
-                        .unwrap_or(false);
+                let is_mermaid = should_render_mermaid_block(code_block_lang.as_deref());
 
                 if is_mermaid {
                     dbg_mermaid_blocks += 1;
                     // Render mermaid diagram.
                     // In streaming mode this updates only the ephemeral preview entry.
                     let terminal_width = max_width.and_then(|w| u16::try_from(w).ok());
-                    if !streaming_mode
-                        && !mermaid_should_register_active()
-                        && !mermaid::image_protocol_available()
-                    {
-                        lines.push(mermaid_sidebar_placeholder(
-                            "↗ mermaid diagram (image protocols unavailable)",
-                        ));
-                        continue;
-                    }
                     let result = if streaming_mode {
                         mermaid::render_mermaid_deferred_with_stream_scope(
                             &code_block_content,
@@ -982,10 +969,7 @@ pub fn render_markdown_with_width(text: &str, max_width: Option<usize>) -> Vec<L
     // Handle incomplete code block (streaming case)
     // If we're still inside a code block, render what we have so far
     if in_code_block && !code_block_content.is_empty() {
-        let is_mermaid = code_block_lang
-            .as_ref()
-            .map(|l| mermaid::is_mermaid_lang(l))
-            .unwrap_or(false);
+        let is_mermaid = should_render_mermaid_block(code_block_lang.as_deref());
 
         if is_mermaid {
             // For mermaid, show "rendering..." placeholder while streaming

crates/jcode-tui-markdown/src/markdown_render_lazy.rs

@@ -371,19 +371,9 @@ pub fn render_markdown_lazy(
                 code_block_content.clear();
             }
             Event::End(TagEnd::CodeBlock) => {
-                let is_mermaid = mermaid_rendering_enabled()
-                    && code_block_lang
-                        .as_ref()
-                        .map(|l| mermaid::is_mermaid_lang(l))
-                        .unwrap_or(false);
+                let is_mermaid = should_render_mermaid_block(code_block_lang.as_deref());
 
                 if is_mermaid {
-                    if !mermaid_should_register_active() && !mermaid::image_protocol_available() {
-                        lines.push(mermaid_sidebar_placeholder(
-                            "↗ mermaid diagram (image protocols unavailable)",
-                        ));
-                        continue;
-                    }
                     let terminal_width = max_width.and_then(|w| u16::try_from(w).ok());
                     let result = if deferred_mermaid_mode {
                         mermaid::render_mermaid_deferred_with_registration(

crates/jcode-tui-markdown/src/markdown_tests/cases/rendering.rs

@@ -293,10 +293,12 @@ fn test_table_cjk_alignment() {
 
 #[test]
 fn test_mermaid_block_detection() {
-    // Mermaid rendering is temporarily disabled by default, so Mermaid fences
-    // should safely fall back to normal code blocks unless explicitly opted in.
+    // Without a native image protocol, Mermaid fences stay useful as readable
+    // source code instead of becoming a half-block image or a text stub.
     let md = "```mermaid\nflowchart LR\n    A --> B\n```";
-    let lines = render_markdown(md);
+    let lines = with_mermaid_rendering_override(Some(true), || {
+        mermaid::with_image_protocol_override(Some(false), || render_markdown(md))
+    });
     let text: String = lines
         .iter()
         .flat_map(|l| l.spans.iter().map(|s| s.content.as_ref()))
@@ -310,6 +312,64 @@ fn test_mermaid_block_detection() {
         text.contains("flowchart LR"),
         "Expected raw Mermaid source: {text}"
     );
+    assert!(
+        lines.iter().all(|line| {
+            mermaid::parse_image_placeholder(line).is_none()
+                && mermaid::parse_inline_image_placeholder(line).is_none()
+        }),
+        "Unsupported terminals must not receive a Mermaid image placeholder: {text}"
+    );
+}
+
+#[cfg(feature = "mermaid-renderer")]
+#[test]
+fn lazy_mermaid_without_native_protocol_also_renders_source() {
+    let md = "```mermaid\nflowchart TD\n    Start --> Finish\n```";
+    let lines = with_mermaid_rendering_override(Some(true), || {
+        mermaid::with_image_protocol_override(Some(false), || {
+            render_markdown_lazy(md, Some(80), 0..usize::MAX)
+        })
+    });
+    let text = lines_to_string(&lines);
+
+    assert!(text.contains("┌─ mermaid"), "missing source header: {text}");
+    assert!(text.contains("Start --> Finish"), "missing source: {text}");
+    assert!(lines.iter().all(|line| {
+        mermaid::parse_image_placeholder(line).is_none()
+            && mermaid::parse_inline_image_placeholder(line).is_none()
+    }));
+}
+
+#[test]
+fn streaming_mermaid_without_native_protocol_keeps_source_visible() {
+    let md = "```mermaid\nflowchart TD\n    Stream --> Source\n```";
+    let lines = with_mermaid_rendering_override(Some(true), || {
+        mermaid::with_image_protocol_override(Some(false), || {
+            with_streaming_render_context(|| render_markdown_with_width(md, Some(80)))
+        })
+    });
+    let text = lines_to_string(&lines);
+
+    assert!(text.contains("┌─ mermaid"), "missing source header: {text}");
+    assert!(text.contains("Stream --> Source"), "missing source: {text}");
+    assert!(!text.contains("rendering mermaid diagram"), "{text}");
+    assert!(lines.iter().all(|line| {
+        mermaid::parse_image_placeholder(line).is_none()
+            && mermaid::parse_inline_image_placeholder(line).is_none()
+    }));
+}
+
+#[cfg(feature = "mermaid-renderer")]
+#[test]
+fn mermaid_gate_accepts_native_protocol_and_rejects_halfblock_fallback() {
+    with_mermaid_rendering_override(Some(true), || {
+        mermaid::with_image_protocol_override(Some(false), || {
+            assert!(!should_render_mermaid_block(Some("mermaid")));
+        });
+        mermaid::with_image_protocol_override(Some(true), || {
+            assert!(should_render_mermaid_block(Some("mermaid")));
+        });
+    });
 }
 
 #[test]

crates/jcode-tui-markdown/src/markdown_tests/cases/streaming_cache.rs

@@ -341,7 +341,8 @@ fn test_incremental_renderer_defers_mermaid_render_until_background_ready() {
 
     let mut renderer = IncrementalMarkdownRenderer::new(Some(80));
     let text = "Plan:\n\n```mermaid\nflowchart LR\n  A[Start] --> B[End]\n```\n";
-    let lines = renderer.update(text);
+    let lines =
+        jcode_tui_mermaid::with_image_protocol_override(Some(true), || renderer.update(text));
     let rendered = lines_to_string(&lines);
 
     assert!(
@@ -395,7 +396,8 @@ fn test_incremental_renderer_rerenders_pending_mermaid_after_epoch_bump() {
     // Unique content so no earlier test populated the render cache for it.
     let text = "Plan:\n\n```mermaid\nflowchart LR\n  E1[EpochBump] --> E2[FastPath]\n```\n";
 
-    let lines = renderer.update(text);
+    let lines =
+        jcode_tui_mermaid::with_image_protocol_override(Some(true), || renderer.update(text));
     if !lines.iter().any(line_is_mermaid_pending_placeholder) {
         // Cache already warm (render finished before this update); nothing to pin.
         return;
@@ -407,7 +409,7 @@ fn test_incremental_renderer_rerenders_pending_mermaid_after_epoch_bump() {
     jcode_tui_mermaid::debug_bump_deferred_render_epoch_for_tests();
 
     let before = thread_render_count();
-    let _ = renderer.update(text);
+    let _ = jcode_tui_mermaid::with_image_protocol_override(Some(true), || renderer.update(text));
     assert!(
         thread_render_count() > before,
         "identical text with an advanced deferred epoch must re-render \

crates/jcode-tui-mermaid/src/lib.rs

@@ -252,8 +252,9 @@ pub use inline_image::{
 pub use runtime::force_test_kitty_picker;
 pub use runtime::{
     error_lines_for, get_cached_png, get_font_size, image_protocol_available, init_picker,
-    is_video_export_mode, protocol_type, register_external_image, register_inline_image,
-    set_video_export_mode, uses_text_image_fallback, with_image_protocol_override,
+    is_video_export_mode, native_image_protocol_available, protocol_type, register_external_image,
+    register_inline_image, set_video_export_mode, uses_text_image_fallback,
+    with_image_protocol_override,
 };
 pub use viewport_render::{
     InlineFitReadiness, inline_fit_readiness, invalidate_render_state, prewarm_inline_fit_state,

crates/jcode-tui-mermaid/src/mermaid_runtime.rs

@@ -361,6 +361,28 @@ pub fn image_protocol_available() -> bool {
     PICKER.get().and_then(|p| p.as_ref()).is_some() || VIDEO_EXPORT_MODE.load(Ordering::Relaxed)
 }
 
+fn protocol_supports_native_images(
+    protocol: Option<ProtocolType>,
+    video_export_mode: bool,
+) -> bool {
+    video_export_mode
+        || matches!(
+            protocol,
+            Some(ProtocolType::Kitty | ProtocolType::Iterm2 | ProtocolType::Sixel)
+        )
+}
+
+/// Whether Mermaid and other image-only content can use a real terminal image
+/// protocol. Unicode half-block rendering intentionally does not count: it is a
+/// useful raster fallback, but Mermaid source is more useful than a degraded
+/// diagram on terminals without Kitty, iTerm2, or Sixel support.
+pub fn native_image_protocol_available() -> bool {
+    if let Some(enabled) = IMAGE_PROTOCOL_OVERRIDE.with(|cell| cell.get()) {
+        return enabled;
+    }
+    protocol_supports_native_images(protocol_type(), VIDEO_EXPORT_MODE.load(Ordering::Relaxed))
+}
+
 fn protocol_uses_text_image_fallback(
     protocol: Option<ProtocolType>,
     video_export_mode: bool,
@@ -686,4 +708,36 @@ mod tests {
             true
         ));
     }
+
+    #[test]
+    fn native_image_capability_excludes_halfblocks_but_allows_video_export() {
+        assert!(protocol_supports_native_images(
+            Some(ProtocolType::Kitty),
+            false
+        ));
+        assert!(protocol_supports_native_images(
+            Some(ProtocolType::Iterm2),
+            false
+        ));
+        assert!(protocol_supports_native_images(
+            Some(ProtocolType::Sixel),
+            false
+        ));
+        assert!(!protocol_supports_native_images(
+            Some(ProtocolType::Halfblocks),
+            false
+        ));
+        assert!(!protocol_supports_native_images(None, false));
+        assert!(protocol_supports_native_images(None, true));
+    }
+
+    #[test]
+    fn native_image_capability_respects_scoped_test_override() {
+        with_image_protocol_override(Some(false), || {
+            assert!(!native_image_protocol_available());
+        });
+        with_image_protocol_override(Some(true), || {
+            assert!(native_image_protocol_available());
+        });
+    }
 }

crates/jcode-tui/src/tui/ui_pinned_tests.rs

@@ -601,7 +601,7 @@ fn render_side_panel_markdown_multiple_mermaids_create_ordered_placements() {
 }
 
 #[test]
-fn render_side_panel_markdown_without_protocol_falls_back_to_text_placeholder() {
+fn render_side_panel_markdown_without_native_protocol_shows_mermaid_source() {
     let page = sample_mermaid_page("```mermaid\nflowchart TD\n    A --> B\n```\n");
 
     // Pin protocol availability OFF for this thread: PICKER is a
@@ -631,8 +631,13 @@ fn render_side_panel_markdown_without_protocol_falls_back_to_text_placeholder()
         rendered.image_placements.len()
     );
     assert!(
-        text.iter().any(|line| line.contains("mermaid diagram")),
-        "expected textual placeholder when image protocols are unavailable: {:?}",
+        text.iter().any(|line| line.contains("┌─ mermaid")),
+        "expected a Mermaid source-code header without a native image protocol: {:?}",
+        text
+    );
+    assert!(
+        text.iter().any(|line| line.contains("flowchart TD")),
+        "expected readable Mermaid source without a native image protocol: {:?}",
         text
     );
 }