atmos/os_lib/css/

animation.rs

// 分割: css.rs より機械的に移動（2026-07-16 リファクタ フェーズ3）。
// ロジック不変。可視性のみ pub(crate) へ昇格し、親が pub(crate) use で再エクスポート。
use super::*;

/// イージング関数。CSS の transition-timing-function / animation-timing-function。
#[derive(Debug, Clone, PartialEq)]
pub enum TimingFunction {
    Linear,
    /// 3次ベジェ制御点 (x1, y1, x2, y2)。ease/ease-in/out/in-out もこれで表現。
    CubicBezier(f32, f32, f32, f32),
    /// steps(n, jump-start|jump-end)。bool=jump_start。
    Steps(u32, bool),
}

impl TimingFunction {
    /// CSS のキーワード/関数表記をパース。
    pub fn parse(s: &str) -> TimingFunction {
        let s = s.trim().to_lowercase();
        match s.as_str() {
            "linear" => TimingFunction::Linear,
            "ease" => TimingFunction::CubicBezier(0.25, 0.1, 0.25, 1.0),
            "ease-in" => TimingFunction::CubicBezier(0.42, 0.0, 1.0, 1.0),
            "ease-out" => TimingFunction::CubicBezier(0.0, 0.0, 0.58, 1.0),
            "ease-in-out" => TimingFunction::CubicBezier(0.42, 0.0, 0.58, 1.0),
            "step-start" => TimingFunction::Steps(1, true),
            "step-end" => TimingFunction::Steps(1, false),
            _ => {
                if let Some(inner) = s
                    .strip_prefix("cubic-bezier(")
                    .and_then(|x| x.strip_suffix(')'))
                {
                    let nums: Vec<f32> = inner
                        .split(',')
                        .filter_map(|n| n.trim().parse::<f32>().ok())
                        .collect();
                    if nums.len() == 4 {
                        return TimingFunction::CubicBezier(nums[0], nums[1], nums[2], nums[3]);
                    }
                } else if let Some(inner) =
                    s.strip_prefix("steps(").and_then(|x| x.strip_suffix(')'))
                {
                    let parts: Vec<&str> = inner.split(',').map(|p| p.trim()).collect();
                    let n = parts
                        .first()
                        .and_then(|p| p.parse::<u32>().ok())
                        .unwrap_or(1);
                    let jump_start = parts.get(1).map(|p| p.contains("start")).unwrap_or(false);
                    return TimingFunction::Steps(n.max(1), jump_start);
                }
                // 不明な指定は ease にフォールバック。
                TimingFunction::CubicBezier(0.25, 0.1, 0.25, 1.0)
            }
        }
    }

    /// 線形進捗 t(0..=1) をイージング後の進捗に変換する。
    pub fn ease(&self, t: f32) -> f32 {
        let t = t.clamp(0.0, 1.0);
        match self {
            TimingFunction::Linear => t,
            TimingFunction::CubicBezier(x1, y1, x2, y2) => {
                cubic_bezier_solve(*x1, *y1, *x2, *y2, t)
            }
            TimingFunction::Steps(n, jump_start) => {
                let n = *n as f32;
                let step = libm_floor(t * n);
                let v = if *jump_start {
                    (step + 1.0) / n
                } else {
                    step / n
                };
                v.clamp(0.0, 1.0)
            }
        }
    }
}

/// 3次ベジェ y(x=t) を解く。x からニュートン法で媒介変数 u を求め y(u) を返す。
pub(crate) fn cubic_bezier_solve(x1: f32, y1: f32, x2: f32, y2: f32, x: f32) -> f32 {
    // ベジェ成分: B(u) = 3(1-u)^2 u * p1 + 3(1-u) u^2 * p2 + u^3。
    fn sample(p1: f32, p2: f32, u: f32) -> f32 {
        let one = 1.0 - u;
        3.0 * one * one * u * p1 + 3.0 * one * u * u * p2 + u * u * u
    }
    fn sample_deriv(p1: f32, p2: f32, u: f32) -> f32 {
        let one = 1.0 - u;
        3.0 * one * one * p1 + 6.0 * one * u * (p2 - p1) + 3.0 * u * u * (1.0 - p2)
    }
    if x <= 0.0 {
        return 0.0;
    }
    if x >= 1.0 {
        return 1.0;
    }
    // ニュートン法で x = sample_x(u) を満たす u を探索。
    let mut u = x;
    for _ in 0..8 {
        let x_est = sample(x1, x2, u) - x;
        let d = sample_deriv(x1, x2, u);
        if d.abs() < 1e-6 {
            break;
        }
        u -= x_est / d;
        u = u.clamp(0.0, 1.0);
    }
    sample(y1, y2, u)
}

