Canvas 2D（<canvas> の 2D コンテキスト）

実装: arm/v1/src/os_lib/canvas2d.rs（純粋モジュール） 試験: arm/v1/tests/src/test_canvas2d.rs（40 件）

着手前の状態

getContext("2d") は既に実装されており、fillRect / arc / bezierCurveTo / drawImage / getImageData など 30 以上のメソッドが 登録済みだった。ただしすべて dom_noop（何もしない）へ接続されており、 canvas を使うページでは一切描画されなかった。 状態プロパティ（fillStyle/lineWidth/font 等）も保持されるだけだった。

つまり「API 表面はあるが中身が無い」状態。

本モジュールの範囲

ハードウェア（画面）に依存しない部分をすべて扱う。

1. アフィン変換（Matrix）: 合成・適用・行列式・逆行列
2. パスの折れ線化（PathBuilder）: moveTo/lineTo/closePath/ ベジェ（2 次は 3 次へ昇格）/円弧/rect
3. 走査線による塗り判定（scanline_spans): nonzero / evenodd
4. バッキングストアへの描画（Surface）: ピクセル合成・矩形塗り・ パス塗り・線描
5. コンテキストの状態（Canvas2dContext / DrawState）: 変換の積み上げ、save/restore、globalAlpha、 fillRect/clearRect/fill/stroke の実行
6. 登録表（create_context/with_context）: JS オブジェクトと Rust 側の状態を id で結び付ける

JS からの接続

JS 側のコンテキストオブジェクトは _c2d_id（registry の id）だけを持ち、 実体は Rust 側の表にある。JS の値へ Rust の可変状態を直接埋めると借用と 寿命の扱いが複雑になるため、既存の DOM プロキシ（style/classList）と同じ 「id で引く」流儀に合わせた。

接続済みのメソッド: fillRect / strokeRect / clearRect / beginPath / closePath / moveTo / lineTo / rect / arc / bezierCurveTo / quadraticCurveTo / ellipse / roundRect / fill / stroke / save / restore / translate / scale / rotate / transform / setTransform / resetTransform。

roundRect の半径は数値 1 個でも配列（1〜4 要素）でも取れる。 補完規則は CSS の border-radius と同じ（1 個なら全隅、2 個なら対角の組、 3 個なら左上・対角・右下）。半径の和が辺長を超える場合は比率を保ったまま 縮小する——しないと角が重なって図形が破綻する。

restore() は変換だけでなく globalAlpha/lineWidth も JS 側へ 書き戻す。これらは JS の素のプロパティなので、Rust 側で戻すだけでは JS から読んだときに古い値が見えてしまう。 色（fillStyle/strokeStyle）は文字列表現を保持していないため 戻せない（既知の割り切り）。

fillStyle 等は JS の素のプロパティで代入を検知できないため、 各描画メソッドの入口で毎回読み直す（canvas_sync_state）。 色は CSS の parse_color をそのまま使う。

同時に保持するコンテキストは 8 個までで、超えたら古い id から捨てる。 ページ遷移のたびに面（最大 64MB）が積み上がるのを防ぐため。

曲線分割規則と巻き数計算という目視では気づけないバグ源を試験で固定できる。

なぜ画面ではなくバッキングストアへ描くか

<canvas> は「レイアウトで決まった矩形へ、自分のピクセルを貼る」要素。 画面座標へ直接描くと、スクロール・クリップ・再描画のたびに canvas の内容を作り直す必要が出る。Surface（ARGB8888 配列）へ キャンバス内座標で完結させておけば、貼り付けだけが画面側の仕事になる。

面のサイズは 4096×4096 を上限とし、超える指定は None を返す （ヒープを食い潰さないため）。

不変条件

• C-1: transform() は現在の行列へ右から掛ける（self * m）。 後から積んだ変換ほど点に対して先に効く。取り違えると translate してから rotate した図形が画面原点回りに回る。
• C-2: 退化行列（行列式 0）の invert() は None。 ゼロ除算で NaN を伝播させない。
• C-3: 点が 1 個以下の副パス（moveTo のみ）は捨てる。 残すと 0 長の線を描こうとする。
• C-4: moveTo 無しの lineTo は、その点への moveTo と同じ扱い。
• C-5: 円弧の掃引角が 2π を超える指定は 1 周へ丸める。 丸めないと分割数が発散して頂点が爆発する。
• C-6: 負の半径・非有限値の円弧は黙って無視する （描画系でパニックさせない）。
• C-7: 走査線の判定は半開区間 [ylo, yhi)。 閉区間にすると、頂点をちょうど走査線が通るときに上下 2 本の辺が 同じ交点を二重計上し、evenodd で内外が反転する （塗り残し・塗り過ぎの典型的な原因）。
• C-8: 水平な辺は交差を作らない。
• C-9: scanline_spans の返す区間は昇順・非重複。

塗りつぶし規則

• nonzero（既定）: 巻き数が 0 でなければ内側。 同じ向きに巻いた入れ子では穴が開かない。逆向きなら開く。
• evenodd: 交差回数が奇数なら内側。入れ子は常に穴が開く。

両者の違いは入れ子図形でしか現れないため、試験で明示的に区別している。

追加の不変条件（Surface）

• C-10: 範囲外への書き込みは黙って無視する（パニックさせない）。
• C-11: 合成は source-over。完全透明は何もしない、 不透明はそのまま置く。
• C-12: clearRect は合成せず上書きする（replace=true）。 合成にすると不透明な既存色が消えない。
• C-13: 走査線はピクセル中心（y + 0.5）で判定する。 境界ちょうどで判定すると、隣り合う図形の継ぎ目に隙間や二重塗りが出る。
• C-14: 線描の Bresenham には反復上限を設ける。 座標異常でも無限ループにしない。
• C-15: save() の入れ子には上限（32 段）を設ける。 restore を呼ばないスクリプトでヒープを食い潰さない。
• C-16: restore() の呼び過ぎはエラーではない（仕様どおり無視）。
• C-17: fillRect は矩形の高速路を持たず常にパス経由で塗る。 軸平行かどうかで分岐すると、回転が入ったときに誤った矩形を塗る。
• C-18: clearRect は globalAlpha の影響を受けない（仕様どおり）。 回転時は外接矩形を消す近似（clearRect に回転を掛ける使い方は稀）。
• C-19: globalAlpha は色のアルファへ掛け算で合成する。 半透明色はさらに薄くなる。
• C-20: 楕円は「半径で伸ばす → 回転する → 中心へ移す」順で写す。 順序を取り違えると回転した楕円が歪む。
• C-21: roundRect の半径は、和が辺長を超えたら比率を保って縮小する。 角が重なって図形が破綻するのを防ぐ。
• C-22: 太い線は線分に垂直な四角形へ展開して塗る。 Bresenham を平行にずらす方式だと斜線が痩せる（角度で太さが変わる）。
• C-23: 線幅 1 以下は 1px 線の高速路へ落とす（見た目・速度とも有利）。
• C-24: 結合部は外側だけを埋める。内側は線分の四角形が既に覆う。 外側の判定（曲がる向きの外積の符号）を誤ると角が欠ける。
• C-25: miter は外側 2 辺の交点まで尖らせるが、 鋭角では尖りが際限なく伸びるため miterLimit（既定 10）を 超えたら bevel へ落とす。交点が求まらない（平行）ときも同様。
• C-26: lineCap/lineJoin に未知の値を入れた代入は捨てる（仕様）。 既定値へ戻すのではない。
• C-27: canvas への描画はエッジトリガで再描画を要求する。 旗を立てっぱなしにすると毎フレーム全画面を描き直して画面が波打つ （画像ロードで実際に起きた。image_results_ready の注記を参照）。
• C-28: 破線は弧長で刻む。座標差で刻むと角度で間隔が変わる。
• C-29: 破線のパターンは折れ線の頂点をまたいで連続する。 頂点で仕切り直すと角で破線がずれる。
• C-30: 不正な破線パターン（負・非有限・空・全 0）はまるごと捨てる。 一部だけ直すのではない。奇数個は 2 周ぶんに複製する。
• C-31: クリップはラスタライズして持つ。式のまま持つと交差のたびに 判定が複雑になる。塗りと同じ走査線・同じ巻き数規則を使う （ずれるとクリップの縁に 1px の隙間が出る）。
• C-32: clearRect もクリップに従う。合成を飛ばすため blend_pixel を通らず、取りこぼしやすい。
• C-33: clip() は領域を狭めるだけで広げられない。
• C-34: putImageData は合成せず上書きし、クリップも無視する。 fill 系とは意味論が違う。
• C-35: createImageData は透明で埋めた新しい配列を返す。 面の内容は読まない（getImageData と混同しない）。
• C-36: getImageData で面の外に出た部分は透明で埋める。 切り詰めると返る配列の大きさが要求と食い違う。
• C-37: canvas.width/height への代入は、同じ値でも 内容と描画状態をまるごと初期化する。 canvas.width = canvas.width という消去の定型句がこれに依存する。
• C-38: 大きさ変更に失敗したら元の面を残す。 失敗時に面を失うと内容が消えたうえ復旧手段もなくなる。
• C-39: 画像の転送は逆変換で引く。転送元を押し出すと 拡大で隙間が空き、回転で縞が出る。
• C-40: drawImage の引数は 3・5・9 個で意味が変わる。 9 個のときだけ転送元の切り出しが指定される。
• C-41: デコード済み画像は Arc で共有する。 複製すると数 MB の写真を二重に持つことになる。
• C-42: 字形は転送の経路を通す（アルファを色に載せた画像として draw_image へ渡す）。別実装にすると変換への追従を二重に持つことになる。
• C-43: フォントの錠を描画中に持ち続けない。字形を写してから 錠を放し、描画は錠の外で行う。GLOBAL_VECTOR_FONT は毎フレームの 文字描画が使うため、握ったままだと優先度逆転を起こす。
• C-44: measureText は字形の送り幅を実測する。 バイト長からの概算は日本語で大きくずれ、文字サイズも反映されない。
• C-45: font の語順は自由なので、px で終わる数値を探す。 pt/em は換算しない（見つからなければ既定の 10px）。

