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 種類）

タブ切り替えで以下のビューを利用できます。

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

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クエリで制御できるのは「どのコードを読み込むか」のみです）。

動作するデモ

このリポジトリの 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