nejimakibird_model-weave/docs/V0.8-rendering-policy.md

V0.8 Rendering Policy

Purpose

This document describes the current Model Weave rendering policy.

Markdown model files remain the source of truth. Custom previews, Mermaid diagrams, SVG, and PNG exports are derived views generated from parsed Model Weave models.

Render Mode Policy

auto is no longer a user-facing default render mode.

Supported render modes depend on the file format:

format	supported render modes
class	custom, mermaid, mermaid-detail
class_diagram	custom, mermaid, mermaid-detail
er_entity	custom, mermaid, mermaid-detail
er_diagram	custom, mermaid, mermaid-detail
dfd_diagram	mermaid
screen	custom
app_process	custom
other table/detail formats	custom or table/detail view as implemented

Missing frontmatter.render_mode uses the format-specific default render mode from settings.

If frontmatter.render_mode is present and supported for the file format, it has highest priority for that file's initial renderer.

If frontmatter.render_mode is unsupported, deprecated, or unknown, Model Weave should show a warning and fall back to the format-specific default render mode from settings.

Renderer Resolution

Initial renderer resolution for a file:

1. Supported frontmatter.render_mode
2. Format-specific default render mode from settings
3. Built-in format fallback

Toolbar renderer selection is temporary for the current view only.

Toolbar selection:

• does not write back to frontmatter
• does not change plugin settings
• should not determine the initial renderer for other files
• is cleared when another file becomes the active render target

Mermaid Detail

Mermaid Detail is available only for supported Class and ER views:

• class
• class_diagram
• er_entity
• er_diagram

Unsupported formats should not expose Mermaid Detail.

DFD remains Mermaid-only. Screen and app_process currently use their custom preview paths.

Mermaid Source And Debug Panels

Mermaid Source is user-facing generated output. For Mermaid-based views with generated Mermaid source, it should be available as a collapsed panel and show a fenced Mermaid code block suitable for copying into an Obsidian Markdown note.

Mermaid Render Debug is a troubleshooting aid. It is controlled by the Show Mermaid Render Debug setting and is hidden by default.

When the setting is enabled, Mermaid Render Debug should appear consistently for Mermaid renderers and remain collapsed by default.

Custom-only renderers should not show Mermaid Source or Mermaid Render Debug unless they actually generate Mermaid source.

Renderer Responsibilities

Custom renderers are for detailed review:

• row and field review
• diagnostics
• navigation-oriented views
• Screen preview
• Class and ER detailed custom views

Mermaid renderers are for generated diagram views:

• overview diagrams
• relationship overview
• DFD flow layout
• app_process Business Flow layout
• export-friendly graph views

Renderer selection does not change the Markdown model format.

Viewer Interaction Policy

Starting with 0.1.16, Model Weave requires Obsidian 1.8.7 or later.

Resolved nodes and boxes in supported Model Weave views can show hover previews and can be clicked to open their source Markdown. Unresolved nodes, labels, edges, and field rows may not be interactive.

Hover previews rely on Obsidian's hover-link / Page Preview behavior. They may not appear near the top edge of the Obsidian window or while using Model Weave Focus mode. Click navigation is the reliable fallback for resolved nodes.

Export Policy

PNG export should export the diagram body, not toolbar controls, diagnostics, lower-pane details, Mermaid Source, or Mermaid Render Debug panels.

For Mermaid diagrams, exported PNGs should use the generated Mermaid-rendered diagram body.

Diagnostics Policy

Unknown, deprecated, or unsupported render_mode values should produce a warning and fall back safely.

Mermaid generation or rendering failure should not crash the viewer. The preview should show a safe fallback message and diagnostics where available.

Diagnostic severity should remain consistent:

• Error: the model cannot be resolved or rendered correctly
• Warning: the model is likely inconsistent, deprecated, unsupported, or risky
• Note: useful information or non-blocking fallback behavior