画面への転送

レイアウトは StyledNode しか見ないため、JS のオブジェクトを直接引かせず DOM 属性 _c2d_id を橋渡しに使う。

1. getContext("2d") が registry へコンテキストを作り、id を DOM 要素の _c2d_id 属性へ書く
2. レイアウトが <canvas> 要素からその属性を読み、 RenderElement::canvas_ctx_id へ載せる
3. 描画時に registry から Surface を引き、要素の矩形へ転送する

面のサイズと要素のサイズが違う場合は最近傍で拡縮する。 CSS で width/height を指定した canvas は、属性の解像度と表示サイズが 食い違うのが普通なので、この経路は必須。

線幅

lineWidth は stroke / strokeRect に反映される。各線分を 「線幅ぶんの太さを持つ四角形」へ展開して塗り、結合部には円を置く。 ## 線端・線結合

lineCap は butt（既定）/round/square、lineJoin は miter（既定）/round/bevel に対応する。miterLimit も反映する。

低水準の stroke_path_width は端 butt・結合 round 固定で、 stroke_path_styled へ委譲する。既存の描画の見た目を変えないための 互換窓口であり、新しい呼び出しは stroke_path_styled を使う。

再描画

canvas はバッキングストア（Surface）へ描くだけなので、そのままでは 画面に出ない。画素を書く入口（fill_rect/fill_path/stroke_path/ stroke_path_styled）で旗を立て、ブラウザの再描画判定がそれを見る。 旗は描画の開始時に降ろす（take_canvas_dirty）。

破線・クリップ

setLineDash/lineDashOffset は stroke/strokeRect に反映される。 クリップは DrawState が Arc<ClipMask> として持ち、描画の直前に Surface へ写す。save/restore は状態を複製するだけなので、 クリップは正しく戻る（色と違って文字列表現に依存しない）。

ImageData・大きさの変更

getImageData/putImageData は面の画素を読み書きする （createImageData は透明のまま）。canvas.width/height への代入は 面を作り直して描画状態を初期化する。

画像の転送

drawImage は <img>（src で共有の置き場を引く）と別の canvas （_c2d_id からコンテキストを引く）を転送元にできる。 変換・globalAlpha・クリップに従う。

テキスト

fillText/measureText はベクトルフォントの字形を使う。 textAlign/textBaseline/font の大きさに従う。 strokeText は塗りで代用する（線でなぞる形は未対応）。 ベースラインの比率はこの処理系の字形配置に合わせた近似で、 フォントごとの実測値ではない。

残課題

1. restore() で色を戻せない（文字列表現を保持していないため）
2. strokeText の輪郭描き（現状は塗りで代用）
3. Path2D（clip(path, rule) の形は未対応）
4. 転送の補間は最近傍のみ（imageSmoothingEnabled は未対応）
5. 線描（stroke）の線幅・線端・線結合（現状は線幅 1 固定）
6. クリップ領域（clip()）
7. <canvas width height> の動的変更への追従（現状は getContext 時のみ）
8. 再描画の契機——JS が描いた後にレイアウト／再描画が走らないと 画面へ反映されない。現状は他の要因で再描画が起きたときに反映される。