---

5K大画面でMermaid図解が巨大化する2つの原因

AstroのShiki分割と横幅100%強制の罠

まず Astro（Astro 5 / 6 系）で Mermaid を動かす際の最初の関門として、標準のコードハイライターである Shiki がコードブロック内の文字列を色分け用の <span> タグに細かく分解してしまうため、Mermaid 標準の自動初期化（startOnLoad: true）だけでは構文エラーになって描画されません。

そのため、pre[data-language="mermaid"] から純粋なテキスト（graph.textContent）だけを抜き出し、手動で mermaid.render(id, content) を呼んで SVG に置き換えるスクリプトを組むのが定石です。

ところが、描画された SVG に対して「画面からはみ出さないようにしよう」と単純に width: 100% !important; height: auto; を指定すると、広大なモニターで悲劇が起きます。

• 画面を広く使うレイアウトで記事エリアの幅が 2,000px 以上あるとき、本来は横 450px でちょうど綺麗に読める縦長フローチャートまで 横 2,400px（約 5 倍）へ強制拡大 されます。
• アスペクト比（縦横比）が保たれたまま横に 5 倍伸びるため、縦方向も 5 倍になり、7 段のフロー図がなんと 縦 6,060px（画面 4 枚分以上！） という超巨大サイズに化けてしまったのです。

机上の計算を裏切る4画面サイズ実機撮影の衝撃

そこで最初は計算式だけでスケーリングを入れてみたのですが、「本当にすべての端末で綺麗に見えているか？」を確かめるため、Playwright MCP を使ってサイト内の 全 37 個の図解を 4 つの画面サイズ（スマホ 375×812・iPad 768×1024・フル HD 1920×1080・5K iMac 2560×1440）で実際に開いて総点検 しました。

すると、机上の計算だけでは絶対に気づけなかった「実物の崩れ」がボロボロ見つかったのです！

1. 円グラフ（pie チャート）の謎の巨大余白 : Mermaid が生成する円グラフの viewBox 横幅が、実際の円と凡例の描画幅より何百ピクセルも広く取られており、そのせいで円本体が不自然に小さく縮んでいました。
2. スマホでの gantt（工程表）や横長 LR 図の文字潰れ : 横幅 1,500px ある横長の図をスマホ幅 340px にそのまま縮小すると、文字が 3px 以下の米粒になって判読不能になっていました。
3. サブグラフ見出しと矢印の貫通・引用符漏れ : 日本語記号を含む subgraph "見出し（補足）" でダブルクォートを忘れた構文エラーや、横並び要素が多すぎて線が文字を貫通している箇所がありました。

---

解像度と図形サイズに応じる動的スケーリング実装

getBBox余白除去と3つの上限値による最適化

この 4 画面実機テストの結果を踏まえ、レイアウト側の自動調整関数（fitMermaidSvg）を次の 4 段階アルゴリズム へ進化させました。

// Astroレイアウト内の is:inline スクリプトで動かす解像度適応型スケーリング関数
const fitMermaidSvg = (svgElement) => {
  if (!svgElement) return;
  const vw = window.innerWidth || document.documentElement.clientWidth || 1200;
  const vh = window.innerHeight || document.documentElement.clientHeight || 800;
  const isMobile = vw <= 768;

  let vbWidth = 0;
  let vbHeight = 0;
  try {
    const bbox = svgElement.getBBox();
    if (bbox && bbox.width > 10 && bbox.height > 10) {
      const origVb = svgElement.getAttribute('data-orig-viewbox') || svgElement.getAttribute('viewBox') || '';
      if (!svgElement.getAttribute('data-orig-viewbox') && origVb) {
        svgElement.setAttribute('data-orig-viewbox', origVb);
      }
      const parts = origVb.trim().split(/[\s,]+/).map(Number);
      // 円グラフ等で元のviewBoxが実描画幅より80px以上広い場合は余白を自動トリミング
      if (parts.length === 4 && parts[2] > bbox.width + 80) {
        const padLeft = 24, padRight = 64, padY = 20;
        vbWidth = Math.ceil(bbox.width + padLeft + padRight);
        vbHeight = Math.ceil(bbox.height + padY * 2);
        svgElement.setAttribute('viewBox', `${Math.floor(bbox.x - padLeft)} ${Math.floor(bbox.y - padY)} ${vbWidth} ${vbHeight}`);
      }
    }
  } catch (e) {}

  if (vbWidth <= 0 || vbHeight <= 0) {
    const parts = (svgElement.getAttribute('viewBox') || '').trim().split(/[\s,]+/).map(Number);
    if (parts.length === 4 && parts[2] > 0 && parts[3] > 0) {
      vbWidth = parts[2];
      vbHeight = parts[3];
    }
  }

  svgElement.removeAttribute('height');
  svgElement.style.display = 'block';
  svgElement.style.margin = '0 auto';
  svgElement.style.height = 'auto';

  if (isMobile) {
    const availW = Math.max(vw - 38, 280);
    svgElement.style.width = '100%';
    svgElement.style.maxWidth = vbWidth > 0 ? Math.min(availW, Math.round(vbWidth * 1.1)) + 'px' : '100%';
    return;
  }

  const naturalLimit = vbWidth > 0 ? vbWidth * 1.08 : 960;
  const screenWidthLimit = Math.min(vw * 0.82, 1160);
  let heightBasedLimit = 1160;
  if (vbWidth > 0 && vbHeight > 0) {
    const maxAllowedHeight = Math.max(vh * 0.75, 460);
    const rawHeightLimit = maxAllowedHeight * (vbWidth / vbHeight);
    const minReadableWidth = Math.min(vbWidth * 0.9, Math.max(vbWidth * 0.72, 440));
    heightBasedLimit = Math.max(rawHeightLimit, minReadableWidth);
  }

  const optimalMaxWidth = Math.round(Math.min(naturalLimit, screenWidthLimit, heightBasedLimit));
  svgElement.style.width = '100%';
  svgElement.style.maxWidth = optimalMaxWidth + 'px';
};

