log

Blast Radius 点検ログ — 再生が速すぎる・半透明で触れない問題の調査と、恒久ツール化のアイデア

Blast Radius の「再生ボタンが速すぎる」は日数ベースで1フレーム1日進む実装が原因で、このサイトの14日分の履歴は約0.23秒で終わる。「半透明でクリックできない」は、Blast 表示の解除手段が Esc キーしかなくスマホでは抜けられないこと、その状態が URL に保存されて再読込後も続くこと、スマホの初期ズームが最小値でノードが5px の点になることの重なり。データ面では106本のリンクのうち89本が弱い relates-to で Outcome はゼロのため、リスク計算系の機能が空回りしている。同日中に P0 と P1 の一部を実装した。恒久化はツール側で完結させ、サイト本体はツールに依存させない(参照される側を保つ)と決めた。

きっかけ

Blast Radius(/tools/blast-radius/)が「何ができるのか中途半端」な状態になっている。具体的な不満は2つ。

  • 再生ボタン(▶)を押すと一瞬で終わり、何が起きたのか分からない
  • ノードが半透明になって、クリックできないことがある

この2つの原因を調べ、あわせて「将来、恒久的に使うツールにするなら何が要るか」を考えた。仕様は Blast Radius 実装仕様、設計判断は Blast Radius のスキーマ拡張を却下する にある。

調べ方

  • npm run build:blast で graph.json を作り直し、配布用の bundle/index.html を headless Chromium で開いた
  • ?debug=1 で中の状態(window.S)を読み、次を計測した
    • 再生にかかる時間
    • 画面上のノード全部について、その位置を実際にクリックして選択されるか
  • 状態は「通常」「Blast 表示中」「タイムラインを途中まで戻した状態」の3つで試した
  • 画面サイズはデスクトップ 1280×800 と、スマホ 390×844(タッチ操作)の2つ

不具合1: 再生が速すぎる

結論: 「1フレームごとに一定日数進む」実装で、時間ではなくフレーム数で再生しているため。

js/30-app.js:356 の再生処理は、毎フレーム次の量だけ時刻を進める。

S.t = … + Math.max(1, span / 240); // span = 最初の記事から最後の記事までの日数
  • 履歴が240日を超える場合は、240フレームで必ず終わる(60Hz の画面で約4秒、120Hz の画面なら約2秒)
  • このサイトの履歴は 14日分 しかない。Math.max(1, …) の下限が効いて1フレームで1日進むので、14フレーム、約0.23秒 で終わる
  • 実測でも、再生ボタンを押してから止まるまで約0.9秒だった(クリック処理の遅れを含む)

つまり、画面のリフレッシュレートや履歴の長さで速さが変わり、どの場合でも「何が増えたのか」を目で追える速さになっていない。さらに次の問題もある。

  • 再生中に「いつの、何の記事が追加されたか」を示す表示がない。ノードが黙って出てくるだけ
  • 一時停止しようにも、0.23秒では押す暇がない

直し方の案

  • 経過時間(performance.now() の差分)で進める。再生時間は「記事数 × 0.5秒」程度にし、8〜30秒に収める
  • 速度を 0.5× / 1× / 2× / 4× から選べるようにする
  • 「日付で連続的に進める」のではなく「記事1件ずつ進める」モードを既定にし、追加された記事のタイトルを字幕のように出す
  • 同じ日に18件追加された日もあるので、同じ日の記事は少しずつずらして出す

不具合2: 半透明になってクリックできない

先に結果を書く。

状態デスクトップスマホ
通常画面上の69件すべてクリックで選択できた1件ずつ間を空けてタップすれば選択できる。ただし隣のノードが選ばれることがある
Blast 表示中69件すべて選択できた同上
タイムラインを途中まで戻した状態表示中の37件すべて選択できた同上

どの状態でも、ノードの上に別の要素がかぶってクリックを奪っている箇所は無かった。デスクトップでは、半透明のノードも実際にはクリックできている。

