# 画面設計書 22-Annotated Source - Browser

## 概要

本ドキュメントは、CoffeeScript v1のブラウザサポートモジュール(browser.coffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`browser.coffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。

**業務上の目的・背景**：CoffeeScriptをブラウザ環境で直接使用するための機能実装を理解したい開発者向けに、XHRによるリモートスクリプト読み込み、`text/coffeescript`スクリプトタグの自動コンパイル、ソースマップ対応などのブラウザ互換性レイヤーの仕組みを解説する。browser.coffeeはCoffeeScriptをブラウザで直接実行可能にする重要なモジュールである。

**画面へのアクセス方法**：v1 Annotated Sourceのインデックスページ(docs/v1/annotated-source/index.html)から「browser.coffee」リンクをクリック、またはURLを直接指定してアクセスする。

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. セクションアンカーリンクによる特定セクションへの直接アクセス
4. CoffeeScript.eval、CoffeeScript.run、CoffeeScript.load関数の実装理解

**画面遷移**：
- 遷移元：v1 Annotated Source Index、他のAnnotated Sourceページ
- 遷移先：cake.coffee、coffee-script.coffee、command.coffee、grammar.coffee、helpers.coffee、index.coffee、lexer.coffee、nodes.coffee、optparse.coffee、register.coffee、repl.coffee、rewriter.coffee、scope.litcoffee、sourcemap.litcoffee

**権限による表示制御**：なし（静的ドキュメントのため全ユーザーがアクセス可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 51 | ブラウザコンパイラ | 主機能 | ブラウザサポートbrowser.coffeeのソースコード解説表示 |
| 52 | XHRローダー | 補助機能 | load関数の解説を含む |
| 53 | scriptタグ実行 | 補助機能 | runScriptsの解説を含む |

## 画面種別

詳細（ソースコード解説ドキュメント）

## URL/ルーティング

`docs/v1/annotated-source/browser.html`

## 入出力項目

本画面は静的HTMLドキュメントのため、ユーザー入力項目はない。

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| タイトル | browser.coffee | h1テキスト |
| Jump Toメニュー | 他ソースファイルへの遷移リンク一覧 | ドロップダウンリスト |
| セクションリスト | ソースコード解説セクション（全8セクション） | 2カラムレイアウト |
| 解説テキスト | 各セクションの解説文 | HTML段落 |
| ソースコード | 対応するCoffeeScriptコード | シンタックスハイライト付きpre |

### 解説セクション一覧

| セクション番号 | 内容 | 対応する主要関数/処理 |
|----------------|------|----------------------|
| 1 | ブラウザ互換性レイヤーの概要 | モジュールインポート |
| 2 | eval関数の定義 | CoffeeScript.eval |
| 3 | run関数の定義 | CoffeeScript.run |
| 4 | ブラウザ環境チェック | window?判定 |
| 5 | ソースマップ対応 | btoa/JSON対応時のcompile拡張 |
| 6 | XHRによるリモートスクリプト読み込み | CoffeeScript.load |
| 7 | scriptタグの自動コンパイル | runScripts |
| 8 | DOMContentLoadedイベントリスナー | イベント登録 |

## イベント仕様

### 1-Jump Toメニュークリック

ユーザーが「Jump To」メニューをクリックすると、ドロップダウンリストが展開され、他のソースファイル解説ページへのリンクが表示される。リンクをクリックすると対応するHTMLページに遷移する。

### 2-セクションアンカークリック

各セクションの段落記号（pilcrow）をクリックすると、そのセクションへのアンカーリンクがURLに設定され、ブックマークや共有に使用可能となる。

## データベース更新仕様

本画面は静的HTMLドキュメントであり、データベース操作は発生しない。

## メッセージ仕様

本画面は静的ドキュメントのため、動的メッセージは表示されない。

## 例外処理

静的HTMLファイルのため、以下のHTTPエラーのみ発生しうる：
- 404 Not Found: ファイルが見つからない場合
- 500 Internal Server Error: サーバー側の問題

## 備考

- Doccoツール（http://ashkenas.com/docco/）で自動生成されたドキュメント
- CoffeeScript 1.x系のソースコードを対象としている
- このモジュールはブラウザ環境専用の機能を提供する
- Node.js環境ではwindow?がfalseとなり、一部機能がスキップされる

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

browser.coffeeが操作する主要なデータ構造は、グローバルwindowオブジェクト、XHRオブジェクト、scriptタグDOM要素である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | browser.coffee | `src/browser.coffee` | CoffeeScriptオブジェクトへのメソッド追加パターンを理解 |

**読解のコツ**: ブラウザ環境のグローバルオブジェクト（window、document、XMLHttpRequest）への依存を把握する。

#### Step 2: エントリーポイントを理解する

browser.coffeeはブラウザで読み込まれると、DOMContentLoadedイベントでrunScriptsが自動実行される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | browser.coffee | `src/browser.coffee` | 6-7行目でcoffeescriptモジュールインポート |
| 2-2 | browser.coffee | `src/browser.coffee` | 103-107行目でイベントリスナー登録 |

**主要処理フロー**:
1. **6-7行目**: CoffeeScriptモジュールとcompile関数のインポート
2. **13-16行目**: CoffeeScript.eval関数の定義
3. **19-22行目**: CoffeeScript.run関数の定義
4. **29行目**: ブラウザ環境チェック（window?）
5. **34-37行目**: ソースマップ対応（btoa/JSON存在時）
6. **40-56行目**: CoffeeScript.load関数（XHR）
7. **61-96行目**: runScripts関数（scriptタグ処理）
8. **103-107行目**: DOMContentLoadedイベント登録

#### Step 3: CoffeeScript.load関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | browser.coffee | `src/browser.coffee` | 40-56行目：load関数 |

**主要処理フロー**:
- **40行目**: load関数の定義（url, callback, options, hold引数）
- **41行目**: sourceFilesオプションにURLを設定
- **42-45行目**: XHRオブジェクトの生成（ActiveXObject対応含む）
- **46行目**: GETリクエストのオープン
- **48-55行目**: onreadystatechange処理（ステータス0/200時に実行）
- **56行目**: リクエスト送信

#### Step 4: runScripts関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | browser.coffee | `src/browser.coffee` | 61-96行目：runScripts関数 |

**主要処理フロー**:
- **62行目**: document.getElementsByTagNameでscriptタグ取得
- **63行目**: 対象MIMEタイプ定義（text/coffeescript, text/literate-coffeescript）
- **64行目**: 対象scriptタグの抽出
- **67-72行目**: execute関数（順次実行）
- **74-94行目**: 各scriptタグの処理（外部src or インライン）
- **96行目**: execute()呼び出しで実行開始

### プログラム呼び出し階層図

```
ブラウザ読み込み
    |
    +-- DOMContentLoaded
            |
            +-- runScripts()
                    |
                    +-- getElementsByTagName('script')
                    |
                    +-- for script in coffees
                    |       |
                    |       +-- [外部src] CoffeeScript.load()
                    |       |       |
                    |       |       +-- XMLHttpRequest
                    |       |       +-- CoffeeScript.run()
                    |       |
                    |       +-- [インライン] coffees[i] = [innerHTML, options]
                    |
                    +-- execute()
                            |
                            +-- CoffeeScript.run()
                                    |
                                    +-- compile()
                                    +-- Function()()
```

### データフロー図

```
[入力]                       [処理]                         [出力]

<script type="text/       runScripts()              JavaScript実行
 coffeescript">        --------->                       結果
 ...                              |
</script>                         v
                         CoffeeScript.run()
                                  |
                                  v
                         compile(code, options)
                                  |
                                  v
                         Function(js)()


外部.coffeeファイル   load() + XHR           CoffeeScript.run()
(URL指定)         --------->           --------->    実行結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| browser.coffee | `src/browser.coffee` | ソース | ブラウザサポートの実装 |
| browser.html | `docs/v1/annotated-source/browser.html` | テンプレート | Docco生成HTML |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | メインコンパイラ |
| docco.css | `docs/v1/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