あわせて原稿側の図解も、スマホで崩れる gantt を廃止して縦方向のフロー図（flowchart TD）や Markdown テーブルへ組み直しました。

5K画面とスマホで実測した劇的な改善データ

27 インチ 5K iMac（2560×1440）上で計測した改修前後の実寸比較がこちらです。

図解のタイプ	改修前（width: 100% 強制）	改修後（fitMermaidSvg 適用）	視覚的な変化
標準の縦フロー図	横 2,400px × 縦 2,850px	横 557px × 縦 661px	本文の文字サイズと綺麗に揃い、中央に品よく収まる。
縦7段の長大フロー図	横 2,400px × 縦 6,060px	横 410px × 縦 1,035px	画面4枚分だった図が、スクロールなしで1画面に見渡せる。
横広のシーケンス図	横 2,400px × 縦 1,170px	横 1,080px × 縦 528px	首を左右に振らずに一目で追える最適サイズに収束。

---

Playwright縦長スクショの0バイト画像クラッシュ

WebP規格の最大16,383pxという14ビットの壁

そして、この実機検証の過程でもう 1 つ発見した AI 開発者必見の重大トラップ が、Playwright MCP のスクリーンショット機能による 「0 バイト画像クラッシュ」 です。

写真が 30〜60 枚入った長編レビュー記事など、ページ全体の縦の長さ（document.documentElement.scrollHeight）が非常に長いページに対して、Playwright MCP の browser_take_screenshot ツールを fullPage: true かつ type: "webp" で呼び出すと、突然 AI エージェントが Agent execution terminated due to error を出して停止し、何度リトライボタンを押しても二度とそのチャットが動かせなくなる事故が起きました。

原因を追跡すると、WebP 画像フォーマットの国際規格そのものにある「14 ビット最大ピクセル寸法上限（縦・横ともに最大 16,383px まで）」 に行き着きました！

• WebP のヘッダー仕様では、画像の幅と高さ（マイナス 1）をそれぞれ 14 ビット整数（$2^{14} = 16,384 \rightarrow$ 最大 16,383px、Retina 2 倍解像度なら論理高さ約 8,191px 相当で到達する場合も）で格納します。
• そのため、高さ 16,383px を超える縦長ページを fullPage: true, type: "webp" で撮影すると、ブラウザ内部の WebP エンコーダが変換に失敗して 中身が 0 バイト（空っぽ）の壊れた .webp ファイル を吐き出します。
• その 0 バイト 画像がそのまま AI チャットの会話履歴（マルチモーダル入力）に添付されるため、以降の全ターンで API 側が「不正な空メディアデータ」としてリクエストを拒否し、会話ごと復帰不能になっていたのです！

会話を壊さないPNG指定とDOM計測の鉄則

AI エージェントに Playwright MCP で画面確認をさせる際は、ルールファイル（GEMINI.md 等）に次の 3 原則を明記しておくだけで、このクラッシュは永久にゼロになります。

---

まとめ：大画面からスマホまで実物を見て仕上げる

「手元のノート PC 画面で綺麗に見えたからヨシ！」と思って公開していても、27 インチ 5K モニターやスマホの縦画面で開くと、図解が怪物のように膨張していたり豆粒に潰れていたりすることは珍しくありません。

1. Mermaid 図解は width: 100% で放置せず、getBBox() 余白トリミング＋自然幅・画面幅・画面高さ（75vh）の 3 上限で動的スケーリングする
2. スマホで文字が重なる gantt や極端な横長図は、縦フロー（TD）や Markdown テーブルへ潔く組み替える
3. Playwright での自動検証時は WebP の 16,383px 上限を忘れず、type: "png", fullPage: false ＋ DOM 計測で安全確実にチェックする

図解のサイズがピタッと画面に調和すると、記事全体の品格と読みやすさが一気に跳ね上がります。ぜひご自身のサイトの図解も大画面とスマホの両方で見比べてみてください！