「半透明でクリックできない」と感じる原因は、次の3つが重なっていると見ている。

2-1. Blast 表示の解除手段が Esc キーしかない(スマホでは抜けられない)

ノードを選んで blast を実行すると、影響を受けないノードは描画が薄くなる(js/30-app.js:278)。

  • 不透明度 0.2 に落ち、さらに塗りがその半分になる
  • ラベルも薄い灰色になる
  • 見た目は「無効化されて押せないボタン」そのもの

この状態を解除する方法は、Esc キー(js/30-app.js:1919)か、コマンドパレットの :reset だけ。

  • 何もない所をクリックしても、選択が外れるだけで Blast は解除されない(js/30-app.js:447)
  • スマホにはそもそも Esc キーが無い
  • 画面上に「Blast 表示中」の表示も、「解除」ボタンも無い

結果として、スマホでは一度 Blast を出すと、画面全体が薄いまま戻れなくなる。薄いノードをタップすると選択自体はされているが、薄いままなので「押せていない」ように見える。

2-2. その状態が URL に保存され、再読み込みしても続く

選択や Blast の起点は URL の # 以降に保存される(writeHash)。開いたときにそこから復元し、Blast も計算し直す(js/30-app.js:65)。

ページを再読み込みしても、ブックマークから開き直しても、薄いままになる。タイムラインを途中まで戻した位置(S.t)も保存されるので、「一部のノードが出てこない」状態も持ち越される。

2-3. スマホの初期表示が最小ズームで、ノードが5pxの点になる

全体を画面に収める処理(fit())は、ズームを 0.12〜2.2 の範囲に制限している。390px 幅に横長のグラフを収めようとすると、下限の 0.12 に張り付く。そうなると次のようになる。

  • ノードの半径は下限の 2.5px(直径5px)(js/30-app.js:266)
  • ラベルはズーム 0.38 を超えないと出ないので、全部消える(js/30-app.js:315)
  • 隣のノードとの間隔が数px しかないので、タップすると近くの別ノードが選ばれる(例: ノード20をタップしてノード6が選ばれた)

デスクトップでも初期ズームは約0.15で、ラベルが1つも出ていない。「何のグラフか分からない点の集まり」から始まることが、「中途半端」の印象を強めている。

なお、テストで素早く連続タップしたときは、ダブルタップ(全体表示し直し)と解釈されて選択に失敗することがあった。実際の操作では起きにくいが、ダブルタップの割り当ては見直したい。

直し方の案

  • Blast 中は画面上部に「Blast: ○○ 起点・N件に影響 [解除]」の帯を出す
  • 何もない所をタップしたら Blast も解除する
  • 選択中のノードの blast ボタンを、押すたびに出す/消すが切り替わる形にする
  • 影響を受けないノードの不透明度の下限を 0.2 → 0.35 程度に上げ、ラベルは残す
  • URL からの復元で Blast を戻すときは、上の帯を必ず出す。共有リンク以外では Blast を保存しない、という手もある
  • スマホの初期表示は「ノードが直径12px 以上・ラベルが出るズーム」を下限にして、最新の記事付近に寄せて始める

「中途半端」の正体: 機能に対してデータが足りていない

不具合とは別に、グラフの中身を数えると、ツールが前提としているデータがほとんど無いことが分かった。

項目値意味
ノード87件(decision 27 / reference 23 / log 19 / showcase 13 / その他 5)決定(ADR)向けのツールだが、決定は3割
リンク106本のうち relates-to が89本、depends-on は7本影響の伝わり方を表す「依存」がほぼ無い
## Outcome 節0件予測の当たり外れ(キャリブレーション)は計算できない
予約タグ(one-way 等)3回リスクモデルはほぼ既定値で動いている
孤立ノード22件どこにもつながっていない
循環9件(うち2件組が5件)related を両方向に書くと「循環」と数えられる
リンク切れ81件サンプル記事の意図的な未作成リンクと、本物の切れが混在

