Narapy

ブラウザ完結型 Python 学習環境

✨ Narapy とは

Narapy は、ブラウザだけで Python を書いて実行できる学習用 Web アプリです。 コードの実行結果やタートルグラフィックスの描画をその場で確認しながら、 「書いて理解する」体験を提供します。

サーバーは不要。すべてブラウザの中で完結します。Python の実行も、 タートルグラフィックスの描画も、すべてあなたの手元のブラウザで動きます。

💡 標準ライブラリの turtle 互換モジュールを内蔵。import turtle で図形描画の授業がそのまま動きます。

🎯 主な機能

🚀 クイックスタート

前提: Node.js 22+ / pnpm 10+ パッケージ管理は pnpm のみ（npm / yarn は使用しないでください）

# 依存関係をインストール
pnpm install

# 開発サーバー起動
pnpm dev

ブラウザで表示された URL（通常 http://localhost:5173）を開けば、すぐに使い始められます。

🛠️ 開発コマンド

🏗️ アーキテクチャ

Narapy は フロントエンド完結型。バックエンドサーバーを持たず、 重い処理（Python 実行）は Web Worker（WebAssembly 上の Pyodide）に逃がしています。

┌─────────────────────────────────────────────────────────────┐
│                     ブラウザ (UI スレッド)                     │
│                                                               │
│        🐍 Monaco エディタ ⇄ 🐢 Turtle/📊 matplotlib             │
│                   │                                           │
│                   ▼                                           │
│        ┌──────────────────┐                                   │
│        │  Pyodide Worker  │                                   │
│        │  Python 実行      │                                   │
│        └──────────────────┘                                   │
└─────────────────────────────────────────────────────────────┘

技術スタック

ディレクトリ構成

narapy/
├── src/
│   ├── main.ts            # エントリポイント（初期化・各モジュール連携）
│   ├── editor/            # Monaco エディタ・コード補完・フォントサイズ
│   ├── completion.worker.ts # Pyodide を使ったコード補完 Web Worker
│   ├── runner/            # 実行・Turtle/matplotlib 描画・エラー翻訳
│   ├── pyodide/           # Pyodide 連携（Turtle互換モジュール）
│   ├── lib/               # Pyodide ローダーなど共通ユーティリティ
│   ├── explorer/          # ファイルエクスプローラー・アップロード
│   ├── fileio/            # .narapy プロジェクト入出力
│   ├── urlload/           # URLの #code= / #project= / ?project=<URL> 読み込み
│   ├── makeUrl/           # /make-url（共有リンク生成ページ）のロジック
│   ├── layout/            # パネルレイアウト（split.js、状態をlocalStorageに永続化）
│   ├── about/             # ライセンス表示
│   ├── theme/             # カラーパレット・テーマ切り替え
│   └── pyodide.worker.ts  # Pyodide 初期化 Web Worker
├── docs/
│   ├── turtle-reference.md # 教材作成者向け Turtle リファレンス
│   └── url-loading.md      # 外部サイト連携・共有リンクの仕組み
├── index.html             # メイン画面（エディタ / ログ）
└── make-url.html          # 共有リンク生成ページ（/make-url）

🐢 タートルグラフィックス

標準 Python の turtle は Tkinter 依存でブラウザでは動きませんが、 Narapy は Canvas 上に描く独自実装を内蔵しています。 import turtle でそのまま書け、実行すると描画モーダルがアニメーション表示されます。

import turtle

for _ in range(4):
    turtle.forward(100)
    turtle.right(90)

• 原点 (0, 0) は画面中央、X は右が +、Y は上が +（数学・標準 turtle と同じ）
• モジュール関数（turtle.forward(...)）でも Turtle インスタンスでも記述可能

対応 API の一覧や教材作成時の注意点は docs/turtle-reference.md を参照してください。

🔗 共有リンク

Python コードやプロジェクトを、サーバーを介さずURLだけで共有できます。値はURLのハッシュ（#以降）に zlib圧縮 + base64url化して埋め込むため、アクセスログにも残りません。

リンクは /make-url（make-url.html）にブラウザでアクセスすると、コードやファイルを貼り付けるだけで生成できます （教材作成者向けのツールで、アプリ本体からの導線はあえて設けていません）。

詳しい仕組み・外部サイト連携時の実装例は docs/url-loading.md を参照してください。

📝 実装メモ

ブラウザの制約まわりで知っておくと役立つポイントです。

• COOP/COEP ヘッダー — SharedArrayBuffer（Pyodide に必要）のため、開発時は vite.config.ts の server.headers で付与。GitHub Pages 等ヘッダーを設定できない環境では coi-serviceworker で代替しています。
• Pyodide Worker — type: 'module' の Worker では importScripts() が使えないため、import() で CDN から動的読み込み。
• 共有リンクとCSP — ?project=<URL> での外部取得のため vite.config.ts の CSP connect-src に https: を許可。自前デプロイ時も同等の設定が必要です。
• postMessage連携は不可 — COOP設定により window.opener 経由の連携ができないため、外部サイトとの連携はURLハッシュ方式のみをサポートしています。

詳細は CLAUDE.md にまとまっています。

🚢 デプロイ

main ブランチへの push で GitHub Actions が自動デプロイします （.github/workflows/deploy.yml）。 S3 / CloudFront などへ手動デプロイする場合は、上記の COOP/COEP 相当のヘッダー付与を忘れずに。