Skip to content
BranchesTags

Repository files navigation

JSVisualizer

🚀 Live Demo — GitHub Pages でホスト中

English README

📖 使い方（利用者向けマニュアル） — 画面右上の「?」ボタンからも開けます

JavaScript プログラムの実行過程をインタラクティブに可視化する教育用 Web アプリケーションです。

式・文・関数呼び出しの各粒度でステップ実行しながら、12 種類の可視化ビューでプログラムの動作（時間の経過とともにメモリの内容がどう変化するか）を直感的に理解できます。

JSVisualizer デモ

特徴

ステップ実行の粒度（8方向ボタン）

フッターの 2行×4列グリッドで 4 粒度 × 前後 = 8 種類のステップ操作が可能です。

⏮  │  ◀◀文   ◀式   ▶式   ▶▶文  │  ⏭  ── スライダー ── カウンタ
   │  ⏪関   ◁人   ▷人   ⏩関  │
粒度 ボタン キーボード 説明
式評価 ◀式 / ▶式 b/←、n/→ 全 AST ノードの評価（最細粒度）
文評価 ◀◀文 / ▶▶文 V / v 文単位（サブ式をスキップ）
人にやさしい単位 ◁人 / ▷人 H / h 代入・条件判定・ループ更新など意味ある変化点のみ
関数呼び出し単位 ⏪関 / ⏩関 F / f 関数呼び出し・リターンをひとまとまりに

その他: Home → 先頭へ、End → 末尾へ、1〜9 → タブ切り替え

コードハイライト（3層）

コード表示エリアでは以下の 3 層が同時に視覚化されます。

層 色 意味
行ハイライト 🟦 青（左ボーダー＋背景） 現在実行中の行
式ハイライト 🟧 オレンジ（半透明） 現在評価中の式の文字範囲
呼び出し元ハイライト 🟣 パープル（破線アンダーライン） 関数内部を実行中のとき、その関数を呼び出した式

可視化ビュー（12 種類）

12 種類のビューは、可視化対象（何を見せるか）と時間表現（実行時間を画面上にどう対応づけるか）の 2 軸で整理しています。

  • 可視化対象: 8 つの対象を、学習者の躓きの原因に対応する 3 カテゴリにまとめています
    • 状態 — ある時点で保持されている値（変数の値、コールスタック、スタック／ヒープのメモリ配置）
    • 振る舞い — 実行が時間とともにどう展開するか（式の評価順、文の実行順・回数、関数呼び出しの順序・コスト）。式・文・関数呼び出しの 3 つはステップ実行の粒度に対応しており、選んだ粒度に対応するビューで動きを追えます
    • 複合型 — 構造を持つデータ（配列、オブジェクト）
  • 時間表現
    • アニメーション型 — ある 1 時点だけを示し、ステップごとにその場で更新する
    • タイムライン型 — 画面の一方の軸を時間に割り当て、複数の時点を同時に見せる
カテゴリ 可視化対象 アニメーション型 タイムライン型
状態 変数の値 変数 実行トレース
コールスタック コールスタック 変数寿命
メモリ配置 メモリ （提供しない）
振る舞い 式の評価 式評価 代入展開
文の実行 制御フロー ヒートマップ
関数呼び出し 呼び出しツリー （提供しない）
複合型 配列 配列 実行トレース
オブジェクト オブジェクト （提供しない）

すべての対象にアニメーション型のビューがあります。実行トレースは、変数の値と配列の両方のタイムライン型を兼ねます（配列＋ポインタのミニ図をステップごとに縦に並べる。ADR-037）。タイムライン型を用意しているのは、各ステップの状態が値・スタックの深さ・行の実行回数・小さな配列のように低次元の量に還元でき、その履歴を 1 本の軸上で見やすく示せる対象だけです。メモリ配置やオブジェクトは各時点の状態がすでにグラフで、グラフを時間方向に並べても読みにくいため、関数呼び出しは隣り合う時点の違いが強調表示されるノードだけで、タイムラインにしても情報がほとんど増えないため、タイムライン型を提供しません。

各ビューの詳細（タブ名は画面の表示どおり）:

カテゴリ タブ名 時間表現 説明
状態 変数 アニメーション 行番号列にソース先頭 15 文字スニペットを表示する変数マトリクス表。各行を最後に実行した時点の値を表示し、変化した変数値を橙太字で強調。列の表示/非表示・D&D 並び替え可
実行トレース タイムライン 変数の値と配列のタイムライン型を兼ねる。humanStep の実行順に全ステップを一覧。配列＋ポインタのミニ図（ポインタが検出されたステップのみ、表示枠の幅はドラッグで変更可）・変数値列・条件式列を表示。変化した値を橙太字で強調。while/for の条件式はイテレーションごとに値を表示
コールスタック アニメーション Global＋関数呼び出しフレームごとの変数値パネル（最内側関数先頭・factorial(6) 形式ラベル）
変数寿命 タイムライン 横軸を時間、縦軸をコールスタックの深さとして、各フレーム（関数の呼び出し）がいつからいつまで存在したかを帯で表示（帯には実引数付きの関数名とその時点の変数を表示）。ローカル変数や引数の生存期間がわかる
メモリ アニメーション スタック（スコープフレーム）とヒープ（オブジェクト・配列）を分離表示。SVG 矢印で参照関係を表現
振る舞い 式評価 アニメーション 代入・宣言・if/while/for 条件・return 引数など1行の式の部分式を逐次置換しながら最終値に収束する過程をトレース表形式で表示。短絡評価で評価されなかった部分式は元の式のまま残る。変数値はステップごとにリアルタイム更新。2色ハイライト付き
代入展開 タイムライン 再帰関数呼び出しを置換モデルで逐次展開。呼び出し式が return 式に置き換わる過程を展開ハイライト（橙）・次置換項ハイライト（青太字）付きで表示
制御フロー アニメーション AST ベースのフローチャート（if/else を true/false 列で横並び・ループは条件＋本体）。未実行ノードをグレーで表示し通らなかった分岐が一目でわかる
ヒートマップ タイムライン 各行の実行回数を「N回/M回」形式＋背景色でステップごとに動的更新。時系列ドット（実行済み/未実行色分け、360px幅）も可視化。異なる行へ遷移する連続ドット間を SVG 縦線で常時表示
呼び出しツリー アニメーション 全関数呼び出し（再帰・非再帰を問わない）を SVG ツリーで表示。各ノードにサブツリーコスト（cost:N）を表示
複合型 配列 アニメーション 複数の配列を色付き箱でインデックス付き表示。ポインタ変数は変数ごとに個別行で表示。各配列ブロックは枠線＋背景色で区切り、幅不足時は次行へ折り返し。ステップ間で配列位置が動かないよう最大サイズで領域を確保
オブジェクト アニメーション オブジェクト・配列の参照関係を SVG グラフで表示（階層型レイアウト。連結成分を自動分離・ノードを背景色で色分け）

タブ上の並び順は上表とは異なります（コールスタック・変数・実行トレース・代入展開・式評価・配列・ヒートマップ・呼び出しツリー・変数寿命・制御フロー・メモリ・オブジェクトの順。1〜9 キーはこの順の 1〜9 番目に対応）。この分類の考え方は、論文「プログラムの動作を複数のビューで可視化するプログラム実行環境の提案」（田中・上田、IS-26-049）の表 1 に基づきます（論文執筆時点で未実装だった配列のタイムライン型は、その後、実行トレースの機能として実装しました）。

Console 出力（console.log ログ）は、どのタブを選択中でも右ペイン下部の常時表示パネルに表示されます（上端ドラッグで高さ変更可）。

エディタ機能

  • シンタックスハイライト — CodeMirror 6 によるキーワード・文字列・コメントの色分け（ライト/ダークテーマ連動）
  • ペインリサイザー — 左右ペインの境界をドラッグして幅を自由に調整（幅は自動保存）
  • プログラム名表示 — サンプルを選択するとヘッダーにサンプル名を表示

URLクエリでコードを外部から読み込む

サンプル選択やコードの貼り付けとは別に、URLクエリパラメータを使って外部（例: BhvVisualizerなどの連携アプリ、あるいは自前でホストした静的JSON）からコードを直接読み込ませることができます。JSVisualizer単体でも「特定のコードへの直リンク」として機能する汎用機能です（# BHV:タグのログ送信配線とは無関係。設計の背景はADR-031を参照）。

クエリパラメータ 意味
exercise 演習（コードの集合）を取得するための完全なURL。指定すると、サンプル選択が組み込みサンプルの代わりにそのURLをfetchして得られるコード一覧だけになる
code 表示させたい個別のコードを取得するための完全なURL。指定すると、そのコードがエディタに直接読み込まれ、サンプル選択も組み込みサンプルの代わりにそのコード1件だけになる

exercise・code はJSVisualizer自身が発行するIDやAPIパス規約を必要としません。呼び出し元がfetch可能な完全なURLをそのまま渡すだけです。JSVisualizerはそのURLをfetchしてtitle/codeフィールドを読み取るだけで、コードがどこにホストされているか（BhvVisualizerか、それ以外の自前サーバーか）には関与しません。

組み合わせによる動作の違い:

指定 動作
exercise のみ サンプル選択が演習のコード一覧に置き換わり（組み込み21種のサンプルは選択肢から消える）、先頭のコードが自動的にエディタへ読み込まれる。演習のタイトルが取得できた場合、サンプル選択の初期表示（「─ サンプル ─」の位置）が演習タイトルに置き換わる
code のみ 指定したコード1件がエディタに直接読み込まれ、サンプル選択もそのコード1件だけの選択肢になる
exercise + code サンプル選択は演習のコード一覧のまま、エディタはcodeで指定したコードの内容になる（先頭コードの自動読み込みよりcodeが優先される）。サンプル選択の初期表示は演習タイトルになる
指定なし 何も起きない（既定のFibonacciサンプル・21種の組み込みサンプルはそのまま）

exercise・codeのいずれかが指定されている間は、組み込みサンプルはサンプル選択の選択肢から一時的に取り除かれます（学習用URLとして配信する際に無関係なサンプルが混ざらないようにするため。ADR-033）。クエリを外してスタンドアロンでアクセスした場合は、従来通り21種すべてが選択できます。

例:

# 個別コードへの直リンク
https://tntetsu.github.io/JSVisualizer/?code=https%3A%2F%2Fbhv-visualizer.web.app%2Fapi%2Fcodes%2Fabc123

# 演習を開く（先頭のコードが自動表示され、他のコードはサンプル選択から切り替えられる）
https://tntetsu.github.io/JSVisualizer/?exercise=https%3A%2F%2Fbhv-visualizer.web.app%2Fapi%2Fexercises%2Fex1

# 演習内の特定コードを指定して開く
https://tntetsu.github.io/JSVisualizer/?exercise=https%3A%2F%2Fbhv-visualizer.web.app%2Fapi%2Fexercises%2Fex1&code=https%3A%2F%2Fbhv-visualizer.web.app%2Fapi%2Fcodes%2Fco2

# ローカル開発中のAPIを参照させる（bhvApiBaseのような専用パラメータは不要。URL自体をローカル向けにするだけ）
https://tntetsu.github.io/JSVisualizer/?code=http%3A%2F%2Flocalhost%3A5000%2Fapi%2Fcodes%2Fabc123

exercise・code の値はURLエンコードした状態で渡す必要があります（URLSearchParamsで組み立てれば自動的にエンコードされます）。存在しないURL・非公開のコードを指定した場合は、エラーメッセージ欄にその旨が表示されます。なお、コード内の特定の行番号やカーソル位置を指定してジャンプする機能はありません（URLクエリで制御できるのは「どのコードを読み込むか」のみです）。

初期表示ビューの指定（view）

exercise・codeとは独立に、viewクエリパラメータで最初の実行（Run）時に開くビューを指定できます（ADR-036）。指定できる値は、右ペインのタブに対応する以下のIDです。

state（コールスタック）・trace（変数）・exectrace（実行トレース）・subst（代入展開）・exprtrace（式評価）・colorbox（配列）・heatmap（ヒートマップ）・calltree（呼び出しツリー）・lifetime（変数寿命）・controlflow（制御フロー）・memory（メモリ）・objgraph（オブジェクト）

# コードを開き、最初の実行でメモリビューを表示する
https://tntetsu.github.io/JSVisualizer/?code=https%3A%2F%2Fbhv-visualizer.web.app%2Fapi%2Fcodes%2Fabc123&view=memory

通常、アクティブなタブはlocalStorageに保存され次回起動時に復元されますが、viewが指定されている場合はそのページで最初に実行したときだけこの復元より優先されます。2回目以降の実行では通常の優先順位（前回保存したタブ→最初のビュー）に戻り、localStorageの保存値自体は書き換えません。

動作するデモ

このリポジトリの web/samples/ に置いた静的JSONファイル（GitHub Pagesで配信、BhvVisualizerとは無関係）を実際に読み込むリンクです。クリックしてそのまま動作を確認できます。

これらのJSONファイル自体（code-demo.json・exercise-demo.json）は「期待するAPIレスポンス形式」の実例にもなっています。

期待するAPIレスポンス形式

exercise・code が指すURLは、以下のJSON形式でレスポンスを返す必要があります（src/core/exercise-source.jsが読み取る形式）。

GET <exercise の値>
  200 OK →
    {
      "title": "...",
      "codes": [
        { "title": "...", "code": "...（JavaScriptソース文字列）" },
        ...
      ]
    }
  200以外（404など） → 演習が見つからない・非公開として扱う

GET <code の値>
  200 OK →
    { "title": "...", "code": "...（JavaScriptソース文字列）" }
  200以外（404など） → コードが見つからない・非公開として扱う