Monte Carlo、キャリブレーション、ホットスポット、Why(影響経路)などの分析は実装されている。しかし入力がこれでは、どれもほぼ空の結果しか返せない。

さらに、それらの機能はコマンドパレット(⌘K)の奥にあり、画面からは見つけにくい。「高機能だが、何も出てこない」という状態が「中途半端」の正体だと考える。

ほかに気づいた点:

  • 日本語版と英語版で同じファイル名の記事が、別々のノードとして両方入る。英訳がある記事ほど重複して見える
  • relates-to は向きのない関係なのに、循環の判定に入っている。両方向に related を書くだけで赤い輪が付き、画面が騒がしくなる

恒久ツールにするためのアイデア

方針: 「キャンバスで眺めるツール」から「記事を書くときに効く仕組み」へ

いまの Blast Radius は、単体の可視化アプリとして作り込まれている。ただ、このサイトで長く役に立つのは、次の2つだと考える。

  1. 記事ページで影響範囲が分かること。 「この記事を書き換えると、どの記事に響くか」
  2. リンクの健全性が自動で保たれること。 リンク切れ・孤立・重複

この2つはビルド時に計算できるので、キャンバスを開かなくても毎日効く。キャンバス版は「全体を俯瞰したいとき」用に絞る。

アイデア一覧

A. サイト本体に組み込む(不採用 — 追記2 参照)

  • 各記事ページの末尾に「この記事に依存している記事 / この記事が依存している記事」を出す。Blast Radius と同じグラフ計算をビルド時に使う
  • 決定(decision)の記事には「書き換えたときの影響件数」をバッジで出す
  • 「Blast Radius で開く」リンクを付け、その記事を中心にしたキャンバス表示へ飛べるようにする

B. 健全性チェックを CI に載せる

  • いまの :doctor(リンク切れ・予約タグの綴り間違い・Outcome 見出しの書式)を、npm run doctor:links として CI で回す
  • サンプル記事の「わざと未作成のリンク」は許可リストで除外し、本物のリンク切れだけを失敗として扱う
  • 新しく孤立した記事が出たら警告する

C. キャンバス版の使い勝手

  • 初期表示を「最新の記事付近、ラベルが読めるズーム」にする
  • 再生は時間ベース・速度選択・記事1件ずつ・タイトル字幕付きにする(不具合1の案)
  • Blast を「モード」として見えるようにする。帯、解除ボタン、トグル(不具合2の案)
  • スマホでは、最初にキャンバスではなく「検索 → 記事リスト → 影響リスト」を出し、キャンバスは補助にする
  • 言語フィルタを付け、既定は日本語だけにする
  • relates-to は循環判定から外し、線も控えめにする

D. データ不足の機能は「データが揃ったら出す」

  • Outcome が0件のうちは、キャリブレーションの画面に「## Outcome を書くとここに出ます」という案内だけを出す
  • Monte Carlo・ホットスポットも、依存リンクが一定数を超えるまでは案内表示にする
  • 決定記事のテンプレート(npm run new -- --type decision)に、depends-on の書き方と ## Outcome の雛形を最初から入れておく

E. 範囲を絞る

  • 音で知らせる機能(sonify)、:sudo、PNG に状態を埋め込む機能などの遊び要素は、実験枠に分ける。恒久版の中心は「影響範囲・リンクの健全性・時系列」の3つにする
  • 恒久化する部分には、今回の調査で作った確認手順を e2e テストとして残す
    • 再生にかかる時間
    • スマホで Blast を解除できるか
    • 画面上のノードがクリックで選択できるか

段階案

段階内容規模
P0再生を時間ベースに(速度選択・字幕付き)/Blast の帯と解除ボタン/何もない所をタップで解除/URL 復元時の表示小
P1スマホの初期ズームとタップ判定/ラベルの出し方/言語フィルタ/relates-to を循環判定から除外小〜中
P2記事ページへの影響範囲の埋め込み(不採用)/リンク健全性チェックをツール側のコマンドとして用意中
P3決定テンプレートの整備と、データが揃った機能から順に表に出す継続