/// 2つの CSS 値を進捗 t で補間する。px/数値/%/色/`<n>deg`/複数値（空白区切り）に対応。
/// 補間できない場合は t<0.5 で from、それ以外で to を返す（discrete）。
pub fn interpolate_value(from: &str, to: &str, t: f32) -> String {
    let from = from.trim();
    let to = to.trim();
    if from == to {
        return from.to_string();
    }
    // 色（#hex / rgb / rgba / hsl / 名前）。
    if let (Some(c1), Some(c2)) = (parse_color(from), parse_color(to)) {
        return interpolate_color(c1, c2, t);
    }
    // `translate(10px, 20px)` / `matrix(a,b,c,d,e,f)` のような、値全体が単一の関数呼び出しで
    // 引数がカンマ区切りのケースを先に処理する。以前はこのチェックより先に空白区切りの
    // 複数トークン判定（`margin: 1px 2px` 用）が走っており、`translate(10px, 20px)` の
    // カンマ後の空白が余分な「トークン」を作ってしまい（`["translate(10px,", "20px)"]`）、
    // 各引数が独立に正しく補間されず途中で離散的にジャンプするバグがあった
    // （`translateX(10px)` のような引数無しカンマの単一関数は元々正しく動いていた）。
    if let (Some(f1), Some(f2)) = (as_single_wrapped_call(from), as_single_wrapped_call(to)) {
        if f1.0 == f2.0 {
            let inner = if f1.1.contains(',') || f2.1.contains(',') {
                let a1 = split_top_level_commas(&f1.1);
                let a2 = split_top_level_commas(&f2.1);
                if a1.len() == a2.len() {
                    a1.iter()
                        .zip(a2.iter())
                        .map(|(a, b)| interpolate_value(a, b, t))
                        .collect::<Vec<String>>()
                        .join(", ")
                } else {
                    return if t < 0.5 { from.to_string() } else { to.to_string() };
                }
            } else {
                interpolate_value(&f1.1, &f2.1, t)
            };
            return alloc::format!("{}({})", f1.0, inner);
        }
    }
    // `box-shadow`/`text-shadow` のようなカンマ区切りの複数レイヤー値。以前はここより先に
    // 空白区切りトークン判定が走っており、カンマ後の空白によるトークン化で
    // レイヤー境界を跨いだ位置ベースの補間（例: "red," と "blue," のような壊れたトークン同士）
    // になってしまい、色として解析できず discrete フォールバックに落ちる/レイヤー数が
    // 食い違うと丸ごとジャンプするバグがあった（`translate(x, y)` の引数分割で見つけたのと
    // 同種）。トップレベル（括弧の外）にカンマがある場合はレイヤー単位で分割・補間する。
    let from_layers = split_top_level_commas(from);
    let to_layers = split_top_level_commas(to);
    if from_layers.len() > 1 || to_layers.len() > 1 {
        if from_layers.len() == to_layers.len() {
            return from_layers
                .iter()
                .zip(to_layers.iter())
                .map(|(a, b)| interpolate_value(a, b, t))
                .collect::<Vec<String>>()
                .join(", ");
        }
        return if t < 0.5 { from.to_string() } else { to.to_string() };
    }
    // 複数トークン（margin: 1px 2px, transform: translateX(..) rotate(..) 等）。
    let ft: Vec<&str> = from.split_whitespace().collect();
    let tt: Vec<&str> = to.split_whitespace().collect();
    if ft.len() > 1 || tt.len() > 1 {
        if ft.len() == tt.len() {
            let parts: Vec<String> = ft
                .iter()
                .zip(tt.iter())
                .map(|(a, b)| interpolate_value(a, b, t))
                .collect();
            return parts.join(" ");
        }
        return if t < 0.5 {
            from.to_string()
        } else {
            to.to_string()
        };
    }
    // translateX(10px) 等の単一関数（引数無しカンマ）: 内側を補間。
    if let (Some(f1), Some(f2)) = (split_fn(from), split_fn(to)) {
        if f1.0 == f2.0 {
            let inner = interpolate_value(&f1.1, &f2.1, t);
            return alloc::format!("{}({})", f1.0, inner);
        }
    }
    // 単位付き数値 / 純数値。CSS仕様上、長さ/百分率等の値では単位無しの`0`は
    // どの単位の文脈でも許容される（例: 実サイト www.sugi-lab.net のタイピング
    // 演出`@keyframes typing { from{width:0} to{width:100%} }`）。以前はこの
    // ケースを`u1 == u2`の厳密一致でのみ判定していたため、`0`（単位無し）と
    // `100%`（%単位）が「単位不一致」とみなされ補間できず、アニメーションが
    // 滑らかに変化せず離散的にジャンプするバグだった（2026-07-22発見・修正）。
    if let (Some((n1, u1)), Some((n2, u2))) = (split_num_unit(from), split_num_unit(to)) {
        let units_compatible =
            u1 == u2 || (u1.is_empty() && n1 == 0.0) || (u2.is_empty() && n2 == 0.0);
        if units_compatible {
            let unit = if u1.is_empty() { u2 } else { u1 };
            let v = n1 + (n2 - n1) * t;
            if unit.is_empty() {
                return fmt_num(v);
            }
            return alloc::format!("{}{}", fmt_num(v), unit);
        }
    }
    // 補間不能 → discrete。
    if t < 0.5 {
        from.to_string()
    } else {
        to.to_string()
    }
}

/// 文字列全体が単一の関数呼び出し（`name(...)`）かどうかを判定し、そうであれば
/// ("name", "args") を返す。`split_fn` と違い、括弧の対応を実際に追跡して
/// 「その関数呼び出しの閉じ括弧が文字列の末尾ちょうどにある」ことまで確認するため、
/// `translateX(10px) rotate(20deg)`（空白区切りの複数関数）を誤って単一関数として
/// 誤認しない（`split_fn` は最初の `(` と末尾の `)` を機械的に拾うだけなので、この判定には使えない）。
pub(crate) fn as_single_wrapped_call(s: &str) -> Option<(String, String)> {
    let s = s.trim();
    let open = s.find('(')?;
    let name = s.get(..open)?.trim();
    if name.is_empty() || name.contains(char::is_whitespace) {
        return None;
    }
    let bytes = s.as_bytes();
    let mut depth = 0i32;
    let mut close_idx = None;
    for (i, &b) in bytes.iter().enumerate().skip(open) {
        match b {
            b'(' => depth += 1,
            b')' => {
                depth -= 1;
                if depth == 0 {
                    close_idx = Some(i);
                    break;
                }
            }
            _ => {}
        }
    }
    let close_idx = close_idx?;
    if close_idx != s.len() - 1 {
        // 閉じ括弧が文字列末尾ちょうどでない = この後に別のトークンが続く
        // （複数関数の並び等）ため単一関数として扱えない。
        return None;
    }
    let inner = s.get(open + 1..close_idx)?.trim();
    Some((name.to_string(), inner.to_string()))
}

/// `fn(args)` を ("fn", "args") に分割。
pub(crate) fn split_fn(s: &str) -> Option<(String, String)> {
    let open = s.find('(')?;
    if !s.ends_with(')') {
        return None;
    }
    let name = s.get(..open)?.trim();
    let inner = s.get(open + 1..s.len() - 1)?.trim();
    if name.is_empty() {
        return None;
    }
    Some((name.to_string(), inner.to_string()))
}

/// `12.5px` → (12.5, "px")、`0.8` → (0.8, "")。
pub(crate) fn split_num_unit(s: &str) -> Option<(f32, String)> {
    let s = s.trim();
    let end = s
        .find(|c: char| !(c.is_ascii_digit() || c == '.' || c == '-' || c == '+'))
        .unwrap_or(s.len());
    let (num, unit) = s.split_at(end);
    let n = num.parse::<f32>().ok()?;
    Some((n, unit.trim().to_string()))
}

/// 数値を簡潔な文字列にする（整数なら小数点なし）。
pub(crate) fn fmt_num(v: f32) -> String {
    let r = libm_round(v * 1000.0) / 1000.0;
    if (r - libm_round(r)).abs() < 1e-4 {
        alloc::format!("{}", r as i64)
    } else {
        let s = alloc::format!("{:.3}", r);
        s.trim_end_matches('0').trim_end_matches('.').to_string()
    }
}

pub(crate) fn libm_round(v: f32) -> f32 {
    if v >= 0.0 {
        (v + 0.5) as i64 as f32
    } else {
        -((-v + 0.5) as i64 as f32)
    }
}

/// 2色を補間して #RRGGBB or rgba(...) 文字列を返す。内部表現は 0xAARRGGBB。
pub(crate) fn interpolate_color(c1: u32, c2: u32, t: f32) -> String {
    let t = t.clamp(0.0, 1.0);
    let a1 = ((c1 >> 24) & 0xFF) as f32;
    let r1 = ((c1 >> 16) & 0xFF) as f32;
    let g1 = ((c1 >> 8) & 0xFF) as f32;
    let b1 = (c1 & 0xFF) as f32;
    let a2 = ((c2 >> 24) & 0xFF) as f32;
    let r2 = ((c2 >> 16) & 0xFF) as f32;
    let g2 = ((c2 >> 8) & 0xFF) as f32;
    let b2 = (c2 & 0xFF) as f32;
    let a = (a1 + (a2 - a1) * t) as u32;
    let r = (r1 + (r2 - r1) * t) as u32;
    let g = (g1 + (g2 - g1) * t) as u32;
    let b = (b1 + (b2 - b1) * t) as u32;
    if a >= 255 {
        alloc::format!("#{:02x}{:02x}{:02x}", r, g, b)
    } else {
        let af = a as f32 / 255.0;
        alloc::format!("rgba({}, {}, {}, {})", r, g, b, fmt_num(af))
    }
}

/// `transition` ショートハンド1項目の解析結果。
#[derive(Debug, Clone, PartialEq)]
pub struct TransitionSpec {
    pub property: String,
    pub duration_ms: f32,
    pub timing: TimingFunction,
    pub delay_ms: f32,
}

/// CSS 時間値 `1s` / `250ms` を ms に変換。
pub fn parse_time_ms(s: &str) -> f32 {
    let s = s.trim().to_lowercase();
    if let Some(v) = s.strip_suffix("ms") {
        v.trim().parse::<f32>().unwrap_or(0.0)
    } else if let Some(v) = s.strip_suffix('s') {
        v.trim().parse::<f32>().unwrap_or(0.0) * 1000.0
    } else {
        s.parse::<f32>().unwrap_or(0.0)
    }
}

/// プロパティ名がアニメーション可能か（transition: all の展開対象判定に使う）。
pub fn is_animatable_property(prop: &str) -> bool {
    matches!(
        prop,
        "width"
            | "height"
            | "left"
            | "top"
            | "right"
            | "bottom"
            | "margin"
            | "margin-left"
            | "margin-top"
            | "margin-right"
            | "margin-bottom"
            | "padding"
            | "padding-left"
            | "padding-top"
            | "padding-right"
            | "padding-bottom"
            | "opacity"
            | "color"
            | "background-color"
            | "border-color"
            | "border-width"
            | "font-size"
            | "transform"
            | "line-height"
            | "letter-spacing"
            | "word-spacing"
            | "max-width"
            | "max-height"
            | "min-width"
            | "min-height"
    )
}

/// `transition` プロパティ（カンマ区切りの複数項目）をパース。
/// 例: "width 1s ease, background-color 0.5s linear 0.2s"。
/// トークンが実際に時間値（`<number>s` / `<number>ms`）かどうかを判定する。
/// 単に末尾が `s` かどうかだけを見ると `flex-basis`/`border-radius` のように
/// 末尾がたまたま `s` で終わるプロパティ名まで時間値と誤認してしまう
/// （`font: oblique <angle>` の `10deg` を size と誤認したのと同根の「緩すぎる
/// トークン分類」バグ）ため、単位を除いた残りが実際に数値としてパースできる
/// ことまで確認する。
pub(crate) fn is_time_token(low: &str) -> bool {
    if let Some(v) = low.strip_suffix("ms") {
        v.trim().parse::<f32>().is_ok()
    } else if let Some(v) = low.strip_suffix('s') {
        v.trim().parse::<f32>().is_ok()
    } else {
        false
    }
}

pub fn parse_transition(value: &str) -> Vec<TransitionSpec> {
    let mut specs = Vec::new();
    for item in split_top_commas(value) {
        let toks: Vec<&str> = item.split_whitespace().collect();
        if toks.is_empty() {
            continue;
        }
        let mut property = String::from("all");
        let mut duration_ms = 0.0;
        let mut delay_ms = 0.0;
        let mut timing = TimingFunction::CubicBezier(0.25, 0.1, 0.25, 1.0);
        let mut time_seen = 0;
        let mut i = 0;
        while i < toks.len() {
            let tok = toks[i];
            let low = tok.to_lowercase();
            if low.starts_with("cubic-bezier(") || low.starts_with("steps(") {
                // 関数表記は空白を含み得るので `)` まで連結。
                let mut joined = String::from(tok);
                while !joined.ends_with(')') && i + 1 < toks.len() {
                    i += 1;
                    joined.push_str(toks[i]);
                }
                timing = TimingFunction::parse(&joined);
            } else if matches!(
                low.as_str(),
                "linear"
                    | "ease"
                    | "ease-in"
                    | "ease-out"
                    | "ease-in-out"
                    | "step-start"
                    | "step-end"
            ) {
                timing = TimingFunction::parse(&low);
            } else if is_time_token(&low) {
                if time_seen == 0 {
                    duration_ms = parse_time_ms(&low);
                } else {
                    delay_ms = parse_time_ms(&low);
                }
                time_seen += 1;
            } else {
                property = tok.to_string();
            }
            i += 1;
        }
        specs.push(TransitionSpec {
            property,
            duration_ms,
            timing,
            delay_ms,
        });
    }
    specs
}

/// `animation` ショートハンドの解析結果。
#[derive(Debug, Clone, PartialEq)]
pub struct AnimationSpec {
    pub name: String,
    pub duration_ms: f32,
    pub timing: TimingFunction,
    pub delay_ms: f32,
    /// 繰り返し回数。f32::INFINITY = infinite。
    pub iterations: f32,
    /// "normal" | "reverse" | "alternate" | "alternate-reverse"。
    pub direction: String,
    /// "none" | "forwards" | "backwards" | "both"。
    pub fill: String,
    /// "running" | "paused"。以前は `animation-play-state` が一切パース/適用されず、
    /// `paused` 指定が常に無視され再生が止められないバグがあった。
    pub play_state: String,
}

/// `animation` ショートハンドの最初の1項目のみをパース（後方互換用）。
/// 複数のカンマ区切りアニメーションをすべて扱いたい場合は `parse_animations` を使う。
pub fn parse_animation(value: &str) -> Option<AnimationSpec> {
    parse_animations(value).into_iter().next()
}

/// `animation` ショートハンドをカンマ区切りの全項目についてパースする。
/// 例: "fade 1s, bounce 2s infinite" → 2つの `AnimationSpec`。
pub fn parse_animations(value: &str) -> alloc::vec::Vec<AnimationSpec> {
    split_top_commas(value)
        .into_iter()
        .filter_map(|item| parse_one_animation(&item))
        .collect()
}

/// `animation` ショートハンド1項目をパース。
/// 例: "slide 2s ease-in-out 0.5s infinite alternate both"。
pub(crate) fn parse_one_animation(item: &str) -> Option<AnimationSpec> {
    let toks: Vec<String> = item.split_whitespace().map(|s| s.to_string()).collect();
    if toks.is_empty() {
        return None;
    }
    let mut spec = AnimationSpec {
        name: String::new(),
        duration_ms: 0.0,
        timing: TimingFunction::CubicBezier(0.25, 0.1, 0.25, 1.0),
        delay_ms: 0.0,
        iterations: 1.0,
        direction: String::from("normal"),
        fill: String::from("none"),
        play_state: String::from("running"),
    };
    let mut time_seen = 0;
    let mut i = 0;
    while i < toks.len() {
        let tok = toks[i].clone();
        let low = tok.to_lowercase();
        if low.starts_with("cubic-bezier(") || low.starts_with("steps(") {
            let mut joined = tok.clone();
            while !joined.ends_with(')') && i + 1 < toks.len() {
                i += 1;
                joined.push_str(&toks[i]);
            }
            spec.timing = TimingFunction::parse(&joined);
        } else if matches!(
            low.as_str(),
            "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | "step-start" | "step-end"
        ) {
            spec.timing = TimingFunction::parse(&low);
        } else if is_time_token(&low) {
            if time_seen == 0 {
                spec.duration_ms = parse_time_ms(&low);
            } else {
                spec.delay_ms = parse_time_ms(&low);
            }
            time_seen += 1;
        } else if low == "infinite" {
            spec.iterations = f32::INFINITY;
        } else if let Ok(n) = low.parse::<f32>() {
            spec.iterations = n;
        } else if matches!(
            low.as_str(),
            "normal" | "reverse" | "alternate" | "alternate-reverse"
        ) {
            spec.direction = low;
        } else if matches!(low.as_str(), "none" | "forwards" | "backwards" | "both") {
            spec.fill = low;
        } else if matches!(low.as_str(), "running" | "paused") {
            spec.play_state = low;
        } else {
            // それ以外は animation-name とみなす。
            spec.name = tok;
        }
        i += 1;
    }
    if spec.name.is_empty() {
        return None;
    }
    Some(spec)
}

/// トップレベルのカンマで分割（関数内の `,` は無視）。
pub(crate) fn split_top_commas(s: &str) -> Vec<String> {
    let mut out = Vec::new();
    let mut depth = 0;
    let mut cur = String::new();
    for c in s.chars() {
        match c {
            '(' => {
                depth += 1;
                cur.push(c);
            }
            ')' => {
                depth -= 1;
                cur.push(c);
            }
            ',' if depth == 0 => {
                out.push(cur.trim().to_string());
                cur.clear();
            }
            _ => cur.push(c),
        }
    }
    if !cur.trim().is_empty() {
        out.push(cur.trim().to_string());
    }
    out
}

/// トランジションの現在値を計算する。
/// `from`/`to`: プロパティの開始値・終了値。`elapsed_ms`: 状態変更からの経過時間。
/// 戻り値: (現在の補間値, アニメーションが進行中か)。
pub fn sample_transition(
    spec: &TransitionSpec,
    from: &str,
    to: &str,
    elapsed_ms: f32,
) -> (String, bool) {
    let active = elapsed_ms - spec.delay_ms;
    if active <= 0.0 {
        return (from.to_string(), true);
    }
    if spec.duration_ms <= 0.0 || active >= spec.duration_ms {
        return (to.to_string(), false);
    }
    let raw = active / spec.duration_ms;
    let eased = spec.timing.ease(raw);
    (interpolate_value(from, to, eased), true)
}

/// @keyframes アニメーションの現在算出値を、対象プロパティごとに返す。
/// `elapsed_ms`: アニメーション開始からの経過。戻り値: プロパティ→現在値のマップ。
pub fn sample_animation(
    spec: &AnimationSpec,
    keyframes: &Keyframes,
    elapsed_ms: f32,
) -> BTreeMap<String, String> {
    let mut result = BTreeMap::new();
    if spec.duration_ms <= 0.0 {
        return result;
    }
    let active = elapsed_ms - spec.delay_ms;
    if active < 0.0 {
        // backwards/both なら最初のフレームを適用。
        if spec.fill == "backwards" || spec.fill == "both" {
            if let Some((_, decls)) = spec.frames_at(keyframes, 0.0) {
                for d in decls {
                    result.insert(d.name.clone(), d.value.clone());
                }
            }
        }
        return result;
    }
    // 現在の反復回数とローカル進捗。
    let iter_f = active / spec.duration_ms;
    let finished = iter_f >= spec.iterations;
    let mut local = if finished {
        // forwards/both なら最終位置で固定。
        if spec.fill != "forwards" && spec.fill != "both" {
            return result;
        }
        // 最終反復の終端進捗。
        let last_iter = if spec.iterations.is_finite() {
            spec.iterations
        } else {
            iter_f
        };
        let frac = last_iter - libm_floor(last_iter);
        if frac == 0.0 {
            1.0
        } else {
            frac
        }
    } else {
        iter_f - libm_floor(iter_f)
    };
    // 完了時の反復インデックス（0始まり、direction:alternate の偶奇判定に使う）。
    // `animation-iteration-count` が非整数（例: 2.5）の場合、以前は常に
    // `floor(iterations) - 1` を使っていたため、最終回の「端数だけ進んだ反復」
    // （本来のインデックスは `floor(iterations)`）ではなく1つ前の反復として扱われ、
    // alternate の偶奇が反転し、fill:forwards/both での最終停止フレームが
    // 左右逆になってしまうバグがあった（整数回数のときは端数が無い＝frac==0.0 なので
    // 従来通り `iterations - 1` のままで正しい）。
    let iter_index = if finished {
        let last_iter = if spec.iterations.is_finite() {
            spec.iterations
        } else {
            iter_f
        };
        let frac = last_iter - libm_floor(last_iter);
        if frac == 0.0 {
            (last_iter.max(1.0) - 1.0) as i64
        } else {
            libm_floor(last_iter) as i64
        }
    } else {
        libm_floor(iter_f) as i64
    };
    // direction を反映。
    let reverse = match spec.direction.as_str() {
        "reverse" => true,
        "alternate" => iter_index % 2 == 1,
        "alternate-reverse" => iter_index % 2 == 0,
        _ => false,
    };
    if reverse {
        local = 1.0 - local;
    }
    local = local.clamp(0.0, 1.0);
    let eased = spec.timing.ease(local);

    // local 進捗を囲む2つのキーフレームを探して各プロパティを補間。
    // まず登場する全プロパティを収集。
    let mut props: Vec<String> = Vec::new();
    for (_, decls) in &keyframes.frames {
        for d in decls {
            if !props.contains(&d.name) {
                props.push(d.name.clone());
            }
        }
    }
    for prop in props {
        // このプロパティを定義する直前・直後のフレームを探す。
        let mut lower: Option<(f32, String)> = None;
        let mut upper: Option<(f32, String)> = None;
        for (off, decls) in &keyframes.frames {
            if let Some(d) = decls.iter().find(|d| d.name == prop) {
                if *off <= eased {
                    lower = Some((*off, d.value.clone()));
                }
                if *off >= eased && upper.is_none() {
                    upper = Some((*off, d.value.clone()));
                }
            }
        }
        let value = match (lower, upper) {
            (Some((o1, v1)), Some((o2, v2))) => {
                if (o2 - o1).abs() < 1e-6 {
                    v2
                } else {
                    let local_t = (eased - o1) / (o2 - o1);
                    interpolate_value(&v1, &v2, local_t)
                }
            }
            (Some((_, v)), None) => v,
            (None, Some((_, v))) => v,
            (None, None) => continue,
        };
        result.insert(prop, value);
    }
    result
}

pub(crate) fn libm_floor(v: f32) -> f32 {
    let i = v as i64 as f32;
    if v < 0.0 && i != v {
        i - 1.0
    } else {
        i
    }
}

impl AnimationSpec {
    /// 与えた offset 以下の最大フレーム（存在しなければ最初のフレーム）を返す。
    fn frames_at<'a>(
        &self,
        keyframes: &'a Keyframes,
        offset: f32,
    ) -> Option<(f32, &'a Vec<Declaration>)> {
        let mut best: Option<(f32, &Vec<Declaration>)> = None;
        for (off, decls) in &keyframes.frames {
            if *off <= offset + 1e-6 {
                best = Some((*off, decls));
            }
        }
        best.or_else(|| keyframes.frames.first().map(|(o, d)| (*o, d)))
    }
}

// ===================================================================
// ステートフルなアニメーション駆動エンジン
//   レンダラが毎フレーム tick() を呼び、要素ごとの算出値を得る。
//   時刻は外部（カーネルの ms クロック）から供給される。
// ===================================================================

/// 1要素・1プロパティのトランジション進行状態。
#[derive(Debug, Clone)]
pub(crate) struct ActiveTransition {
    element_id: String,
    property: String,
    from: String,
    to: String,
    spec: TransitionSpec,
    /// 開始時刻（ms）。
    start_ms: f32,
}

/// 1要素のアニメーション（@keyframes）進行状態。
#[derive(Debug, Clone)]
pub(crate) struct ActiveAnimation {
    element_id: String,
    spec: AnimationSpec,
    keyframes: Keyframes,
    start_ms: f32,
    /// 完了済みか（fill が none のとき値を出さなくなる）。
    done: bool,
    /// `play_state:paused` の間だけ `Some(経過ms)` を保持し、その値で経過時間を凍結する
    /// （`start_ms` はそのままにしておき、再開時に「凍結していた経過時間ぶんだけ現在時刻から
    /// 巻き戻す」形で `start_ms` を前進させ、一時停止した分だけシームレスに再開する）。
    paused_elapsed_ms: Option<f32>,
    /// `animation-delay`が経過し実際に最初のキーフレームの適用が始まったか
    /// （`animationstart`イベントを1回だけ発火するためのガード）。
    started: bool,
}

/// アニメーション/トランジションの集中管理。
#[derive(Debug, Clone, Default)]
pub struct AnimationEngine {
    transitions: Vec<ActiveTransition>,
    animations: Vec<ActiveAnimation>,
    /// 直近に算出した (element_id, property) → 値。レンダラが set_style に焼く。
    pub computed: Vec<(String, String, String)>,
    /// `animationend`/`transitionend`/`animationstart`（丸ごと未対応だった。
    /// `new AnimationEvent(...)`/`new TransitionEvent(...)`コンストラクタ自体は
    /// 既に実装済みで、手動での`el.dispatchEvent(new AnimationEvent
    /// ('animationend', ...))`は可能だったが、実際にCSSアニメーション/
    /// トランジションが完了・開始した時に、このエンジン自身が自動でイベントを
    /// 発火する経路が丸ごと存在しなかった。`tick()`の呼び出し元
    /// （`web_engine/layout.rs`の`tick_animations`。DOM/JSランタイムへのアクセス
    /// 権を持つ）がこのライフサイクルイベントリストを都度回収し、実際に
    /// `dispatch_event_with`する。各要素は`(element_id, event_type, name)`
    /// （`name`はアニメーションなら`animation-name`、トランジションなら
    /// プロパティ名）。`animationiteration`/`transitionstart`/`transitionrun`/
    /// `transitioncancel`（反復・トランジション側の開始/中断系）は状態遷移の
    /// 追跡がより複雑になるため今回は対象外とし、定番の完了/開始検知パターンで
    /// 使われる`animationend`/`transitionend`/`animationstart`の3つのみに絞った。
    pub lifecycle_events: Vec<(String, &'static str, String)>,
}

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

    /// すべての進行状態をクリア（ページ遷移時に呼ぶ）。
    pub fn clear(&mut self) {
        self.transitions.clear();
        self.animations.clear();
        self.computed.clear();
    }

    /// 進行中・予定のアニメーションが1つでもあるか（再描画要否の判定に使う）。
    pub fn is_active(&self) -> bool {
        !self.transitions.is_empty() || self.animations.iter().any(|a| !a.done)
    }

    /// 要素に `transition` が設定された状態で値が old→new に変化したら呼ぶ。
    /// 既存の同プロパティのトランジションは置き換える（再ターゲット）。
    pub fn start_transition(
        &mut self,
        element_id: &str,
        property: &str,
        from: &str,
        to: &str,
        spec: TransitionSpec,
        now_ms: f32,
    ) {
        if from == to {
            return;
        }
        // 同一 (element, property) の進行中トランジションがあれば、そのトランジションの
        // 「現在の補間値」をサンプリングしてから新トランジションの from とする（実ブラウザの
        // getComputedStyle 準拠の「中断→逆再生は現在位置から滑らかに」という挙動）。
        // 以前はコメントに「現在値から再スタート」と書いてありながら実装は伴っておらず、
        // 呼び出し側から渡された `from`（1つ前の style 更新時点の値、stale）をそのまま使って
        // 古いトランジションを単純に破棄していたため、中断時に一瞬ジャンプしてから
        // 逆再生してしまうバグがあった。
        let effective_from = self
            .transitions
            .iter()
            .find(|t| t.element_id == element_id && t.property == property)
            .map(|existing| {
                let elapsed = now_ms - existing.start_ms;
                sample_transition(&existing.spec, &existing.from, &existing.to, elapsed).0
            })
            .unwrap_or_else(|| from.to_string());
        self.transitions
            .retain(|t| !(t.element_id == element_id && t.property == property));
        if effective_from == to {
            // サンプリングした現在値が新しい目標値と一致するなら、新規トランジションは不要。
            return;
        }
        self.transitions.push(ActiveTransition {
            element_id: element_id.to_string(),
            property: property.to_string(),
            from: effective_from,
            to: to.to_string(),
            spec,
            start_ms: now_ms,
        });
    }

    /// 要素に `animation` が設定されたら呼ぶ。既存の同名アニメが既にある場合は
    /// 再登録せず、`play_state`（`animation-play-state:paused` のライブ切り替え、例えば
    /// hover 等のクラストグルで実現する一般的なパターン）だけを更新する。以前は既存アニメを
    /// 完全にスキップしていたため、実行中アニメの `play_state` をあとから変更しても
    /// 一切反映されなかった。
    pub fn start_animation(
        &mut self,
        element_id: &str,
        spec: AnimationSpec,
        keyframes: Keyframes,
        now_ms: f32,
    ) {
        if let Some(existing) = self
            .animations
            .iter_mut()
            .find(|a| a.element_id == element_id && a.spec.name == spec.name)
        {
            existing.spec.play_state = spec.play_state;
            // `@keyframes` の中身が動的に書き換わった場合（`<style>` の再注入や
            // メディアクエリ切り替えで同名の `@keyframes` ルールが別内容へ変わる等）にも
            // 追従できるよう、毎回渡される最新の `keyframes` へ更新する。以前はここで
            // 破棄しており、アニメーション開始時点のキーフレーム内容がずっと固定される
            // バグがあった（`iterations:infinite` だと永久に古い内容のまま）。
            existing.keyframes = keyframes;
            return;
        }
        self.animations.push(ActiveAnimation {
            element_id: element_id.to_string(),
            spec,
            keyframes,
            start_ms: now_ms,
            done: false,
            paused_elapsed_ms: None,
            started: false,
        });
    }

    /// 指定要素のアニメ/トランジションを取り消す。
    pub fn cancel_for(&mut self, element_id: &str) {
        self.transitions.retain(|t| t.element_id != element_id);
        self.animations.retain(|a| a.element_id != element_id);
    }

    /// 要素の `animation-name`（または `animation` ショートハンド）が変化した際、
    /// 現在指定されているアニメーション名の集合に無い、この要素の古いアニメーションを
    /// 取り消す。`start_animation` は「同一 (element, name) が既に存在すれば更新のみ」
    /// という判定しかしないため、以前は `animation-name` を "fade" から "bounce" のような
    /// 別名へ切り替えても、古い "fade" のアニメーションが決して除去されず（特に
    /// `iterations: infinite` の場合は自然完了もしないため）新旧2つのアニメーションが
    /// 永久に同時に走り続けてしまうバグがあった。
    pub fn retain_animation_names(&mut self, element_id: &str, current_names: &[String]) {
        self.animations.retain(|a| {
            a.element_id != element_id || current_names.iter().any(|n| n == &a.spec.name)
        });
    }

    /// 現在時刻で全アニメ/トランジションを評価し、computed を更新する。
    /// 戻り値: 進行中のものが残っているか（= 次フレームも再描画が要るか）。
    pub fn tick(&mut self, now_ms: f32) -> bool {
        self.computed.clear();
        self.lifecycle_events.clear();
        let mut still_active = false;

        // トランジション。
        let mut finished_idx: Vec<usize> = Vec::new();
        for (i, t) in self.transitions.iter().enumerate() {
            let elapsed = now_ms - t.start_ms;
            let (value, active) = sample_transition(&t.spec, &t.from, &t.to, elapsed);
            self.computed
                .push((t.element_id.clone(), t.property.clone(), value));
            if active {
                still_active = true;
            } else {
                finished_idx.push(i);
            }
        }
        // 完了したトランジションを除去（末尾から）。除去前に`transitionend`を記録する
        // （`element_id`/`property`は除去後には参照できないため）。
        for i in finished_idx.into_iter().rev() {
            let t = &self.transitions[i];
            self.lifecycle_events
                .push((t.element_id.clone(), "transitionend", t.property.clone()));
            self.transitions.remove(i);
        }

        // アニメーション。
        for a in self.animations.iter_mut() {
            let elapsed = if a.spec.play_state == "paused" {
                // 一時停止中: 経過時間を最初に一時停止した瞬間の値へ凍結する。
                *a.paused_elapsed_ms.get_or_insert(now_ms - a.start_ms)
            } else {
                if let Some(frozen) = a.paused_elapsed_ms.take() {
                    // 再開: 一時停止していた経過時間から連続するよう start_ms を
                    // 現在時刻基準に前進させる（一時停止していた分だけ巻き戻す）。
                    a.start_ms = now_ms - frozen;
                }
                now_ms - a.start_ms
            };
            // `animationstart`は`animation-delay`が経過し実際にキーフレームの
            // 適用が始まった瞬間に1回だけ発火する（`!a.started`だった時だけ記録
            // する同じガードパターン）。
            if !a.started && elapsed >= a.spec.delay_ms {
                self.lifecycle_events
                    .push((a.element_id.clone(), "animationstart", a.spec.name.clone()));
                a.started = true;
            }
            let m = sample_animation(&a.spec, &a.keyframes, elapsed);
            // 完了判定: 経過がトータル尺を超え、かつ無限でない。`!a.done`だった
            // ものが今回のtickで初めてtrueになった瞬間だけ`animationend`を記録する
            // （既に完了済みのアニメが`fill!=none`で居残り続ける場合に毎tick
            // 再発火してしまわないようにするガード）。
            let total = a.spec.delay_ms + a.spec.duration_ms * a.spec.iterations;
            if a.spec.iterations.is_finite() && elapsed >= total {
                if !a.done {
                    self.lifecycle_events.push((
                        a.element_id.clone(),
                        "animationend",
                        a.spec.name.clone(),
                    ));
                }
                a.done = true;
            } else {
                still_active = true;
            }
            for (prop, val) in m {
                self.computed.push((a.element_id.clone(), prop, val));
            }
        }
        // fill=none で完了したアニメは破棄（値を出し切ったあと）。
        self.animations
            .retain(|a| !(a.done && a.spec.fill == "none"));

        still_active
    }
}