atmos/os_lib/

canvas2d.rs

//! Canvas 2D の変換行列とパス幾何（純粋モジュール）。
//!
//! `<canvas>` の 2D コンテキストは、現状 API 表面だけが存在し
//! 全メソッドが `dom_noop` へ接続されている（＝一切描画されない）。
//! 実描画を入れる前提として、ラスタライズに依存しない部分——
//! **アフィン変換の合成**と**パスの折れ線化**——をここへ集約する。
//!
//! ハードウェアにもグローバル状態にも依存しないので、ホスト側で検証できる。
//!
//! # 座標系
//!
//! 変換行列は CSS/Canvas と同じ `[a b c d e f]` の並びで、点 (x, y) は
//!
//! ```text
//! x' = a*x + c*y + e
//! y' = b*x + d*y + f
//! ```
//!
//! へ移る。`transform()` は**現在の行列へ右から掛ける**（後から積んだ変換が
//! 点に対して先に効く）。この順序を取り違えると `translate` してから
//! `rotate` した図形が原点回りに回ってしまうので、試験で固定する。

extern crate alloc;
use alloc::vec::Vec;

/// アフィン変換行列 `[a b c d e f]`。
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Matrix {
    pub a: f32,
    pub b: f32,
    pub c: f32,
    pub d: f32,
    pub e: f32,
    pub f: f32,
}

impl Default for Matrix {
    fn default() -> Self {
        Self::identity()
    }
}

impl Matrix {
    pub fn identity() -> Self {
        Matrix { a: 1.0, b: 0.0, c: 0.0, d: 1.0, e: 0.0, f: 0.0 }
    }

    pub fn translate(tx: f32, ty: f32) -> Self {
        Matrix { a: 1.0, b: 0.0, c: 0.0, d: 1.0, e: tx, f: ty }
    }

    pub fn scale(sx: f32, sy: f32) -> Self {
        Matrix { a: sx, b: 0.0, c: 0.0, d: sy, e: 0.0, f: 0.0 }
    }

    /// 角度はラジアン。正の角度で「x 軸から y 軸へ」回る（Canvas の既定は
    /// y 軸が下向きなので、画面上は時計回りに見える）。
    pub fn rotate(rad: f32) -> Self {
        let (s, c) = (libm::sinf(rad), libm::cosf(rad));
        Matrix { a: c, b: s, c: -s, d: c, e: 0.0, f: 0.0 }
    }

    /// `self` に `m` を**右から**掛ける（`self * m`）。
    ///
    /// Canvas の `ctx.transform(...)` の意味論。後から積んだ変換ほど
    /// 点に対して先に効く。
    pub fn multiply(&self, m: &Matrix) -> Matrix {
        Matrix {
            a: self.a * m.a + self.c * m.b,
            b: self.b * m.a + self.d * m.b,
            c: self.a * m.c + self.c * m.d,
            d: self.b * m.c + self.d * m.d,
            e: self.a * m.e + self.c * m.f + self.e,
            f: self.b * m.e + self.d * m.f + self.f,
        }
    }

    /// 点を変換する。
    pub fn apply(&self, x: f32, y: f32) -> (f32, f32) {
        (
            self.a * x + self.c * y + self.e,
            self.b * x + self.d * y + self.f,
        )
    }

    /// 行列式。0 なら退化（逆行列を持たない）。
    pub fn determinant(&self) -> f32 {
        self.a * self.d - self.b * self.c
    }

    /// 逆行列。退化していれば `None`（呼び出し側は変換を諦める）。
    ///
    /// `isPointInPath` のようにデバイス座標をユーザー座標へ戻す用途で要る。
    pub fn invert(&self) -> Option<Matrix> {
        let det = self.determinant();
        if !det.is_finite() || libm::fabsf(det) < 1e-12 {
            return None;
        }
        let inv = 1.0 / det;
        Some(Matrix {
            a: self.d * inv,
            b: -self.b * inv,
            c: -self.c * inv,
            d: self.a * inv,
            e: (self.c * self.f - self.d * self.e) * inv,
            f: (self.b * self.e - self.a * self.f) * inv,
        })
    }
}

/// パスを構成する副パス（連続した折れ線）。
#[derive(Debug, Clone, PartialEq)]
pub struct SubPath {
    /// 折れ線の頂点（変換適用済みのデバイス座標）。
    pub points: Vec<(f32, f32)>,
    /// `closePath()` で閉じられたか。
    pub closed: bool,
}

/// パス構築器。曲線は折れ線へ分割して保持する。
///
/// ラスタライザは「折れ線の集まり」だけを相手にすればよくなるので、
/// 曲線の分割規則をここへ閉じ込めて試験できる。
#[derive(Debug, Clone, Default)]
pub struct PathBuilder {
    subpaths: Vec<SubPath>,
    current: Option<SubPath>,
    /// 直近の点（**変換前**のユーザー座標）。曲線の始点に使う。
    last_user: Option<(f32, f32)>,
}

/// 円弧を折れ線化するときの、90 度あたりの分割数。
const ARC_SEGMENTS_PER_QUARTER: usize = 8;
/// ベジェ 1 本あたりの分割数。
const BEZIER_SEGMENTS: usize = 16;

impl PathBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    /// 現在の副パスを確定して次へ移る。
    ///
    /// 点が 1 個以下の副パスは描画に寄与しないので捨てる
    /// （`moveTo` だけして何も引かなかった場合など）。
    fn flush(&mut self) {
        if let Some(sp) = self.current.take() {
            if sp.points.len() >= 2 {
                self.subpaths.push(sp);
            }
        }
    }

    pub fn begin_path(&mut self) {
        self.subpaths.clear();
        self.current = None;
        self.last_user = None;
    }

    pub fn move_to(&mut self, m: &Matrix, x: f32, y: f32) {
        self.flush();
        self.current = Some(SubPath {
            points: alloc::vec![m.apply(x, y)],
            closed: false,
        });
        self.last_user = Some((x, y));
    }

    pub fn line_to(&mut self, m: &Matrix, x: f32, y: f32) {
        // `moveTo` 無しの `lineTo` は、仕様上その点への `moveTo` と同じ扱い。
        if self.current.is_none() {
            self.move_to(m, x, y);
            return;
        }
        if let Some(sp) = self.current.as_mut() {
            sp.points.push(m.apply(x, y));
        }
        self.last_user = Some((x, y));
    }

    pub fn close_path(&mut self) {
        if let Some(sp) = self.current.as_mut() {
            sp.closed = true;
        }
        self.flush();
    }

    pub fn add_path(&mut self, other: &PathBuilder, transform: Option<&Matrix>) {
        self.flush();
        let id_mat = Matrix::identity();
        let m = transform.unwrap_or(&id_mat);
        for sp in &other.subpaths {
            let pts = sp.points.iter().map(|p| m.apply(p.0, p.1)).collect();
            self.subpaths.push(SubPath {
                points: pts,
                closed: sp.closed,
            });
        }
        if let Some(ref sp) = other.current {
            if sp.points.len() >= 2 {
                let pts = sp.points.iter().map(|p| m.apply(p.0, p.1)).collect();
                self.subpaths.push(SubPath {
                    points: pts,
                    closed: sp.closed,
                });
            }
        }
        if let Some((lx, ly)) = other.last_user {
            let lp = m.apply(lx, ly);
            self.last_user = Some((lp.0, lp.1));
        }
    }

    /// 3 次ベジェ。始点は直近の点。
    pub fn bezier_curve_to(
        &mut self,
        m: &Matrix,
        c1x: f32,
        c1y: f32,
        c2x: f32,
        c2y: f32,
        x: f32,
        y: f32,
    ) {
        let (x0, y0) = match self.last_user {
            Some(p) => p,
            None => {
                self.move_to(m, c1x, c1y);
                (c1x, c1y)
            }
        };
        for i in 1..=BEZIER_SEGMENTS {
            let t = i as f32 / BEZIER_SEGMENTS as f32;
            let mt = 1.0 - t;
            let px = mt * mt * mt * x0
                + 3.0 * mt * mt * t * c1x
                + 3.0 * mt * t * t * c2x
                + t * t * t * x;
            let py = mt * mt * mt * y0
                + 3.0 * mt * mt * t * c1y
                + 3.0 * mt * t * t * c2y
                + t * t * t * y;
            self.line_to(m, px, py);
        }
        self.last_user = Some((x, y));
    }

    /// 2 次ベジェ。3 次へ昇格させて処理する。
    pub fn quadratic_curve_to(&mut self, m: &Matrix, cx: f32, cy: f32, x: f32, y: f32) {
        let (x0, y0) = match self.last_user {
            Some(p) => p,
            None => {
                self.move_to(m, cx, cy);
                (cx, cy)
            }
        };
        // 2 次 → 3 次の標準的な昇格。
        let c1x = x0 + 2.0 / 3.0 * (cx - x0);
        let c1y = y0 + 2.0 / 3.0 * (cy - y0);
        let c2x = x + 2.0 / 3.0 * (cx - x);
        let c2y = y + 2.0 / 3.0 * (cy - y);
        self.bezier_curve_to(m, c1x, c1y, c2x, c2y, x, y);
    }

    /// 円弧。`anticlockwise` が真なら反時計回り。
    pub fn arc(
        &mut self,
        m: &Matrix,
        cx: f32,
        cy: f32,
        r: f32,
        start: f32,
        end: f32,
        anticlockwise: bool,
    ) {
        // 負の半径・非有限値は仕様上エラーだが、ここでは黙って無視する
        // （描画系でパニックさせない方が安全）。
        if !r.is_finite() || r < 0.0 || !start.is_finite() || !end.is_finite() {
            return;
        }
        let sweep = normalize_sweep(start, end, anticlockwise);
        let steps = arc_steps(sweep);
        for i in 0..=steps {
            let t = i as f32 / steps as f32;
            let ang = start + sweep * t;
            let px = cx + r * libm::cosf(ang);
            let py = cy + r * libm::sinf(ang);
            if i == 0 && self.current.is_none() {
                self.move_to(m, px, py);
            } else {
                self.line_to(m, px, py);
            }
        }
    }

    /// 矩形。独立した閉じた副パスになる。
    pub fn rect(&mut self, m: &Matrix, x: f32, y: f32, w: f32, h: f32) {
        self.flush();
        self.current = Some(SubPath {
            points: alloc::vec![
                m.apply(x, y),
                m.apply(x + w, y),
                m.apply(x + w, y + h),
                m.apply(x, y + h),
            ],
            closed: true,
        });
        self.flush();
        self.last_user = Some((x, y));
    }

    /// 構築済みの副パス一覧を返す（未確定の副パスも含める）。
    pub fn finish(&self) -> Vec<SubPath> {
        let mut out = self.subpaths.clone();
        if let Some(sp) = &self.current {
            if sp.points.len() >= 2 {
                out.push(sp.clone());
            }
        }
        out
    }
}

/// 円弧の掃引角を求める。
///
/// Canvas の仕様では、時計回り指定で `end < start` のときは 2π を足し、
/// 反時計回り指定で `end > start` のときは 2π を引く。
/// 差が 2π を超える場合は 1 周に丸める（分割数が発散しないように）。
pub fn normalize_sweep(start: f32, end: f32, anticlockwise: bool) -> f32 {
    let tau = core::f32::consts::PI * 2.0;
    let mut sweep = end - start;
    if anticlockwise {
        if sweep > 0.0 {
            sweep -= tau;
        }
        if sweep < -tau {
            sweep = -tau;
        }
    } else {
        if sweep < 0.0 {
            sweep += tau;
        }
        if sweep > tau {
            sweep = tau;
        }
    }
    sweep
}

/// 掃引角に応じた分割数（最低 1）。
pub fn arc_steps(sweep: f32) -> usize {
    let quarters = libm::fabsf(sweep) / (core::f32::consts::PI / 2.0);
    let n = (quarters * ARC_SEGMENTS_PER_QUARTER as f32) as usize;
    n.max(1)
}

// ───────────── ラスタライズ（走査線） ─────────────

/// 塗りつぶし規則。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FillRule {
    /// `nonzero`（既定）。巻き数が 0 でなければ内側。
    NonZero,
    /// `evenodd`。交差回数が奇数なら内側。
    EvenOdd,
}

/// 走査線 `y` とパスの交点を求め、塗るべき x 区間を返す（純粋関数）。
///
/// 返り値は `(x_start, x_end)` の並びで、いずれも**昇順・非重複**。
/// 閉じていない副パスも、塗りのときは仕様上「閉じているものとして」扱う。
///
/// # なぜ純粋関数にするか
///
/// 巻き数の数え方（`nonzero` と `evenodd` の違い）と、頂点をちょうど
/// 走査線が通るときの二重計上は、目視では気づけない典型的なバグ源。
/// ここを試験で固定しておけば、実際のピクセル書き込み側は
/// 「区間を塗るだけ」の単純な処理に保てる。
///
/// 計算量: **O(辺の数 log 辺の数)**（交点の整列ぶん）。
pub fn scanline_spans(subpaths: &[SubPath], y: f32, rule: FillRule) -> Vec<(f32, f32)> {
    // (x, 巻き方向) の組を集める。
    let mut hits: Vec<(f32, i32)> = Vec::new();
    for sp in subpaths {
        let n = sp.points.len();
        if n < 2 {
            continue;
        }
        // 塗りでは常に閉じたものとして扱う（最後の点と最初の点を結ぶ）。
        for i in 0..n {
            let (x0, y0) = sp.points[i];
            let (x1, y1) = sp.points[(i + 1) % n];
            if !y0.is_finite() || !y1.is_finite() || !x0.is_finite() || !x1.is_finite() {
                continue;
            }
            // 水平な辺は交差を作らない。
            if (y0 - y1).abs() < f32::EPSILON {
                continue;
            }
            // 半開区間 [min, max) で判定する。
            //
            // これをしないと、頂点をちょうど走査線が通るときに
            // 上下 2 本の辺が同じ交点を二重に数え、`evenodd` で
            // 内外が反転する（塗り残し・塗り過ぎの典型的な原因）。
            let (ylo, yhi) = if y0 < y1 { (y0, y1) } else { (y1, y0) };
            if y < ylo || y >= yhi {
                continue;
            }
            let t = (y - y0) / (y1 - y0);
            let x = x0 + t * (x1 - x0);
            // 下向きの辺を +1、上向きを -1 とする。
            let dir = if y1 > y0 { 1 } else { -1 };
            hits.push((x, dir));
        }
    }
    if hits.is_empty() {
        return Vec::new();
    }
    // x 昇順に並べる（NaN は上で除外済み）。
    hits.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(core::cmp::Ordering::Equal));

    let mut spans = Vec::new();
    match rule {
        FillRule::EvenOdd => {
            let mut i = 0;
            while i + 1 < hits.len() {
                spans.push((hits[i].0, hits[i + 1].0));
                i += 2;
            }
        }
        FillRule::NonZero => {
            let mut winding = 0i32;
            let mut start = 0.0f32;
            for &(x, dir) in &hits {
                let was_inside = winding != 0;
                winding += dir;
                let now_inside = winding != 0;
                if !was_inside && now_inside {
                    start = x;
                } else if was_inside && !now_inside {
                    spans.push((start, x));
                }
            }
        }
    }
    spans
}


// ───────────── グラデーション ─────────────

/// グラデーションのカラーストップ。
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ColorStop {
    pub offset: f32, // 0.0 ..= 1.0
    pub color: u32,  // ARGB8888
}

/// グラデーションの種別と幾何パラメータ。
#[derive(Debug, Clone, PartialEq)]
pub enum GradientKind {
    Linear {
        x0: f32,
        y0: f32,
        x1: f32,
        y1: f32,
    },
    Radial {
        x0: f32,
        y0: f32,
        r0: f32,
        x1: f32,
        y1: f32,
        r1: f32,
    },
}

/// カラーストップ配列から位置 `t`（0.0..=1.0）に対応する ARGB8888 色を線形補間する。
pub fn sample_gradient_stops(stops: &[ColorStop], t: f32) -> u32 {
    if stops.is_empty() {
        return 0; // 透明
    }
    let t = t.clamp(0.0, 1.0);
    if t <= stops[0].offset {
        return stops[0].color;
    }
    let last = &stops[stops.len() - 1];
    if t >= last.offset {
        return last.color;
    }
    for i in 0..stops.len() - 1 {
        let s0 = &stops[i];
        let s1 = &stops[i + 1];
        if t >= s0.offset && t <= s1.offset {
            let span = s1.offset - s0.offset;
            let ratio = if span > 1e-6 { (t - s0.offset) / span } else { 0.0 };
            let a0 = ((s0.color >> 24) & 0xFF) as f32;
            let r0 = ((s0.color >> 16) & 0xFF) as f32;
            let g0 = ((s0.color >> 8) & 0xFF) as f32;
            let b0 = (s0.color & 0xFF) as f32;

            let a1 = ((s1.color >> 24) & 0xFF) as f32;
            let r1 = ((s1.color >> 16) & 0xFF) as f32;
            let g1 = ((s1.color >> 8) & 0xFF) as f32;
            let b1 = (s1.color & 0xFF) as f32;

            let a = ((1.0 - ratio) * a0 + ratio * a1 + 0.5) as u32;
            let r = ((1.0 - ratio) * r0 + ratio * r1 + 0.5) as u32;
            let g = ((1.0 - ratio) * g0 + ratio * g1 + 0.5) as u32;
            let b = ((1.0 - ratio) * b0 + ratio * b1 + 0.5) as u32;

            return (a.min(255) << 24) | (r.min(255) << 16) | (g.min(255) << 8) | b.min(255);
        }
    }
    last.color
}

/// Canvas 2D のグラデーションオブジェクト。
#[derive(Debug, Clone, PartialEq)]
pub struct CanvasGradient {
    pub kind: GradientKind,
    pub stops: Vec<ColorStop>,
}

impl CanvasGradient {
    pub fn new_linear(x0: f32, y0: f32, x1: f32, y1: f32) -> Self {
        CanvasGradient {
            kind: GradientKind::Linear { x0, y0, x1, y1 },
            stops: Vec::new(),
        }
    }

    pub fn new_radial(x0: f32, y0: f32, r0: f32, x1: f32, y1: f32, r1: f32) -> Self {
        CanvasGradient {
            kind: GradientKind::Radial { x0, y0, r0, x1, y1, r1 },
            stops: Vec::new(),
        }
    }

    pub fn add_color_stop(&mut self, offset: f32, color: u32) {
        let offset = offset.clamp(0.0, 1.0);
        let stop = ColorStop { offset, color };
        let idx = self.stops.partition_point(|s| s.offset <= offset);
        self.stops.insert(idx, stop);
    }

    /// 256段の高速ルックアップテーブル（LUT）を生成する。
    pub fn build_lut(&self) -> [u32; 256] {
        let mut lut = [0u32; 256];
        if self.stops.is_empty() {
            return lut;
        }
        for i in 0..256 {
            let t = i as f32 / 255.0;
            lut[i] = sample_gradient_stops(&self.stops, t);
        }
        lut
    }

    /// 座標 (x, y) における射影パラメータ t (0.0..=1.0) を計算する。
    pub fn calculate_t(&self, x: f32, y: f32) -> f32 {
        match self.kind {
            GradientKind::Linear { x0, y0, x1, y1 } => {
                let dx = x1 - x0;
                let dy = y1 - y0;
                let len_sq = dx * dx + dy * dy;
                if len_sq < 1e-6 {
                    return 0.0;
                }
                let proj = (x - x0) * dx + (y - y0) * dy;
                (proj / len_sq).clamp(0.0, 1.0)
            }
            GradientKind::Radial { x0: _, y0: _, r0, x1, y1, r1 } => {
                let dx = x - x1;
                let dy = y - y1;
                let dist = libm::sqrtf(dx * dx + dy * dy);
                let r_span = r1 - r0;
                if libm::fabsf(r_span) < 1e-6 {
                    return 0.0;
                }
                ((dist - r0) / r_span).clamp(0.0, 1.0)
            }
        }
    }
}


// ───────────── パターン ─────────────

/// `createPattern` のリピート方式。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Repetition {
    Repeat,
    RepeatX,
    RepeatY,
    NoRepeat,
}

/// 文字列から `Repetition` を判定する（仕様上、大文字小文字無視、空文字や未知の値は Repeat）。
pub fn parse_repetition(s: &str) -> Repetition {
    let s = s.trim();
    if s.is_empty() {
        return Repetition::Repeat;
    }
    if s.eq_ignore_ascii_case("repeat") {
        Repetition::Repeat
    } else if s.eq_ignore_ascii_case("repeat-x") {
        Repetition::RepeatX
    } else if s.eq_ignore_ascii_case("repeat-y") {
        Repetition::RepeatY
    } else if s.eq_ignore_ascii_case("no-repeat") {
        Repetition::NoRepeat
    } else {
        Repetition::Repeat
    }
}

/// Canvas 2D のパターンオブジェクト。
#[derive(Debug, Clone, PartialEq)]
pub struct CanvasPattern {
    pub width: u32,
    pub height: u32,
    pub pixels: Vec<u32>,
    pub repetition: Repetition,
    pub transform: Matrix,
}

impl CanvasPattern {
    pub fn new(width: u32, height: u32, pixels: Vec<u32>, repetition: Repetition) -> Self {
        CanvasPattern {
            width,
            height,
            pixels,
            repetition,
            transform: Matrix::identity(),
        }
    }

    pub fn set_transform(&mut self, m: Matrix) {
        self.transform = m;
    }

    /// 座標 (x, y) におけるピクセル色 (ARGB8888) をサンプリングする。
    /// 範囲外（no-repeat等）は 0（透明）を返す。
    pub fn sample(&self, x: f32, y: f32) -> u32 {
        if self.width == 0 || self.height == 0 || self.pixels.is_empty() {
            return 0;
        }
        let (u, v) = if let Some(inv) = self.transform.invert() {
            inv.apply(x, y)
        } else {
            (x, y)
        };
        let w = self.width as i32;
        let h = self.height as i32;

        let (ix, iy) = match self.repetition {
            Repetition::Repeat => (
                (libm::floorf(u) as i32).rem_euclid(w),
                (libm::floorf(v) as i32).rem_euclid(h),
            ),
            Repetition::RepeatX => {
                let y_int = libm::floorf(v) as i32;
                if y_int < 0 || y_int >= h {
                    return 0;
                }
                ((libm::floorf(u) as i32).rem_euclid(w), y_int)
            }
            Repetition::RepeatY => {
                let x_int = libm::floorf(u) as i32;
                if x_int < 0 || x_int >= w {
                    return 0;
                }
                (x_int, (libm::floorf(v) as i32).rem_euclid(h))
            }
            Repetition::NoRepeat => {
                let x_int = libm::floorf(u) as i32;
                let y_int = libm::floorf(v) as i32;
                if x_int < 0 || x_int >= w || y_int < 0 || y_int >= h {
                    return 0;
                }
                (x_int, y_int)
            }
        };

        let idx = (iy as usize) * (self.width as usize) + (ix as usize);
        self.pixels.get(idx).copied().unwrap_or(0)
    }
}


// ───────────── バッキングストアへの描画 ─────────────

/// Canvas のバッキングストア（ARGB8888 のピクセル配列）。
///
/// 画面へ直接描かず、まずここへ描く。`<canvas>` は
/// 「レイアウトで決まった矩形へ、自分のピクセルを貼る」要素なので、
/// 画面座標ではなく**キャンバス内座標**で完結させる必要がある。
#[derive(Debug, Clone)]
pub struct Surface {
    pub width: u32,
    pub height: u32,
    /// 長さは `width * height`。各要素は 0xAARRGGBB。
    pub pixels: Vec<u32>,
    /// 有効なクリップ領域。`None` なら全面に描ける。
    ///
    /// 状態側（`DrawState`）が持ち主で、描画の直前に `sync_clip` で写す。
    /// 塗りの実装すべてが最後は `blend_pixel` を通るので、
    /// ここで一度だけ見れば経路の取りこぼしが起きない。
    pub clip: Option<alloc::sync::Arc<ClipMask>>,
}

impl Surface {
    /// 透明で初期化した面を作る。
    ///
    /// 面積が過大な場合は `None`（ヒープを食い潰さないための上限）。
    /// 実サイトの canvas は大きくても数千×数千なので、
    /// 4096×4096（約 64MB）を上限とする。
    pub fn new(width: u32, height: u32) -> Option<Self> {
        const MAX_SIDE: u32 = 4096;
        if width == 0 || height == 0 || width > MAX_SIDE || height > MAX_SIDE {
            return None;
        }
        let n = (width as usize).checked_mul(height as usize)?;
        Some(Surface {
            width,
            height,
            pixels: alloc::vec![0u32; n],
            clip: None,
        })
    }

    /// 指定座標のピクセル（0xAARRGGBB）を返す。範囲外は 0（透明）。
    pub fn get_pixel(&self, x: i32, y: i32) -> u32 {
        if x < 0 || y < 0 || x as u32 >= self.width || y as u32 >= self.height {
            return 0;
        }
        let idx = y as usize * self.width as usize + x as usize;
        self.pixels[idx]
    }

    /// 1 ピクセルを source-over で合成する。範囲外は黙って無視する。
    pub fn blend_pixel(&mut self, x: i32, y: i32, argb: u32) {
        if x < 0 || y < 0 || x as u32 >= self.width || y as u32 >= self.height {
            return;
        }
        if let Some(c) = &self.clip {
            if !c.allows(x, y) {
                return;
            }
        }
        let a = (argb >> 24) & 0xFF;
        if a == 0 {
            return;
        }
        let idx = y as usize * self.width as usize + x as usize;
        if a == 255 {
            self.pixels[idx] = argb;
            return;
        }
        let dst = self.pixels[idx];
        let inv = 255 - a;
        // source-over: out = src + dst * (1 - srcA)
        let da = (dst >> 24) & 0xFF;
        let out_a = a + da * inv / 255;
        let mix = |shift: u32| -> u32 {
            let s = (argb >> shift) & 0xFF;
            let d = (dst >> shift) & 0xFF;
            (s * a + d * inv) / 255
        };
        self.pixels[idx] =
            (out_a.min(255) << 24) | (mix(16) << 16) | (mix(8) << 8) | mix(0);
    }

    /// 矩形を塗りつぶす（`clearRect` は `argb=0` かつ `replace=true` で使う）。
    ///
    /// `replace` が真なら合成せず上書きする（`clearRect` の意味論）。
    pub fn fill_rect(&mut self, x: i32, y: i32, w: i32, h: i32, argb: u32, replace: bool) {
        mark_canvas_dirty();
        if w <= 0 || h <= 0 {
            return;
        }
        let x0 = x.max(0);
        let y0 = y.max(0);
        let x1 = (x.saturating_add(w)).min(self.width as i32);
        let y1 = (y.saturating_add(h)).min(self.height as i32);
        for py in y0..y1 {
            for px in x0..x1 {
                if replace {
                    // `clearRect` も合成を飛ばすだけで、クリップは効く（仕様）。
                    // ここは `blend_pixel` を通らないので個別に見る。
                    if let Some(c) = &self.clip {
                        if !c.allows(px, py) {
                            continue;
                        }
                    }
                    let idx = py as usize * self.width as usize + px as usize;
                    self.pixels[idx] = argb;
                } else {
                    self.blend_pixel(px, py, argb);
                }
            }
        }
    }

    /// パスを塗りつぶす。
    ///
    /// 走査線はピクセル中心（`y + 0.5`）で判定する。境界ちょうどの
    /// 走査線を使うと、隣り合う図形の継ぎ目に隙間や二重塗りが出る。
    pub fn fill_path(&mut self, subpaths: &[SubPath], rule: FillRule, argb: u32) {
        mark_canvas_dirty();
        if subpaths.is_empty() {
            return;
        }
        // 走査する y 範囲をパスの境界から絞る（全面走査を避ける）。
        let (mut ymin, mut ymax) = (f32::MAX, f32::MIN);
        for sp in subpaths {
            for &(_, py) in &sp.points {
                if py.is_finite() {
                    ymin = ymin.min(py);
                    ymax = ymax.max(py);
                }
            }
        }
        if ymin > ymax {
            return;
        }
        let y_start = (libm::floorf(ymin) as i32).max(0);
        let y_end = (libm::ceilf(ymax) as i32).min(self.height as i32);
        for py in y_start..y_end {
            let spans = scanline_spans(subpaths, py as f32 + 0.5, rule);
            for (sx, ex) in spans {
                // 区間の両端はピクセル境界へ丸める。
                let x0 = (libm::roundf(sx) as i32).max(0);
                let x1 = (libm::roundf(ex) as i32).min(self.width as i32);
                for px in x0..x1 {
                    self.blend_pixel(px, py, argb);
                }
            }
        }
    }

    /// パスをグラデーション（線形または円形）で塗りつぶす。
    pub fn fill_path_gradient(
        &mut self,
        subpaths: &[SubPath],
        rule: FillRule,
        gradient: &CanvasGradient,
        alpha_multiplier: f32,
    ) {
        mark_canvas_dirty();
        if subpaths.is_empty() || gradient.stops.is_empty() {
            return;
        }
        let lut = gradient.build_lut();
        let (mut ymin, mut ymax) = (f32::MAX, f32::MIN);
        for sp in subpaths {
            for &(_, py) in &sp.points {
                if py.is_finite() {
                    ymin = ymin.min(py);
                    ymax = ymax.max(py);
                }
            }
        }
        if ymin > ymax {
            return;
        }
        let y_start = (libm::floorf(ymin) as i32).max(0);
        let y_end = (libm::ceilf(ymax) as i32).min(self.height as i32);

        match gradient.kind {
            GradientKind::Linear { x0, y0, x1, y1 } => {
                let dx = x1 - x0;
                let dy = y1 - y0;
                let len_sq = dx * dx + dy * dy;
                let (cx, cy, c_base) = if len_sq >= 1e-6 {
                    let inv = 1.0 / len_sq;
                    (dx * inv, dy * inv, -(x0 * dx + y0 * dy) * inv)
                } else {
                    (0.0, 0.0, 0.0)
                };

                for py in y_start..y_end {
                    let y_mid = py as f32 + 0.5;
                    let t_row_base = c_base + cy * y_mid;
                    let spans = scanline_spans(subpaths, y_mid, rule);
                    for (sx, ex) in spans {
                        let px0 = (libm::roundf(sx) as i32).max(0);
                        let px1 = (libm::roundf(ex) as i32).min(self.width as i32);
                        for px in px0..px1 {
                            let x_mid = px as f32 + 0.5;
                            let t = (t_row_base + cx * x_mid).clamp(0.0, 1.0);
                            let lut_idx = (t * 255.0 + 0.5) as usize;
                            let mut color = lut[lut_idx.min(255)];
                            if alpha_multiplier < 1.0 {
                                let a = (((color >> 24) & 0xFF) as f32 * alpha_multiplier + 0.5) as u32;
                                color = (a.min(255) << 24) | (color & 0x00FF_FFFF);
                            }
                            self.blend_pixel(px, py, color);
                        }
                    }
                }
            }
            GradientKind::Radial { .. } => {
                for py in y_start..y_end {
                    let y_mid = py as f32 + 0.5;
                    let spans = scanline_spans(subpaths, y_mid, rule);
                    for (sx, ex) in spans {
                        let px0 = (libm::roundf(sx) as i32).max(0);
                        let px1 = (libm::roundf(ex) as i32).min(self.width as i32);
                        for px in px0..px1 {
                            let x_mid = px as f32 + 0.5;
                            let t = gradient.calculate_t(x_mid, y_mid);
                            let lut_idx = (t * 255.0 + 0.5) as usize;
                            let mut color = lut[lut_idx.min(255)];
                            if alpha_multiplier < 1.0 {
                                let a = (((color >> 24) & 0xFF) as f32 * alpha_multiplier + 0.5) as u32;
                                color = (a.min(255) << 24) | (color & 0x00FF_FFFF);
                            }
                            self.blend_pixel(px, py, color);
                        }
                    }
                }
            }
        }
    }

    /// パスをパターン（タイリング画像）で塗りつぶす。
    pub fn fill_path_pattern(
        &mut self,
        subpaths: &[SubPath],
        rule: FillRule,
        pattern: &CanvasPattern,
        alpha_multiplier: f32,
    ) {
        mark_canvas_dirty();
        if subpaths.is_empty() || pattern.width == 0 || pattern.height == 0 || pattern.pixels.is_empty() {
            return;
        }
        let (mut ymin, mut ymax) = (f32::MAX, f32::MIN);
        for sp in subpaths {
            for &(_, py) in &sp.points {
                if py.is_finite() {
                    ymin = ymin.min(py);
                    ymax = ymax.max(py);
                }
            }
        }
        if ymin > ymax {
            return;
        }
        let y_start = (libm::floorf(ymin) as i32).max(0);
        let y_end = (libm::ceilf(ymax) as i32).min(self.height as i32);

        for py in y_start..y_end {
            let y_mid = py as f32 + 0.5;
            let spans = scanline_spans(subpaths, y_mid, rule);
            for (sx, ex) in spans {
                let px0 = (libm::roundf(sx) as i32).max(0);
                let px1 = (libm::roundf(ex) as i32).min(self.width as i32);
                for px in px0..px1 {
                    let x_mid = px as f32 + 0.5;
                    let color = pattern.sample(x_mid, y_mid);
                    let a = (color >> 24) & 0xFF;
                    if a == 0 {
                        continue;
                    }
                    let final_color = if alpha_multiplier < 1.0 {
                        let final_a = libm::roundf(a as f32 * alpha_multiplier).clamp(0.0, 255.0) as u32;
                        (final_a << 24) | (color & 0x00FF_FFFF)
                    } else {
                        color
                    };
                    self.blend_pixel(px, py, final_color);
                }
            }
        }
    }

    /// 折れ線を線幅 1 で描く（`stroke` の最小実装）。
    ///
    /// 線幅・線端・線結合は未対応。まず「線が見える」ところまでを担保する。
    pub fn stroke_path(&mut self, subpaths: &[SubPath], argb: u32) {
        mark_canvas_dirty();
        for sp in subpaths {
            let n = sp.points.len();
            if n < 2 {
                continue;
            }
            let last = if sp.closed { n } else { n - 1 };
            for i in 0..last {
                let (x0, y0) = sp.points[i];
                let (x1, y1) = sp.points[(i + 1) % n];
                self.draw_line(x0, y0, x1, y1, argb);
            }
        }
    }

    /// Bresenham で線分を引く。非有限座標は無視する。
    fn draw_line(&mut self, x0: f32, y0: f32, x1: f32, y1: f32, argb: u32) {
        if !x0.is_finite() || !y0.is_finite() || !x1.is_finite() || !y1.is_finite() {
            return;
        }
        let mut x = libm::roundf(x0) as i32;
        let mut y = libm::roundf(y0) as i32;
        let xe = libm::roundf(x1) as i32;
        let ye = libm::roundf(y1) as i32;
        let dx = (xe - x).abs();
        let dy = -(ye - y).abs();
        let sx = if x < xe { 1 } else { -1 };
        let sy = if y < ye { 1 } else { -1 };
        let mut err = dx + dy;
        // 上限を設けて、万一の座標異常でも無限ループにしない。
        let mut guard = 0i32;
        let limit = (self.width as i32 + self.height as i32) * 4 + 16;
        loop {
            self.blend_pixel(x, y, argb);
            if (x == xe && y == ye) || guard > limit {
                break;
            }
            guard += 1;
            let e2 = err * 2;
            if e2 >= dy {
                err += dy;
                x += sx;
            }
            if e2 <= dx {
                err += dx;
                y += sy;
            }
        }
    }
}


// ───────────── 2D コンテキストの状態 ─────────────

/// `save()`/`restore()` で退避・復帰する描画状態。
#[derive(Debug, Clone)]
pub struct DrawState {
    pub transform: Matrix,
    /// 塗り色（ARGB8888）。
    pub fill: u32,
    /// 塗り色の文字列表現（例: "#000000", "red"）。
    pub fill_str: alloc::string::String,
    /// 線色（ARGB8888）。
    pub stroke: u32,
    /// 線色の文字列表現。
    pub stroke_str: alloc::string::String,
    pub line_width: f32,
    /// `lineCap`。
    pub line_cap: LineCap,
    /// `lineJoin`。
    pub line_join: LineJoin,
    /// `miterLimit`。
    pub miter_limit: f32,
    /// `setLineDash` のパターン。空なら実線。
    pub line_dash: Vec<f32>,
    /// `lineDashOffset`。
    pub line_dash_offset: f32,
    /// クリップ領域。`None` なら全面。
    pub clip: Option<alloc::sync::Arc<ClipMask>>,
    /// `globalAlpha`（0.0〜1.0）。
    pub global_alpha: f32,
    /// フォント指定文字列（例: "10px sans-serif"）。
    pub font_str: alloc::string::String,
    /// 水平揃え文字列（例: "start"）。
    pub text_align_str: alloc::string::String,
    /// 垂直ベースライン文字列（例: "alphabetic"）。
    pub text_baseline_str: alloc::string::String,
    /// 画像平滑化有効フラグ（imageSmoothingEnabled）。
    pub image_smoothing_enabled: bool,
    /// 塗りグラデーション（指定時は単色 fill より優先）。
    pub fill_gradient: Option<CanvasGradient>,
    /// 線グラデーション。
    pub stroke_gradient: Option<CanvasGradient>,
    /// 塗りパターン（指定時は単色 fill より優先）。
    pub fill_pattern: Option<CanvasPattern>,
    /// 線パターン。
    pub stroke_pattern: Option<CanvasPattern>,
}

impl Default for DrawState {
    fn default() -> Self {
        DrawState {
            transform: Matrix::identity(),
            // Canvas の既定は不透明な黒。
            fill: 0xFF00_0000,
            fill_str: alloc::string::String::from("#000000"),
            stroke: 0xFF00_0000,
            stroke_str: alloc::string::String::from("#000000"),
            line_width: 1.0,
            line_cap: LineCap::Butt,
            line_join: LineJoin::Miter,
            miter_limit: DEFAULT_MITER_LIMIT,
            line_dash: Vec::new(),
            line_dash_offset: 0.0,
            clip: None,
            global_alpha: 1.0,
            font_str: alloc::string::String::from("10px sans-serif"),
            text_align_str: alloc::string::String::from("start"),
            text_baseline_str: alloc::string::String::from("alphabetic"),
            image_smoothing_enabled: true,
            fill_gradient: None,
            stroke_gradient: None,
            fill_pattern: None,
            stroke_pattern: None,
        }
    }
}

/// 1 つの `<canvas>` に対する 2D コンテキストの全状態。
///
/// JS 側のオブジェクトは軽いハンドルだけを持ち、実体はこれを指す。
/// パスと面はどちらもここに持たせて、描画の途中経過が
/// JS オブジェクトの寿命に左右されないようにする。
#[derive(Debug)]
pub struct Canvas2dContext {
    pub surface: Surface,
    pub path: PathBuilder,
    pub state: DrawState,
    /// `save()` の退避スタック。
    stack: Vec<DrawState>,
}

/// `save()` の入れ子上限。
///
/// 際限なく積むと、壊れた（`restore` を呼ばない）スクリプトで
/// ヒープを食い潰す。実用上 32 段もあれば足りる。
const MAX_SAVE_DEPTH: usize = 32;

impl Canvas2dContext {
    pub fn new(width: u32, height: u32) -> Option<Self> {
        Some(Canvas2dContext {
            surface: Surface::new(width, height)?,
            path: PathBuilder::new(),
            state: DrawState::default(),
            stack: Vec::new(),
        })
    }

    /// 現在の状態を退避する。上限を超えたら黙って無視する
    /// （`restore` との対応が崩れるが、落ちるよりはよい）。
    pub fn save(&mut self) {
        if self.stack.len() >= MAX_SAVE_DEPTH {
            return;
        }
        self.stack.push(self.state.clone());
    }

    /// 直近の退避状態へ戻す。スタックが空なら何もしない
    /// （仕様どおり。`restore` の呼び過ぎはエラーではない）。
    pub fn restore(&mut self) {
        if let Some(s) = self.stack.pop() {
            self.state = s;
        }
    }

    /// `globalAlpha` を適用した色を返す。
    ///
    /// アルファは掛け算で合成する。`globalAlpha=0.5` の半透明色は
    /// さらに薄くなる（仕様どおり）。
    pub fn apply_alpha(&self, argb: u32) -> u32 {
        let ga = self.state.global_alpha.clamp(0.0, 1.0);
        if ga >= 1.0 {
            return argb;
        }
        let a = ((argb >> 24) & 0xFF) as f32 * ga;
        let a = libm::roundf(a).clamp(0.0, 255.0) as u32;
        (a << 24) | (argb & 0x00FF_FFFF)
    }

    /// 現在の変換を適用して矩形を塗る。
    ///
    /// 変換が平行移動と拡大だけなら矩形のまま塗れるが、回転が入ると
    /// 軸平行でなくなる。判定を分けず、常にパス経由で塗ることで
    /// 回転時も正しくなるようにしている。
    pub fn fill_rect(&mut self, x: f32, y: f32, w: f32, h: f32) {
        self.sync_clip();
        let mut p = PathBuilder::new();
        p.rect(&self.state.transform, x, y, w, h);
        let sub = p.finish();
        if let Some(ref grad) = self.state.fill_gradient {
            self.surface.fill_path_gradient(&sub, FillRule::NonZero, grad, self.state.global_alpha.clamp(0.0, 1.0));
        } else if let Some(ref pat) = self.state.fill_pattern {
            self.surface.fill_path_pattern(&sub, FillRule::NonZero, pat, self.state.global_alpha.clamp(0.0, 1.0));
        } else {
            let color = self.apply_alpha(self.state.fill);
            self.surface.fill_path(&sub, FillRule::NonZero, color);
        }
    }

    /// 矩形を透明で消す。`globalAlpha` の影響は受けない（仕様どおり）。
    ///
    /// 回転が入っていると軸平行に消せないため、パスの外接矩形を消す。
    /// 厳密ではないが、`clearRect` に回転を掛ける使い方は稀。
    pub fn clear_rect(&mut self, x: f32, y: f32, w: f32, h: f32) {
        self.sync_clip();
        let m = &self.state.transform;
        let pts = [
            m.apply(x, y),
            m.apply(x + w, y),
            m.apply(x + w, y + h),
            m.apply(x, y + h),
        ];
        let (mut x0, mut y0, mut x1, mut y1) = (f32::MAX, f32::MAX, f32::MIN, f32::MIN);
        for (px, py) in pts {
            if !px.is_finite() || !py.is_finite() {
                return;
            }
            x0 = x0.min(px);
            y0 = y0.min(py);
            x1 = x1.max(px);
            y1 = y1.max(py);
        }
        self.surface.fill_rect(
            libm::floorf(x0) as i32,
            libm::floorf(y0) as i32,
            libm::ceilf(x1 - x0) as i32,
            libm::ceilf(y1 - y0) as i32,
            0,
            true,
        );
    }

    /// 現在のパスを塗る。
    pub fn fill(&mut self, rule: FillRule) {
        self.sync_clip();
        let sub = self.path.finish();
        if let Some(ref grad) = self.state.fill_gradient {
            self.surface.fill_path_gradient(&sub, rule, grad, self.state.global_alpha.clamp(0.0, 1.0));
        } else if let Some(ref pat) = self.state.fill_pattern {
            self.surface.fill_path_pattern(&sub, rule, pat, self.state.global_alpha.clamp(0.0, 1.0));
        } else {
            let color = self.apply_alpha(self.state.fill);
            self.surface.fill_path(&sub, rule, color);
        }
    }

    /// 現在のパスを線描する。
    pub fn stroke(&mut self) {
        self.sync_clip();
        let color = self.apply_alpha(self.state.stroke);
        let sub = self.path.finish();
        self.surface.stroke_path(&sub, color);
    }

    /// 現在の変換へ平行移動を積む。
    pub fn translate(&mut self, tx: f32, ty: f32) {
        self.state.transform = self.state.transform.multiply(&Matrix::translate(tx, ty));
    }

    /// 現在の変換へ拡大縮小を積む。
    pub fn scale(&mut self, sx: f32, sy: f32) {
        self.state.transform = self.state.transform.multiply(&Matrix::scale(sx, sy));
    }

    /// 現在の変換へ回転を積む。
    pub fn rotate(&mut self, rad: f32) {
        self.state.transform = self.state.transform.multiply(&Matrix::rotate(rad));
    }

    /// 変換行列を直接置き換える（`setTransform`）。
    pub fn set_transform(&mut self, m: Matrix) {
        self.state.transform = m;
    }

    /// 変換を単位行列へ戻す（`resetTransform`）。
    pub fn reset_transform(&mut self) {
        self.state.transform = Matrix::identity();
    }
}


// ───────────── コンテキスト登録表 ─────────────

/// `<canvas>` ごとの 2D コンテキストを id で保持する表。
///
/// JS 側のオブジェクトは `ObjKind::Host("canvas2d:<id>")` というタグだけを
/// 持ち、実体はここにある。JS の値へ Rust の可変状態を直接埋めると
/// 借用と寿命の扱いが複雑になるため、既存の DOM プロキシ（style/classList）
/// と同じ「タグで引く」流儀に合わせた。
static CONTEXTS: spin::Mutex<alloc::collections::BTreeMap<u32, Canvas2dContext>> =
    spin::Mutex::new(alloc::collections::BTreeMap::new());

/// 次に払い出す id。
static NEXT_ID: core::sync::atomic::AtomicU32 = core::sync::atomic::AtomicU32::new(1);

/// 同時に保持するコンテキスト数の上限。
///
/// ページ遷移のたびに増え続けると、面（最大 64MB）が積み上がって
/// ヒープを食い潰す。上限を超えたら最も古い id から捨てる。
const MAX_CONTEXTS: usize = 8;

/// 新しいコンテキストを作り、その id を返す。
///
/// 面が確保できない（サイズが不正・過大）場合は `None`。
pub fn create_context(width: u32, height: u32) -> Option<u32> {
    let ctx = Canvas2dContext::new(width, height)?;
    let id = NEXT_ID.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
    let mut map = CONTEXTS.lock();
    // 上限を超えたら最も古い（id が小さい）ものから捨てる。
    while map.len() >= MAX_CONTEXTS {
        let Some(&oldest) = map.keys().next() else {
            break;
        };
        map.remove(&oldest);
    }
    map.insert(id, ctx);
    Some(id)
}

/// id のコンテキストへ可変アクセスする。
///
/// 見つからなければ `f` を呼ばず `None` を返す（ページ遷移で
/// 破棄された後の呼び出しは黙って無視する）。
pub fn with_context<R>(id: u32, f: impl FnOnce(&mut Canvas2dContext) -> R) -> Option<R> {
    let mut map = CONTEXTS.lock();
    map.get_mut(&id).map(f)
}

/// 保持している全コンテキストを破棄する（ページ遷移時に呼ぶ）。
pub fn clear_contexts() {
    CONTEXTS.lock().clear();
}

/// `ObjKind::Host` のタグ文字列から id を取り出す。
///
/// 形式は `canvas2d:<id>`。合致しなければ `None`。
pub fn id_from_tag(tag: &str) -> Option<u32> {
    tag.strip_prefix("canvas2d:")?.parse::<u32>().ok()
}

/// id からタグ文字列を作る。
pub fn tag_for_id(id: u32) -> alloc::string::String {
    alloc::format!("canvas2d:{}", id)
}

impl PathBuilder {
    /// 楕円弧（`ellipse`）。
    ///
    /// `arc` の一般形で、x/y に別々の半径と、楕円自体の回転を持つ。
    /// 単位円上の点を「半径で伸ばす → 回転する → 中心へ移す」順で写す。
    /// この順序を取り違えると、回転した楕円が歪む。
    #[allow(clippy::too_many_arguments)]
    pub fn ellipse(
        &mut self,
        m: &Matrix,
        cx: f32,
        cy: f32,
        rx: f32,
        ry: f32,
        rotation: f32,
        start: f32,
        end: f32,
        anticlockwise: bool,
    ) {
        if !rx.is_finite()
            || !ry.is_finite()
            || rx < 0.0
            || ry < 0.0
            || !start.is_finite()
            || !end.is_finite()
            || !rotation.is_finite()
        {
            return;
        }
        let sweep = normalize_sweep(start, end, anticlockwise);
        let steps = arc_steps(sweep);
        let (rs, rc) = (libm::sinf(rotation), libm::cosf(rotation));
        for i in 0..=steps {
            let t = i as f32 / steps as f32;
            let ang = start + sweep * t;
            // 単位円 → 半径で伸ばす
            let ux = rx * libm::cosf(ang);
            let uy = ry * libm::sinf(ang);
            // → 楕円の回転 → 中心へ移す
            let px = cx + ux * rc - uy * rs;
            let py = cy + ux * rs + uy * rc;
            if i == 0 && self.current.is_none() {
                self.move_to(m, px, py);
            } else {
                self.line_to(m, px, py);
            }
        }
    }

    /// 角丸矩形（`roundRect`）。
    ///
    /// 半径は 4 隅ぶん（左上・右上・右下・左下）。
    /// 半径の合計が辺の長さを超える場合は、仕様どおり**比率を保ったまま
    /// 縮小**する。しないと角が重なって図形が破綻する。
    #[allow(clippy::too_many_arguments)]
    pub fn round_rect(
        &mut self,
        m: &Matrix,
        x: f32,
        y: f32,
        w: f32,
        h: f32,
        radii: [f32; 4],
    ) {
        if !w.is_finite() || !h.is_finite() || w == 0.0 || h == 0.0 {
            return;
        }
        // 負の幅・高さは反対側から描く（仕様）。
        let (x, w) = if w < 0.0 { (x + w, -w) } else { (x, w) };
        let (y, h) = if h < 0.0 { (y + h, -h) } else { (y, h) };

        let mut r = [0.0f32; 4];
        for (i, v) in radii.iter().enumerate() {
            r[i] = if v.is_finite() && *v > 0.0 { *v } else { 0.0 };
        }
        // 辺ごとに「両端の半径の和」が辺長を超えないよう縮小率を求める。
        let mut scale = 1.0f32;
        let pairs = [
            (r[0] + r[1], w), // 上辺: 左上 + 右上
            (r[2] + r[3], w), // 下辺: 右下 + 左下
            (r[1] + r[2], h), // 右辺: 右上 + 右下
            (r[3] + r[0], h), // 左辺: 左下 + 左上
        ];
        for (sum, len) in pairs {
            if sum > 0.0 && sum > len {
                scale = scale.min(len / sum);
            }
        }
        for v in r.iter_mut() {
            *v *= scale;
        }

        let half_pi = core::f32::consts::PI / 2.0;
        let pi = core::f32::consts::PI;
        self.flush();
        // 左上から時計回りに、直線 → 角の 1/4 円 を繰り返す。
        self.move_to(m, x + r[0], y);
        self.line_to(m, x + w - r[1], y);
        if r[1] > 0.0 {
            self.arc(m, x + w - r[1], y + r[1], r[1], -half_pi, 0.0, false);
        }
        self.line_to(m, x + w, y + h - r[2]);
        if r[2] > 0.0 {
            self.arc(m, x + w - r[2], y + h - r[2], r[2], 0.0, half_pi, false);
        }
        self.line_to(m, x + r[3], y + h);
        if r[3] > 0.0 {
            self.arc(m, x + r[3], y + h - r[3], r[3], half_pi, pi, false);
        }
        self.line_to(m, x, y + r[0]);
        if r[0] > 0.0 {
            self.arc(m, x + r[0], y + r[0], r[0], pi, pi + half_pi, false);
        }
        self.close_path();
    }
}

impl Surface {
    /// 線幅つきで折れ線を描く。
    ///
    /// 各線分を「線幅ぶんの太さを持つ四角形」に展開して塗る。
    /// 線端・線結合（`lineCap`/`lineJoin`）は未対応で、
    /// 結合部には円を置いて隙間を埋める（`round` 相当の近似）。
    ///
    /// # なぜ四角形へ展開するか
    ///
    /// Bresenham を平行にずらして何本も引く方法は、斜線で
    /// 太さが不均一になる（見た目が痩せる）。線分に垂直な方向へ
    /// 幅の半分ずつ広げた四角形を塗れば、角度によらず一定の太さになる。
    /// 線幅つきで折れ線を描く（線端 `Butt`・結合 `Round`）。
    ///
    /// 線端・結合を選ぶ場合は `stroke_path_styled` を使う。
    pub fn stroke_path_width(&mut self, subpaths: &[SubPath], argb: u32, width: f32) {
        self.stroke_path_styled(
            subpaths,
            argb,
            width,
            LineCap::Butt,
            LineJoin::Round,
            DEFAULT_MITER_LIMIT,
        );
    }

    /// 中心 (cx, cy)・半径 r の円を塗る（線の結合部を埋めるのに使う）。
    fn fill_disc(&mut self, cx: f32, cy: f32, r: f32, argb: u32) {
        if !cx.is_finite() || !cy.is_finite() || !r.is_finite() || r <= 0.0 {
            return;
        }
        let y0 = (libm::floorf(cy - r) as i32).max(0);
        let y1 = (libm::ceilf(cy + r) as i32).min(self.height as i32);
        let r2 = r * r;
        for py in y0..y1 {
            let dy = py as f32 + 0.5 - cy;
            let d = r2 - dy * dy;
            if d < 0.0 {
                continue;
            }
            let dx = libm::sqrtf(d);
            let x0 = (libm::roundf(cx - dx) as i32).max(0);
            let x1 = (libm::roundf(cx + dx) as i32).min(self.width as i32);
            for px in x0..x1 {
                self.blend_pixel(px, py, argb);
            }
        }
    }
}

impl Canvas2dContext {
    /// 現在のパスを、`lineWidth` を反映して線描する。
    pub fn stroke_with_width(&mut self) {
        self.sync_clip();
        let color = self.apply_alpha(self.state.stroke);
        let w = self.state.line_width;
        let (cap, join, limit) = (
            self.state.line_cap,
            self.state.line_join,
            self.state.miter_limit,
        );
        let sub = self.path.finish();
        let sub = self.apply_dash(&sub);
        self.surface
            .stroke_path_styled(&sub, color, w, cap, join, limit);
    }
}

/// 線端の形状（`lineCap`）。
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum LineCap {
    /// 端点で切り落とす（既定）。
    Butt,
    /// 端点に半円を付ける。
    Round,
    /// 端点から線幅の半分だけ四角く伸ばす。
    Square,
}

/// 線の結合形状（`lineJoin`）。
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum LineJoin {
    /// 外側の辺を延長して尖らせる（既定）。
    Miter,
    /// 結合点に円を置く。
    Round,
    /// 外側を直線で切り落とす。
    Bevel,
}

/// `miterLimit` の既定値。仕様どおり 10。
pub const DEFAULT_MITER_LIMIT: f32 = 10.0;

pub fn parse_line_cap(s: &str) -> Option<LineCap> {
    match s.trim() {
        "butt" => Some(LineCap::Butt),
        "round" => Some(LineCap::Round),
        "square" => Some(LineCap::Square),
        _ => None,
    }
}

pub fn parse_line_join(s: &str) -> Option<LineJoin> {
    match s.trim() {
        "miter" => Some(LineJoin::Miter),
        "round" => Some(LineJoin::Round),
        "bevel" => Some(LineJoin::Bevel),
        _ => None,
    }
}

/// 2 直線の交点。`p1` を通り向き `d1` の直線と、`p2` を通り向き `d2` の直線。
///
/// 平行（または反転）なら交点は無いので `None`。miter を延ばす先を
/// 求めるのに使い、`None` のときは bevel へ落とす。
pub fn line_intersection(
    p1: (f32, f32),
    d1: (f32, f32),
    p2: (f32, f32),
    d2: (f32, f32),
) -> Option<(f32, f32)> {
    let den = d1.0 * d2.1 - d1.1 * d2.0;
    // ほぼ平行なら交点が無限遠へ飛ぶ。閾値は目視で差が出ない範囲。
    if libm::fabsf(den) < 1e-6 {
        return None;
    }
    let t = ((p2.0 - p1.0) * d2.1 - (p2.1 - p1.1) * d2.0) / den;
    let x = p1.0 + d1.0 * t;
    let y = p1.1 + d1.1 * t;
    if !x.is_finite() || !y.is_finite() {
        return None;
    }
    Some((x, y))
}

impl Surface {
    /// 線端・結合を指定して折れ線を描く。
    ///
    /// `stroke_path_width` は端 `Butt`・結合 `Round` でこれを呼ぶ。
    pub fn stroke_path_styled(
        &mut self,
        subpaths: &[SubPath],
        argb: u32,
        width: f32,
        cap: LineCap,
        join: LineJoin,
        miter_limit: f32,
    ) {
        mark_canvas_dirty();
        // 1 以下は従来の 1px 線で足りる（見た目も速度も有利）。
        if !width.is_finite() || width <= 1.0 {
            self.stroke_path(subpaths, argb);
            return;
        }
        let half = width / 2.0;
        let limit = if miter_limit.is_finite() && miter_limit > 0.0 {
            miter_limit
        } else {
            DEFAULT_MITER_LIMIT
        };
        for sp in subpaths {
            let n = sp.points.len();
            if n < 2 {
                continue;
            }
            let seg_end = if sp.closed { n } else { n - 1 };

            // 各線分を、線分に垂直な方向へ half ずつ広げた四角形へ展開。
            for i in 0..seg_end {
                let a = sp.points[i];
                let b = sp.points[(i + 1) % n];
                let Some((dx, dy, len)) = unit_delta(a, b) else {
                    continue;
                };
                // 端が Square のときは、線分の外側へ half だけ伸ばす。
                let (mut ax, mut ay) = a;
                let (mut bx, mut by) = b;
                if cap == LineCap::Square && !sp.closed {
                    if i == 0 {
                        ax -= dx * half;
                        ay -= dy * half;
                    }
                    if i == seg_end - 1 {
                        bx += dx * half;
                        by += dy * half;
                    }
                }
                let _ = len;
                let (nx, ny) = (-dy * half, dx * half);
                self.fill_quad(
                    (ax + nx, ay + ny),
                    (bx + nx, by + ny),
                    (bx - nx, by - ny),
                    (ax - nx, ay - ny),
                    argb,
                );
            }

            // 結合部を埋める。線分の四角形だけでは外側の角が欠ける。
            let joint_from = if sp.closed { 0 } else { 1 };
            let joint_to = if sp.closed { n } else { n - 1 };
            for j in joint_from..joint_to {
                let prev = sp.points[(j + n - 1) % n];
                let cur = sp.points[j];
                let next = sp.points[(j + 1) % n];
                self.fill_joint(prev, cur, next, half, argb, join, limit);
            }

            // 端が Round なら両端に半円（円で近似）を置く。
            if cap == LineCap::Round && !sp.closed {
                let first = sp.points[0];
                let last = sp.points[n - 1];
                self.fill_disc(first.0, first.1, half, argb);
                self.fill_disc(last.0, last.1, half, argb);
            }
        }
    }

    /// 結合部 1 箇所を埋める。
    #[allow(clippy::too_many_arguments)]
    fn fill_joint(
        &mut self,
        prev: (f32, f32),
        cur: (f32, f32),
        next: (f32, f32),
        half: f32,
        argb: u32,
        join: LineJoin,
        limit: f32,
    ) {
        if join == LineJoin::Round {
            self.fill_disc(cur.0, cur.1, half, argb);
            return;
        }
        let (Some((d1x, d1y, _)), Some((d2x, d2y, _))) =
            (unit_delta(prev, cur), unit_delta(cur, next))
        else {
            return;
        };
        // 曲がる向き。外側だけを埋めれば足りる（内側は線分の四角形が覆う）。
        let cross = d1x * d2y - d1y * d2x;
        if libm::fabsf(cross) < 1e-6 {
            // まっすぐ、または折り返し。角は生じないので何もしない。
            return;
        }
        // 左法線を (-dy, dx) とすると、左折（cross>0）では外側は右。
        let s = if cross > 0.0 { -1.0f32 } else { 1.0f32 };
        let p1 = (cur.0 + s * -d1y * half, cur.1 + s * d1x * half);
        let p2 = (cur.0 + s * -d2y * half, cur.1 + s * d2x * half);

        if join == LineJoin::Miter {
            if let Some(mp) = line_intersection(p1, (d1x, d1y), p2, (d2x, d2y)) {
                let (mx, my) = (mp.0 - cur.0, mp.1 - cur.1);
                let miter_len = libm::sqrtf(mx * mx + my * my);
                // 鋭角では尖りが際限なく伸びる。仕様どおり
                // miterLength/halfWidth が上限を超えたら bevel へ落とす。
                if miter_len / half <= limit {
                    self.fill_quad(cur, p1, mp, p2, argb);
                    return;
                }
            }
        }
        // Bevel（および miter の打ち切り）。外側を直線で結ぶ三角形。
        self.fill_tri(cur, p1, p2, argb);
    }

    fn fill_quad(
        &mut self,
        a: (f32, f32),
        b: (f32, f32),
        c: (f32, f32),
        d: (f32, f32),
        argb: u32,
    ) {
        for p in [a, b, c, d] {
            if !p.0.is_finite() || !p.1.is_finite() {
                return;
            }
        }
        let poly = alloc::vec![SubPath {
            points: alloc::vec![a, b, c, d],
            closed: true,
        }];
        self.fill_path(&poly, FillRule::NonZero, argb);
    }

    fn fill_tri(&mut self, a: (f32, f32), b: (f32, f32), c: (f32, f32), argb: u32) {
        for p in [a, b, c] {
            if !p.0.is_finite() || !p.1.is_finite() {
                return;
            }
        }
        let poly = alloc::vec![SubPath {
            points: alloc::vec![a, b, c],
            closed: true,
        }];
        self.fill_path(&poly, FillRule::NonZero, argb);
    }
}

/// `a` から `b` への単位ベクトルと距離。長さが 0 なら `None`。
pub fn unit_delta(a: (f32, f32), b: (f32, f32)) -> Option<(f32, f32, f32)> {
    let (dx, dy) = (b.0 - a.0, b.1 - a.1);
    if !dx.is_finite() || !dy.is_finite() {
        return None;
    }
    let len = libm::sqrtf(dx * dx + dy * dy);
    if len < 1e-6 {
        return None;
    }
    Some((dx / len, dy / len, len))
}

/// JS が canvas へ描いたことを示す旗（エッジトリガ再描画用）。
///
/// canvas への描画はバッキングストア（`Surface`）を書き換えるだけで、
/// 画面には出ない。以前は「他の理由で再描画が起きたとき」にだけ
/// ついでに反映されていたため、JS が描いても画面が変わらないことがあった。
///
/// 立てっぱなしにすると毎フレーム全画面を描き直して画面が波打つので、
/// 画像完了（`image_results_ready`）と同じく**変化があった一度だけ**
/// 再描画させる。描画側が `take_canvas_dirty` で降ろす。
static CANVAS_DIRTY: core::sync::atomic::AtomicBool =
    core::sync::atomic::AtomicBool::new(false);

/// 画素が変わったことを記録する。`Surface` の塗り口から呼ぶ。
pub fn mark_canvas_dirty() {
    CANVAS_DIRTY.store(true, core::sync::atomic::Ordering::Relaxed);
}

/// 変化があったかを見る（降ろさない）。再描画するかの判断に使う。
pub fn canvas_dirty() -> bool {
    CANVAS_DIRTY.load(core::sync::atomic::Ordering::Relaxed)
}

/// 変化があったかを見て、同時に降ろす。描画を始める側から呼ぶ。
pub fn take_canvas_dirty() -> bool {
    CANVAS_DIRTY.swap(false, core::sync::atomic::Ordering::Relaxed)
}

/// 破線のパターンを正規化する（`setLineDash` の引数検査）。
///
/// 仕様では、負の値や非有限が混じるパターンは**まるごと捨てる**
/// （一部だけ直すのではない）。奇数個なら 2 周ぶんに複製して偶数個にする。
/// 全部 0 のパターンは「破線なし」と同じ扱い。
pub fn normalize_dash(pattern: &[f32]) -> Option<Vec<f32>> {
    if pattern.is_empty() {
        return None;
    }
    for v in pattern {
        if !v.is_finite() || *v < 0.0 {
            return None;
        }
    }
    if pattern.iter().all(|v| *v == 0.0) {
        return None;
    }
    let mut out: Vec<f32> = pattern.to_vec();
    // 奇数個なら繰り返して偶数個にする（仕様）。
    if out.len() % 2 == 1 {
        let dup = out.clone();
        out.extend(dup);
    }
    Some(out)
}

/// 折れ線を破線に切り分ける。
///
/// `pattern` は「描く長さ・空ける長さ」の交互。`offset` はパターンの
/// 開始位置をずらす量（`lineDashOffset`）。戻り値は描く区間だけを集めた
/// 開いた折れ線の並びで、そのまま `stroke_path_styled` へ渡せる。
///
/// 線分の途中でパターンが切り替わるので、線分を長さで分割しながら進む。
pub fn dash_subpaths(subpaths: &[SubPath], pattern: &[f32], offset: f32) -> Vec<SubPath> {
    let Some(pat) = normalize_dash(pattern) else {
        return subpaths.to_vec();
    };
    let total: f32 = pat.iter().sum();
    if total <= 0.0 {
        return subpaths.to_vec();
    }
    let mut out: Vec<SubPath> = Vec::new();
    for sp in subpaths {
        let n = sp.points.len();
        if n < 2 {
            continue;
        }
        // パターン内の位置。offset は仕様どおり周期で巻き戻す。
        let mut phase = if offset.is_finite() {
            let m = libm::fmodf(offset, total);
            if m < 0.0 {
                m + total
            } else {
                m
            }
        } else {
            0.0
        };
        // phase がどの区間にいるか（偶数番が「描く」）。
        let mut idx = 0usize;
        while phase >= pat[idx] {
            phase -= pat[idx];
            idx = (idx + 1) % pat.len();
        }
        let mut drawing = idx % 2 == 0;
        let mut cur: Vec<(f32, f32)> = Vec::new();
        if drawing {
            cur.push(sp.points[0]);
        }

        let seg_end = if sp.closed { n } else { n - 1 };
        for i in 0..seg_end {
            let a = sp.points[i];
            let b = sp.points[(i + 1) % n];
            let Some((dx, dy, len)) = unit_delta(a, b) else {
                continue;
            };
            let mut travelled = 0.0f32;
            while travelled < len {
                // この区間の残り長。
                let remain = pat[idx] - phase;
                let step = remain.min(len - travelled);
                travelled += step;
                phase += step;
                let p = (a.0 + dx * travelled, a.1 + dy * travelled);
                if phase >= pat[idx] - 1e-6 {
                    // 区間の切り替わり。描いていたなら、ここで区切る。
                    if drawing {
                        cur.push(p);
                        if cur.len() >= 2 {
                            out.push(SubPath {
                                points: core::mem::take(&mut cur),
                                closed: false,
                            });
                        } else {
                            cur.clear();
                        }
                    } else {
                        cur.clear();
                        cur.push(p);
                    }
                    phase = 0.0;
                    idx = (idx + 1) % pat.len();
                    drawing = !drawing;
                } else if drawing {
                    // 線分の終わりで、まだ同じ区間の途中。
                    cur.push(p);
                }
            }
        }
        if drawing && cur.len() >= 2 {
            out.push(SubPath {
                points: cur,
                closed: false,
            });
        }
    }
    out
}

impl Canvas2dContext {
    /// 現在の破線設定をパスへ適用する。実線ならそのまま返す。
    pub fn apply_dash(&self, subpaths: &[SubPath]) -> Vec<SubPath> {
        if self.state.line_dash.is_empty() {
            return subpaths.to_vec();
        }
        dash_subpaths(subpaths, &self.state.line_dash, self.state.line_dash_offset)
    }
}

// ───────────── クリップ領域 ─────────────

/// クリップ領域（`clip()`）。画素ごとに「描いてよいか」を持つ。
///
/// 走査線ベースの塗りに合わせて、パスをその場でラスタライズして持つ。
/// 領域を式のまま持つと、交差のたびに判定が複雑になっていく。
#[derive(Debug, Clone)]
pub struct ClipMask {
    pub width: u32,
    pub height: u32,
    /// `true` の画素だけ描ける。長さは `width * height`。
    pub bits: Vec<bool>,
}

impl ClipMask {
    /// パスからクリップ領域を作る。塗りと同じ走査線・同じ巻き数規則を使う。
    ///
    /// 塗りとずれた判定をすると、クリップの縁に 1px の隙間や food が出る。
    pub fn from_path(width: u32, height: u32, subpaths: &[SubPath], rule: FillRule) -> ClipMask {
        let mut bits = alloc::vec![false; (width as usize) * (height as usize)];
        for y in 0..height {
            // 塗りと同じくピクセル中心で判定する。
            let spans = scanline_spans(subpaths, y as f32 + 0.5, rule);
            for (x0, x1) in spans {
                let a = (libm::ceilf(x0 - 0.5) as i32).max(0);
                let b = (libm::ceilf(x1 - 0.5) as i32).min(width as i32);
                for x in a..b {
                    bits[y as usize * width as usize + x as usize] = true;
                }
            }
        }
        ClipMask {
            width,
            height,
            bits,
        }
    }

    /// 2 つのクリップ領域の交わり。`clip()` は既存の領域を**狭める**だけで、
    /// 広げることはできない（仕様）。
    pub fn intersect(&self, other: &ClipMask) -> ClipMask {
        if self.width != other.width || self.height != other.height {
            // 大きさが食い違うことは無い想定。安全側（狭い方）へ倒す。
            return self.clone();
        }
        let bits = self
            .bits
            .iter()
            .zip(other.bits.iter())
            .map(|(a, b)| *a && *b)
            .collect();
        ClipMask {
            width: self.width,
            height: self.height,
            bits,
        }
    }

    /// その画素に描いてよいか。範囲外は描けない。
    pub fn allows(&self, x: i32, y: i32) -> bool {
        if x < 0 || y < 0 || x as u32 >= self.width || y as u32 >= self.height {
            return false;
        }
        self.bits[y as usize * self.width as usize + x as usize]
    }
}

impl Canvas2dContext {
    /// 現在のパスでクリップ領域を狭める（`clip()`）。
    ///
    /// `save`/`restore` で元に戻る。状態を複製するだけで復帰できるよう
    /// `Rc` で共有しており、色と違って**正しく戻せる**。
    pub fn clip(&mut self, rule: FillRule) {
        let sub = self.path.finish();
        if sub.is_empty() {
            return;
        }
        let mask = ClipMask::from_path(self.surface.width, self.surface.height, &sub, rule);
        let merged = match &self.state.clip {
            Some(prev) => prev.intersect(&mask),
            None => mask,
        };
        self.state.clip = Some(alloc::sync::Arc::new(merged));
    }

    /// 描画前に、現在のクリップ領域を `Surface` へ渡す。
    pub fn sync_clip(&mut self) {
        self.surface.clip = self.state.clip.clone();
    }
}

// ───────────── ImageData ─────────────

/// `Surface` の一部を `ImageData` のバイト列（RGBA8・行優先）へ取り出す。
///
/// 面の外にはみ出した部分は**透明**として埋める（仕様）。
/// はみ出しを切り詰めると、返る配列の大きさが要求と食い違ってしまう。
pub fn get_image_data(s: &Surface, x: i32, y: i32, w: i32, h: i32) -> Vec<u8> {
    if w <= 0 || h <= 0 {
        return Vec::new();
    }
    let mut out = alloc::vec![0u8; (w as usize) * (h as usize) * 4];
    for row in 0..h {
        for col in 0..w {
            let (sx, sy) = (x + col, y + row);
            if sx < 0 || sy < 0 || sx as u32 >= s.width || sy as u32 >= s.height {
                continue;
            }
            let argb = s.pixels[sy as usize * s.width as usize + sx as usize];
            let o = ((row as usize) * (w as usize) + col as usize) * 4;
            out[o] = ((argb >> 16) & 0xFF) as u8;
            out[o + 1] = ((argb >> 8) & 0xFF) as u8;
            out[o + 2] = (argb & 0xFF) as u8;
            out[o + 3] = ((argb >> 24) & 0xFF) as u8;
        }
    }
    out
}

/// `ImageData` のバイト列を `Surface` へ書き戻す。
///
/// `putImageData` は**合成しない**（上書きする）。クリップも無視する。
/// これは仕様で、`fill` 系とは意味論が違う。
pub fn put_image_data(s: &mut Surface, data: &[u8], w: i32, h: i32, x: i32, y: i32) {
    if w <= 0 || h <= 0 {
        return;
    }
    // 長さが足りない配列は、足りるぶんだけ書く（途中で落とさない）。
    mark_canvas_dirty();
    for row in 0..h {
        for col in 0..w {
            let o = ((row as usize) * (w as usize) + col as usize) * 4;
            if o + 3 >= data.len() {
                return;
            }
            let (dx, dy) = (x + col, y + row);
            if dx < 0 || dy < 0 || dx as u32 >= s.width || dy as u32 >= s.height {
                continue;
            }
            let argb = ((data[o + 3] as u32) << 24)
                | ((data[o] as u32) << 16)
                | ((data[o + 1] as u32) << 8)
                | (data[o + 2] as u32);
            s.pixels[dy as usize * s.width as usize + dx as usize] = argb;
        }
    }
}

/// canvas の大きさ変更。`<canvas width>`/`height` への代入で呼ぶ。
///
/// 仕様では、大きさを代入すると**同じ値でも**内容と描画状態が
/// まるごと初期化される。これを省くと、大きさを設定し直す定型句
/// （`canvas.width = canvas.width` による消去）が効かなくなる。
///
/// 大きさが上限を超える等で面が作れなければ何もしない（元の面を残す）。
pub fn resize_context(id: u32, width: u32, height: u32) -> bool {
    let Some(fresh) = Surface::new(width, height) else {
        return false;
    };
    mark_canvas_dirty();
    with_context(id, |c| {
        c.surface = fresh;
        c.state = DrawState::default();
        c.path = PathBuilder::new();
        c.stack.clear();
    })
    .is_some()
}

// ───────────── 画像の転送 ─────────────

/// 転送元の画素（RGBA8・行優先）。
pub struct ImageSource<'a> {
    pub width: u32,
    pub height: u32,
    pub rgba: &'a [u8],
}

impl ImageSource<'_> {
    /// 最近傍で 1 画素を読む。範囲外は透明。
    pub fn sample(&self, x: i32, y: i32) -> u32 {
        if x < 0 || y < 0 || x as u32 >= self.width || y as u32 >= self.height {
            return 0;
        }
        let o = (y as usize * self.width as usize + x as usize) * 4;
        if o + 3 >= self.rgba.len() {
            return 0;
        }
        ((self.rgba[o + 3] as u32) << 24)
            | ((self.rgba[o] as u32) << 16)
            | ((self.rgba[o + 1] as u32) << 8)
            | (self.rgba[o + 2] as u32)
    }

    /// バイリニア補間で 1 画素を読む（imageSmoothingEnabled 用）。
    pub fn sample_bilinear(&self, sxf: f32, syf: f32) -> u32 {
        let u = sxf - 0.5;
        let v = syf - 0.5;
        let x0 = libm::floorf(u) as i32;
        let y0 = libm::floorf(v) as i32;
        let x1 = x0 + 1;
        let y1 = y0 + 1;

        let fx = ((u - x0 as f32) * 256.0).clamp(0.0, 256.0) as u32;
        let fy = ((v - y0 as f32) * 256.0).clamp(0.0, 256.0) as u32;

        let c00 = self.sample(x0, y0);
        let c10 = self.sample(x1, y0);
        let c01 = self.sample(x0, y1);
        let c11 = self.sample(x1, y1);

        if c00 == c10 && c10 == c01 && c01 == c11 {
            return c00;
        }

        let w00 = (256 - fx) * (256 - fy);
        let w10 = fx * (256 - fy);
        let w01 = (256 - fx) * fy;
        let w11 = fx * fy;

        let a = (((c00 >> 24) & 0xFF) * w00
            + ((c10 >> 24) & 0xFF) * w10
            + ((c01 >> 24) & 0xFF) * w01
            + ((c11 >> 24) & 0xFF) * w11 + 32768) >> 16;

        let r = (((c00 >> 16) & 0xFF) * w00
            + ((c10 >> 16) & 0xFF) * w10
            + ((c01 >> 16) & 0xFF) * w01
            + ((c11 >> 16) & 0xFF) * w11 + 32768) >> 16;

        let g = (((c00 >> 8) & 0xFF) * w00
            + ((c10 >> 8) & 0xFF) * w10
            + ((c01 >> 8) & 0xFF) * w01
            + ((c11 >> 8) & 0xFF) * w11 + 32768) >> 16;

        let b = ((c00 & 0xFF) * w00
            + (c10 & 0xFF) * w10
            + (c01 & 0xFF) * w01
            + (c11 & 0xFF) * w11 + 32768) >> 16;

        (a.min(255) << 24) | (r.min(255) << 16) | (g.min(255) << 8) | b.min(255)
    }
}

/// 転送の指定（`drawImage` の 9 引数形に対応）。
#[derive(Debug, Clone, Copy)]
pub struct BlitSpec {
    /// 転送元の矩形。
    pub sx: f32,
    pub sy: f32,
    pub sw: f32,
    pub sh: f32,
    /// 転送先の矩形（変換前の canvas 座標）。
    pub dx: f32,
    pub dy: f32,
    pub dw: f32,
    pub dh: f32,
}

impl Surface {
    /// 画像を現在の変換のもとで転送する（`drawImage`）。
    ///
    /// # なぜ逆変換で引くか
    ///
    /// 転送元を 1 画素ずつ変換先へ「押し出す」と、拡大時に隙間が空き
    /// 回転時には縞が出る。転送先の画素ごとに**逆変換で元を引く**と、
    /// どの倍率・角度でも穴が空かない。
    ///
    /// 変換が退化している（面積 0 に潰れる）場合は何もしない。
    pub fn draw_image(&mut self, src: &ImageSource, spec: &BlitSpec, m: &Matrix, alpha: f32, smooth: bool) {
        if spec.dw == 0.0 || spec.dh == 0.0 || spec.sw == 0.0 || spec.sh == 0.0 {
            return;
        }
        for v in [
            spec.sx, spec.sy, spec.sw, spec.sh, spec.dx, spec.dy, spec.dw, spec.dh,
        ] {
            if !v.is_finite() {
                return;
            }
        }
        let Some(inv) = m.invert() else {
            return;
        };
        mark_canvas_dirty();

        // 転送先の 4 隅を変換して、走査すべき範囲を求める。
        let corners = [
            m.apply(spec.dx, spec.dy),
            m.apply(spec.dx + spec.dw, spec.dy),
            m.apply(spec.dx + spec.dw, spec.dy + spec.dh),
            m.apply(spec.dx, spec.dy + spec.dh),
        ];
        let mut x0 = corners[0].0;
        let mut x1 = corners[0].0;
        let mut y0 = corners[0].1;
        let mut y1 = corners[0].1;
        for (cx, cy) in corners.iter().skip(1) {
            x0 = x0.min(*cx);
            x1 = x1.max(*cx);
            y0 = y0.min(*cy);
            y1 = y1.max(*cy);
        }
        let px0 = (libm::floorf(x0) as i32).max(0);
        let px1 = (libm::ceilf(x1) as i32).min(self.width as i32);
        let py0 = (libm::floorf(y0) as i32).max(0);
        let py1 = (libm::ceilf(y1) as i32).min(self.height as i32);

        let a = alpha.clamp(0.0, 1.0);
        for py in py0..py1 {
            for px in px0..px1 {
                // 画素中心を逆変換して、変換前の canvas 座標へ戻す。
                let (ux, uy) = inv.apply(px as f32 + 0.5, py as f32 + 0.5);
                // 転送先の矩形の中だけを描く。
                let tx = (ux - spec.dx) / spec.dw;
                let ty = (uy - spec.dy) / spec.dh;
                if !(0.0..1.0).contains(&tx) || !(0.0..1.0).contains(&ty) {
                    continue;
                }
                // 転送元の対応位置（smooth に応じてバイリニア / 最近傍）。
                let sxf = spec.sx + tx * spec.sw;
                let syf = spec.sy + ty * spec.sh;
                let argb = if smooth {
                    src.sample_bilinear(sxf, syf)
                } else {
                    src.sample(libm::floorf(sxf) as i32, libm::floorf(syf) as i32)
                };
                if argb >> 24 == 0 {
                    continue;
                }
                let argb = if a >= 1.0 {
                    argb
                } else {
                    let na = (((argb >> 24) & 0xFF) as f32 * a) as u32;
                    (na << 24) | (argb & 0x00FF_FFFF)
                };
                self.blend_pixel(px, py, argb);
            }
        }
    }
}

// ───────────── テキスト ─────────────

/// `textAlign`。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextAlign {
    Start,
    End,
    Left,
    Right,
    Center,
}

/// `textBaseline`。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextBaseline {
    Top,
    Hanging,
    Middle,
    Alphabetic,
    Ideographic,
    Bottom,
}

pub fn parse_text_align(s: &str) -> Option<TextAlign> {
    match s.trim() {
        "start" => Some(TextAlign::Start),
        "end" => Some(TextAlign::End),
        "left" => Some(TextAlign::Left),
        "right" => Some(TextAlign::Right),
        "center" => Some(TextAlign::Center),
        _ => None,
    }
}

pub fn parse_text_baseline(s: &str) -> Option<TextBaseline> {
    match s.trim() {
        "top" => Some(TextBaseline::Top),
        "hanging" => Some(TextBaseline::Hanging),
        "middle" => Some(TextBaseline::Middle),
        "alphabetic" => Some(TextBaseline::Alphabetic),
        "ideographic" => Some(TextBaseline::Ideographic),
        "bottom" => Some(TextBaseline::Bottom),
        _ => None,
    }
}

/// 指定位置から見た、描き始めの x のずれ。
///
/// `start`/`end` は書字方向で決まる。この処理系は左から右のみ扱うので
/// `start` は `left`、`end` は `right` と同じになる。
pub fn align_offset(align: TextAlign, total_advance: f32) -> f32 {
    match align {
        TextAlign::Start | TextAlign::Left => 0.0,
        TextAlign::End | TextAlign::Right => -total_advance,
        TextAlign::Center => -total_advance / 2.0,
    }
}

/// 指定位置から見た、ベースラインの y のずれ。
///
/// 字形はベースライン基準で置かれるので、`top` 指定なら
/// ベースラインを下げる（正の向きへずらす）。
/// 比率はこの処理系の字形配置（アセンダ 0.85）に合わせた近似で、
/// フォントごとの実測値ではない。
pub fn baseline_offset(baseline: TextBaseline, size_px: f32) -> f32 {
    match baseline {
        TextBaseline::Alphabetic => 0.0,
        TextBaseline::Top => size_px * 0.85,
        TextBaseline::Hanging => size_px * 0.8,
        TextBaseline::Middle => size_px * 0.35,
        TextBaseline::Ideographic | TextBaseline::Bottom => -size_px * 0.15,
    }
}

/// `font` から文字の大きさ（px）を取り出す。
///
/// CSS の `font` 一括指定は語順が自由なので、**`px` で終わる数値**を
/// 探す。`pt`/`em` 等は換算せず、見つからなければ `None`
/// （呼び出し側が既定の 10px を使う）。
pub fn parse_font_size(font: &str) -> Option<f32> {
    for tok in font.split(|c: char| c.is_whitespace() || c == '/') {
        let t = tok.trim();
        let Some(num) = t.strip_suffix("px") else {
            continue;
        };
        if let Ok(v) = num.parse::<f32>() {
            if v.is_finite() && v > 0.0 {
                return Some(v);
            }
        }
    }
    None
}

/// 1 文字ぶんの字形（アルファ値のビットマップ）。
///
/// フォントの実装（`kernel::vector_font`）に依存しないよう、
/// ここでは**値として受け取る**。canvas 側を純粋に保つため。
pub struct GlyphBitmap<'a> {
    pub width: u32,
    pub height: u32,
    /// 字形の左上を、ペン位置（ベースライン左端）から見たずれ。
    pub x_offset: i32,
    pub y_offset: i32,
    /// 次の文字までの送り幅。
    pub advance: f32,
    /// 長さは `width * height`。0 は透明。
    pub alpha: &'a [u8],
}

impl Surface {
    /// 字形を 1 つ描く。
    ///
    /// 字形は軸に沿ったビットマップだが、**現在の変換の下で**置きたい。
    /// アルファを色に載せた画像として `draw_image` に通すことで、
    /// 回転・拡大も転送と同じ経路で扱える（別実装を増やさない）。
    pub fn draw_glyph(&mut self, g: &GlyphBitmap, pen_x: f32, pen_y: f32, argb: u32, m: &Matrix) {
        if g.width == 0 || g.height == 0 {
            return;
        }
        let n = (g.width as usize) * (g.height as usize);
        if g.alpha.len() < n {
            return;
        }
        let (r, gg, b) = ((argb >> 16) & 0xFF, (argb >> 8) & 0xFF, argb & 0xFF);
        let base_a = (argb >> 24) & 0xFF;
        let mut rgba = alloc::vec![0u8; n * 4];
        for i in 0..n {
            let a = (g.alpha[i] as u32 * base_a / 255) as u8;
            rgba[i * 4] = r as u8;
            rgba[i * 4 + 1] = gg as u8;
            rgba[i * 4 + 2] = b as u8;
            rgba[i * 4 + 3] = a;
        }
        let src = ImageSource {
            width: g.width,
            height: g.height,
            rgba: &rgba,
        };
        let spec = BlitSpec {
            sx: 0.0,
            sy: 0.0,
            sw: g.width as f32,
            sh: g.height as f32,
            dx: pen_x + g.x_offset as f32,
            dy: pen_y + g.y_offset as f32,
            dw: g.width as f32,
            dh: g.height as f32,
        };
        self.draw_image(&src, &spec, m, 1.0, false);
    }

    /// 字形の輪郭（ストローク）を描く。
    ///
    /// 線幅 `line_width` に応じて近傍へ輪郭マスクを膨張（dilation）させて描画する。
    pub fn draw_glyph_stroke(
        &mut self,
        g: &GlyphBitmap,
        pen_x: f32,
        pen_y: f32,
        stroke_argb: u32,
        line_width: f32,
        m: &Matrix,
    ) {
        if g.width == 0 || g.height == 0 || line_width <= 0.0 {
            return;
        }
        let n = (g.width as usize) * (g.height as usize);
        if g.alpha.len() < n {
            return;
        }
        let r = (line_width / 2.0).clamp(0.5, 4.0);
        let ir = libm::ceilf(r) as i32;
        let w = g.width as i32;
        let h = g.height as i32;

        let mut stroke_alpha = alloc::vec![0u8; n];
        for y in 0..h {
            for x in 0..w {
                let idx = (y * w + x) as usize;
                let a = g.alpha[idx];
                if a > 0 {
                    for dy in -ir..=ir {
                        for dx in -ir..=ir {
                            let dist = libm::sqrtf((dx * dx + dy * dy) as f32);
                            if dist <= r {
                                let nx = x + dx;
                                let ny = y + dy;
                                if nx >= 0 && nx < w && ny >= 0 && ny < h {
                                    let nidx = (ny * w + nx) as usize;
                                    let falloff = if r > 0.0 {
                                        (1.0 - (dist / (r + 0.5))).clamp(0.0, 1.0)
                                    } else {
                                        1.0
                                    };
                                    let strk_val = (a as f32 * falloff) as u8;
                                    if strk_val > stroke_alpha[nidx] {
                                        stroke_alpha[nidx] = strk_val;
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
        let (r_col, g_col, b_col) = (
            (stroke_argb >> 16) & 0xFF,
            (stroke_argb >> 8) & 0xFF,
            stroke_argb & 0xFF,
        );
        let base_a = (stroke_argb >> 24) & 0xFF;
        let mut rgba = alloc::vec![0u8; n * 4];
        for i in 0..n {
            let a = (stroke_alpha[i] as u32 * base_a / 255) as u8;
            rgba[i * 4] = r_col as u8;
            rgba[i * 4 + 1] = g_col as u8;
            rgba[i * 4 + 2] = b_col as u8;
            rgba[i * 4 + 3] = a;
        }
        let src = ImageSource {
            width: g.width,
            height: g.height,
            rgba: &rgba,
        };
        let spec = BlitSpec {
            sx: 0.0,
            sy: 0.0,
            sw: g.width as f32,
            sh: g.height as f32,
            dx: pen_x + g.x_offset as f32,
            dy: pen_y + g.y_offset as f32,
            dw: g.width as f32,
            dh: g.height as f32,
        };
        self.draw_image(&src, &spec, m, 1.0, false);
    }
}


// ───────────── SVG パス文字列のパース ─────────────

/// SVG パス文字列から浮動小数点数を順次読み取るトークナイザ。
struct SvgPathTokenizer<'a> {
    data: &'a [u8],
    pos: usize,
}

impl<'a> SvgPathTokenizer<'a> {
    fn new(data: &'a str) -> Self {
        Self {
            data: data.as_bytes(),
            pos: 0,
        }
    }

    fn skip_whitespace_and_comma(&mut self) {
        while self.pos < self.data.len() {
            let c = self.data[self.pos];
            if c == b' ' || c == b'\t' || c == b'\n' || c == b'\r' || c == b',' {
                self.pos += 1;
            } else {
                break;
            }
        }
    }

    fn next_cmd(&mut self) -> Option<char> {
        self.skip_whitespace_and_comma();
        if self.pos >= self.data.len() {
            return None;
        }
        let c = self.data[self.pos] as char;
        if c.is_ascii_alphabetic() {
            self.pos += 1;
            Some(c)
        } else {
            None
        }
    }

    fn next_f32(&mut self) -> Option<f32> {
        self.skip_whitespace_and_comma();
        if self.pos >= self.data.len() {
            return None;
        }
        let start = self.pos;
        if self.pos < self.data.len() && (self.data[self.pos] == b'-' || self.data[self.pos] == b'+') {
            self.pos += 1;
        }
        let mut has_digit = false;
        while self.pos < self.data.len() && self.data[self.pos].is_ascii_digit() {
            self.pos += 1;
            has_digit = true;
        }
        if self.pos < self.data.len() && self.data[self.pos] == b'.' {
            self.pos += 1;
            while self.pos < self.data.len() && self.data[self.pos].is_ascii_digit() {
                self.pos += 1;
                has_digit = true;
            }
        }
        if has_digit && self.pos < self.data.len() && (self.data[self.pos] == b'e' || self.data[self.pos] == b'E') {
            self.pos += 1;
            if self.pos < self.data.len() && (self.data[self.pos] == b'-' || self.data[self.pos] == b'+') {
                self.pos += 1;
            }
            while self.pos < self.data.len() && self.data[self.pos].is_ascii_digit() {
                self.pos += 1;
            }
        }
        if !has_digit {
            self.pos = start;
            return None;
        }
        let s = core::str::from_utf8(&self.data[start..self.pos]).ok()?;
        s.parse::<f32>().ok()
    }
}

/// SVG パス文字列 `d` を解析し、`PathBuilder` へ追加する。
pub fn parse_svg_path_into(d: &str, p: &mut PathBuilder, m: &Matrix) {
    let mut tok = SvgPathTokenizer::new(d);
    let mut curr_x = 0.0f32;
    let mut curr_y = 0.0f32;
    let mut start_x = 0.0f32;
    let mut start_y = 0.0f32;
    let mut last_cmd = ' ';

    while tok.pos < tok.data.len() {
        tok.skip_whitespace_and_comma();
        if tok.pos >= tok.data.len() {
            break;
        }
        let cmd = if let Some(c) = tok.next_cmd() {
            last_cmd = c;
            c
        } else if last_cmd != ' ' {
            if last_cmd == 'M' {
                'L'
            } else if last_cmd == 'm' {
                'l'
            } else {
                last_cmd
            }
        } else {
            break;
        };

        match cmd {
            'M' => {
                if let (Some(x), Some(y)) = (tok.next_f32(), tok.next_f32()) {
                    curr_x = x;
                    curr_y = y;
                    start_x = x;
                    start_y = y;
                    p.move_to(m, x, y);
                }
            }
            'm' => {
                if let (Some(dx), Some(dy)) = (tok.next_f32(), tok.next_f32()) {
                    curr_x += dx;
                    curr_y += dy;
                    start_x = curr_x;
                    start_y = curr_y;
                    p.move_to(m, curr_x, curr_y);
                }
            }
            'L' => {
                if let (Some(x), Some(y)) = (tok.next_f32(), tok.next_f32()) {
                    curr_x = x;
                    curr_y = y;
                    p.line_to(m, x, y);
                }
            }
            'l' => {
                if let (Some(dx), Some(dy)) = (tok.next_f32(), tok.next_f32()) {
                    curr_x += dx;
                    curr_y += dy;
                    p.line_to(m, curr_x, curr_y);
                }
            }
            'H' => {
                if let Some(x) = tok.next_f32() {
                    curr_x = x;
                    p.line_to(m, curr_x, curr_y);
                }
            }
            'h' => {
                if let Some(dx) = tok.next_f32() {
                    curr_x += dx;
                    p.line_to(m, curr_x, curr_y);
                }
            }
            'V' => {
                if let Some(y) = tok.next_f32() {
                    curr_y = y;
                    p.line_to(m, curr_x, curr_y);
                }
            }
            'v' => {
                if let Some(dy) = tok.next_f32() {
                    curr_y += dy;
                    p.line_to(m, curr_x, curr_y);
                }
            }
            'C' => {
                if let (Some(x1), Some(y1), Some(x2), Some(y2), Some(x), Some(y)) = (
                    tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32()
                ) {
                    p.bezier_curve_to(m, x1, y1, x2, y2, x, y);
                    curr_x = x;
                    curr_y = y;
                }
            }
            'c' => {
                if let (Some(dx1), Some(dy1), Some(dx2), Some(dy2), Some(dx), Some(dy)) = (
                    tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32()
                ) {
                    p.bezier_curve_to(m, curr_x + dx1, curr_y + dy1, curr_x + dx2, curr_y + dy2, curr_x + dx, curr_y + dy);
                    curr_x += dx;
                    curr_y += dy;
                }
            }
            'S' | 's' => {
                if cmd == 'S' {
                    if let (Some(x2), Some(y2), Some(x), Some(y)) = (
                        tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32()
                    ) {
                        p.bezier_curve_to(m, curr_x, curr_y, x2, y2, x, y);
                        curr_x = x;
                        curr_y = y;
                    }
                } else {
                    if let (Some(dx2), Some(dy2), Some(dx), Some(dy)) = (
                        tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32()
                    ) {
                        p.bezier_curve_to(m, curr_x, curr_y, curr_x + dx2, curr_y + dy2, curr_x + dx, curr_y + dy);
                        curr_x += dx;
                        curr_y += dy;
                    }
                }
            }
            'Q' => {
                if let (Some(x1), Some(y1), Some(x), Some(y)) = (
                    tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32()
                ) {
                    p.quadratic_curve_to(m, x1, y1, x, y);
                    curr_x = x;
                    curr_y = y;
                }
            }
            'q' => {
                if let (Some(dx1), Some(dy1), Some(dx), Some(dy)) = (
                    tok.next_f32(), tok.next_f32(), tok.next_f32(), tok.next_f32()
                ) {
                    p.quadratic_curve_to(m, curr_x + dx1, curr_y + dy1, curr_x + dx, curr_y + dy);
                    curr_x += dx;
                    curr_y += dy;
                }
            }
            'Z' | 'z' => {
                p.close_path();
                curr_x = start_x;
                curr_y = start_y;
            }
            _ => {
                tok.pos += 1;
            }
        }
    }
}

// ───────────── Path2D 登録表 ─────────────

static PATH2D_MAP: spin::Mutex<alloc::collections::BTreeMap<u32, PathBuilder>> =
    spin::Mutex::new(alloc::collections::BTreeMap::new());
static NEXT_PATH2D_ID: core::sync::atomic::AtomicU32 = core::sync::atomic::AtomicU32::new(1);
const MAX_PATH2D: usize = 64;

pub fn create_path2d(init_svg: Option<&str>) -> u32 {
    let id = NEXT_PATH2D_ID.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
    let mut builder = PathBuilder::new();
    if let Some(svg) = init_svg {
        parse_svg_path_into(svg, &mut builder, &Matrix::identity());
    }
    let mut map = PATH2D_MAP.lock();
    while map.len() >= MAX_PATH2D {
        if let Some(&oldest) = map.keys().next() {
            map.remove(&oldest);
        } else {
            break;
        }
    }
    map.insert(id, builder);
    id
}

pub fn clone_path2d(src_id: u32) -> u32 {
    let new_id = NEXT_PATH2D_ID.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
    let mut map = PATH2D_MAP.lock();
    while map.len() >= MAX_PATH2D {
        if let Some(&oldest) = map.keys().next() {
            map.remove(&oldest);
        } else {
            break;
        }
    }
    let cloned = map.get(&src_id).cloned().unwrap_or_else(PathBuilder::new);
    map.insert(new_id, cloned);
    new_id
}

pub fn with_path2d<R>(id: u32, f: impl FnOnce(&mut PathBuilder) -> R) -> Option<R> {
    let mut map = PATH2D_MAP.lock();
    map.get_mut(&id).map(f)
}

pub fn get_path2d_subpaths(id: u32) -> Option<Vec<SubPath>> {
    let map = PATH2D_MAP.lock();
    map.get(&id).map(|p| p.finish())
}

pub fn add_path_to_path2d(dst_id: u32, src_id: u32, transform: Option<&Matrix>) {
    let mut map = PATH2D_MAP.lock();
    if let Some(src) = map.get(&src_id).cloned() {
        if let Some(dst) = map.get_mut(&dst_id) {
            dst.add_path(&src, transform);
        }
    }
}

impl Canvas2dContext {
    /// 外部のパス（Path2D 等）を指定して塗る。
    pub fn fill_subpaths(&mut self, subpaths: &[SubPath], rule: FillRule) {
        self.sync_clip();
        if let Some(ref grad) = self.state.fill_gradient {
            self.surface.fill_path_gradient(subpaths, rule, grad, self.state.global_alpha.clamp(0.0, 1.0));
        } else {
            let color = self.apply_alpha(self.state.fill);
            self.surface.fill_path(subpaths, rule, color);
        }
    }

    /// 外部のパス（Path2D 等）を指定して線を描く。
    pub fn stroke_subpaths(&mut self, subpaths: &[SubPath]) {
        self.sync_clip();
        let color = self.apply_alpha(self.state.stroke);
        let w = self.state.line_width;
        let (cap, join, limit) = (
            self.state.line_cap,
            self.state.line_join,
            self.state.miter_limit,
        );
        let sub = self.apply_dash(subpaths);
        self.surface
            .stroke_path_styled(&sub, color, w, cap, join, limit);
    }

    /// 外部のパス（Path2D 等）を指定してクリップする。
    pub fn clip_subpaths(&mut self, subpaths: &[SubPath], rule: FillRule) {
        if subpaths.is_empty() {
            return;
        }
        let mask = ClipMask::from_path(self.surface.width, self.surface.height, subpaths, rule);
        let merged = match &self.state.clip {
            Some(prev) => prev.intersect(&mask),
            None => mask,
        };
        self.state.clip = Some(alloc::sync::Arc::new(merged));
    }
}


// ───────────── CanvasGradient 登録表 ─────────────

static GRADIENT_MAP: spin::Mutex<alloc::collections::BTreeMap<u32, CanvasGradient>> =
    spin::Mutex::new(alloc::collections::BTreeMap::new());
static NEXT_GRADIENT_ID: core::sync::atomic::AtomicU32 = core::sync::atomic::AtomicU32::new(1);
const MAX_GRADIENTS: usize = 64;

pub fn create_linear_gradient(x0: f32, y0: f32, x1: f32, y1: f32) -> u32 {
    let id = NEXT_GRADIENT_ID.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
    let grad = CanvasGradient::new_linear(x0, y0, x1, y1);
    let mut map = GRADIENT_MAP.lock();
    while map.len() >= MAX_GRADIENTS {
        if let Some(&oldest) = map.keys().next() {
            map.remove(&oldest);
        } else {
            break;
        }
    }
    map.insert(id, grad);
    id
}

pub fn create_radial_gradient(x0: f32, y0: f32, r0: f32, x1: f32, y1: f32, r1: f32) -> u32 {
    let id = NEXT_GRADIENT_ID.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
    let grad = CanvasGradient::new_radial(x0, y0, r0, x1, y1, r1);
    let mut map = GRADIENT_MAP.lock();
    while map.len() >= MAX_GRADIENTS {
        if let Some(&oldest) = map.keys().next() {
            map.remove(&oldest);
        } else {
            break;
        }
    }
    map.insert(id, grad);
    id
}

pub fn add_color_stop_to_gradient(id: u32, offset: f32, color: u32) {
    let mut map = GRADIENT_MAP.lock();
    if let Some(grad) = map.get_mut(&id) {
        grad.add_color_stop(offset, color);
    }
}

pub fn get_gradient(id: u32) -> Option<CanvasGradient> {
    let map = GRADIENT_MAP.lock();
    map.get(&id).cloned()
}