次にやること

  • P0 の3点(再生・Blast の解除・URL 復元)から直す。どれも js/30-app.js の中で完結する
  • P2 の「記事ページへの埋め込み」は、サイト本体のビルド(Astro)に手を入れる。 → 不採用(追記2)

追記: P0 と P1 の一部を実装した

同じ日のうちに、次を直した。いずれも public/tools/blast-radius/js/30-app.js が中心。

項目変更確認
再生記事が追加された日を 1 日ずつ、時間ベースで進める(既定 1.1 秒/日)。速度は 0.5×〜4×。日付・件数・タイトルの字幕と、追加ノードの金色の輪を表示。新しいノードが画面外なら視点を移す。Space でも再生・停止14 日分で約 17 秒(以前は約 0.23 秒)。フレーム数では進まないことをテストで固定
Blast の解除画面上部に「BLAST・起点・件数・clear ✕」の帯。何もない所のタップ、blast / b の再実行でも解除スマホ幅でボタン・空白タップの両方で解除できることを確認。URL から復元したときも帯が出る
薄い表示影響外ノードの不透明度を 0.2 → 0.38、塗りを半分 → 3/4 に「押せないボタン」に見えない程度に
初期ズーム全体表示がラベルの読める下限(0.42)を割るときは、そのズームで最新側に寄せて始める。f で全体表示と切り替えスマホでもラベル付きで始まる
ラベル短縮ラベルを「日付を除いた slug を末尾から省略」にし、列の幅に収める以前は id の末尾 12 文字(rchitecture のような切れ方)で、隣の列と重なっていた
ダブルタップ同じノードを 2 回タップしたときだけ拡大する隣り合うノードを素早く続けてタップしても視点が飛ばない(17/17 選択)
言語グラフは言語を絞って組む。既定 auto は日本語を主とし、英語は対応する日本語が無い記事だけノード 87 → 81(英訳の重複 6 件が消えた)
循環relates-to を循環判定から外す循環 9 → 2。両方向の related だけでは赤い輪が付かない

テスト(npm run test:blast-graph)に、再生が時間ベースで進むこと、b で Blast を出し入れできること、言語の絞り込み、relates-to の対だけでは循環にならないことを追加した。

残りは P1 のうち「スマホで最初に検索とリストを出す」と、P2(リンク健全性チェック)、P3。

追記2: サイト本体はツールに依存させない

方針を決めた。サイト本体は Blast Radius に依存しない。ツールはサイトを参照する側にとどめ、サイトは「参照される側」を保つ。

  • アイデア A(記事ページに影響範囲を出す・影響件数バッジ・ツールへのリンクを記事に付ける)は採用しない。ツールの計算結果をサイトの記事ページやコンポーネントに持ち込むと、ツールの不具合や仕様変更がサイトの表示とビルドに波及するため
  • 影響範囲を知りたいときは、ツール側で記事を検索して開く。ツールからサイトの記事へは、従来どおり open で飛べる(ツール → サイトの向きの参照だけが残る)
  • B(リンク健全性チェック)は、ツール側のコマンドとして用意する方向に読み替える。サイトのビルドや公開を止める関門にはしない

この点検で、依存が逆向きになっている箇所が1つ見つかった。npm run build の prebuild が graph.json の生成スクリプトを呼んでおり、それが失敗するとサイト全体のビルドが止まっていた(実際、このセッション中に gray-matter が入っていない環境でサイトのビルドが落ちた)。

prebuild は生成に失敗しても警告を出して続行するように変えた。gray-matter を一時的に外して npm run build を流し、終了コード 0 でサイトのビルドが完了することを確かめた。npm run build:blast を単体で実行した場合は、従来どおり失敗を返す。

仕様(Blast Radius 実装仕様 の「非目標」)と README にも同じ方針を書き足した。