exercise側のトップレベルtitleは任意項目です。含まれていればサンプル選択の初期表示に使われ、省略した場合は既定の「─ サンプル ─」のままになります。JSVisualizerが実際に参照するのはこれらのフィールドのみです。他のフィールドが含まれていても無視されます。200以外のステータスはすべて「見つからない・非公開」として扱われるため、エラー時のレスポンスボディの形式は問いません。

この形式で応答するAPIであれば、BhvVisualizer以外の任意のシステム（自前で書いた静的JSONホスティングなど）から読み込ませることもできます。BhvVisualizerの実装はBhvVisualizer/docs/design.md 2.4節を参照してください。

テーマ

右上の ⚙ ボタンからライトテーマとダークテーマを切り替えられます。 デフォルトはライトテーマ。設定は自動的に保存され、次回起動時も維持されます。

言語（日本語 / English）

ヘッダーの EN / 日 ボタンで表示言語を切り替えられます。ボタンラベル・タブ名・説明文・設定パネルなど UI 全体（約 46 項目）が即座に切り替わります。デフォルトは日本語。設定は自動的に保存され、次回起動時も維持されます（エラーメッセージとサンプルプログラム名は対象外）。

その他

  • ステップバック対応 — 過去のステップに戻れる（O(1)）
  • サンプルコード 21 種内蔵 — バブルソート・フィボナッチ（再帰/DP）・クラスと継承・連結リストなど
  • 分割代入サポート — [a, b] = [b, a] などのスワップ構文に対応
  • カスタムコード対応 — 自分で書いた JavaScript を貼り付けて実行
  • 設定永続化 — テーマ・最後に見ていたタブ・ペイン幅を localStorage に保存し次回起動時に復元
  • 色覚多様性対応 — 色だけでなく形・パターン・アイコンで状態を表現
  • わかりやすいエラー表示 — 構文エラー/実行エラーをバッジ付きで表示

インストール

git clone https://github.com/tntetsu/JSVisualizer.git
cd JSVisualizer
npm install

JSInterpreter が ../JSInterpreter に存在する必要があります。

# JSInterpreter が未取得の場合
cd ..
git clone https://github.com/tntetsu/JSInterpreter.git
cd JSVisualizer

使い方

開発サーバーの起動

npm run dev

ブラウザで http://localhost:8000 を開いてください。ファイルを保存すると自動的に再ビルドされます。

本番ビルド

npm run build
# web/ 以下に成果物が生成されます

テスト

npm test

サンプルコード（21 種類）

カテゴリ サンプル
探索 線形探索、二分探索
ソート（基本） バブルソート、選択ソート
ソート（高度） クイックソート、マージソート
ソート（オブジェクト） 数値キーでソート、文字列キーでソート
数学・アルゴリズム ユークリッド互除法（ループ/再帰）、階乗、フィボナッチ（再帰）、フィボナッチ（DP/メモ化）
データ構造 二分木構築・探索、連結リスト
スコープ・オブジェクト クロージャ、クラスと継承
Study Tasks [Warm-up] 階乗（ループ）、[Task 1] 選択ソート（バグあり）、[Task 2] フィボナッチ（呼び出し回数）、[Task 3] バブルソート（中間状態）

対象ユーザー

  • プログラミング学習者 — 自分のコードの動作を一歩ずつ確認したい
  • 教員 — 授業で動くプログラムを見せながら解説したい
  • 教材制作者 — トレース図のアニメーションを手軽に作りたい

背景・動機

プログラミング教育において、学生がバグの修正に苦労する主な原因は「プログラムの動作の理解不足」です。紙や静的なスライドでは動作が伝わりにくく、既存のトレースツール（Algorithm Visualizer、Python Tutor など）は可視化専用コードの埋め込みが必要だったり、表示が見にくいという問題があります。

JSVisualizer は 汎用の JavaScript インタープリタを内蔵することで、任意のコードを貼り付けるだけで多彩な可視化を提供します。

技術スタック

項目 採用技術
コアエンジン JSInterpreter（自作 JS インタープリタ）
フロントエンド Vanilla JS (ES2022+) + HTML + CSS
ビルドツール esbuild
テスト Jest（71 テスト）
コードエディタ CodeMirror 6
可視化 DOM + CSS アニメーション + SVG 手動描画
テーマ CSS カスタムプロパティ（Catppuccin Latte / Mocha）
CI/CD GitHub Actions → GitHub Pages

ドキュメント

ライセンス

MIT

About

JavaScript プログラムの実行過程をインタラクティブに可視化する教育用 Web アプリケーション

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages