atmos/os_lib/web_engine/

image.rs

// web_engine/image.rs - Image decode & async loader thread

use alloc::string::String;
use alloc::vec::Vec;
use spin::Mutex;

use super::cache::{read_cache, write_cache};

// ---------------------------------------------------------------------------
// 画像非同期ロードキュー
// ---------------------------------------------------------------------------

pub(super) struct ImageLoadQueue {
    /// フェッチ待ちの画像 src キー（URL またはパス）
    pub pending: Vec<ImageFetchReq>,
    /// デコード完了した (src_key, decoded_image)
    pub results: Vec<(String, super::DecodedImage)>,
    /// 【2026-08-04】稼働中のワーカースレッド数。
    ///
    /// 以前は `thread_active: bool` で**ワーカーが 1 本だけ**だった。
    /// 画像は通信が重く、1 枚取っている間は同じキューの後続が
    /// 一切進まない（実測: ギャラリー画像 3 枚が alt テキストのまま）。
    /// 通信待ちの間はスケジューラへ譲るので、複数本走らせれば
    /// 重い 1 枚が他を止めなくなる。
    pub active_workers: usize,
}

#[derive(Clone)]
pub(super) struct ImageFetchReq {
    pub src_key: String, // image_cache のキーとして使う文字列
    pub is_https: bool,
    pub host: String,
    pub path: String,
    pub is_local: bool, // SylFS からの読み込みの場合 true
    pub owner: u64,     // 発行元エンジン(タブ)の ID。ページ遷移時に保留分を破棄するために使う
}

pub(super) static IMAGE_QUEUE: Mutex<ImageLoadQueue> = Mutex::new(ImageLoadQueue {
    pending: Vec::new(),
    results: Vec::new(),
    active_workers: 0,
});

/// 同時に走らせる画像取得ワーカーの上限。
///
/// TCP ソケット表（32 件）を圧迫しない範囲で、
/// 重い 1 枚が他を止めないだけの本数を確保する。
const MAX_IMAGE_WORKERS: usize = 4;

/// SVG をラスタライズする目標解像度（自然サイズ基準・上限512・最低1）を決める
fn svg_target_size(data: &[u8]) -> (u32, u32) {
    let (w, h) = crate::os_lib::svg::natural_size(data);
    let cap = 512.0f32;
    let scale = (cap / w.max(1.0)).min(cap / h.max(1.0)).clamp(0.01, 1.0);
    // 自然サイズが小さい場合は等倍、大きい場合のみ縮小
    let tw = (w * if w > cap || h > cap { scale } else { 1.0 }).max(1.0) as u32;
    let th = (h * if w > cap || h > cap { scale } else { 1.0 }).max(1.0) as u32;
    (tw.max(1), th.max(1))
}

pub(super) fn decode_image(data: &[u8]) -> Option<super::DecodedImage> {
    crate::debug!("[GPU] TRACE: decode_image start. len={}", data.len());
    // SVG（テキスト）: マジックバイトが無いので先頭を覗いて判定
    {
        let head_len = data.len().min(512);
        if let Ok(head) = core::str::from_utf8(&data[..head_len]) {
            let ht = head.trim_start();
            if ht.starts_with("<svg")
                || ht.starts_with("<?xml")
                || ht.starts_with("<!--") && head.contains("<svg")
            {
                crate::debug!("[GPU] TRACE: decode_image SVG target size parsing...");
                let (tw, th) = svg_target_size(data);
                crate::debug!("[GPU] TRACE: decode_image SVG decoding...");
                if let Some((w, h, rgba)) = crate::os_lib::svg::decode_svg_image(data, tw, th) {
                    crate::debug!("[GPU] TRACE: decode_image SVG success");
                    return Some(super::DecodedImage {
                        width: w,
                        height: h,
                        rgba,
                    });
                }
                crate::debug!("[GPU] TRACE: decode_image SVG failed");
                return None;
            }
        }
    }
    if data.len() > 8 && &data[0..8] == b"\x89PNG\r\n\x1a\n" {
        crate::debug!("[GPU] TRACE: decode_image trying PNG...");
        let mut decoder = zune_png::PngDecoder::new(data);
        if let Ok(pixels) = decoder.decode_raw() {
            if let Some(info) = decoder.get_info() {
                let width = info.width as u32;
                let height = info.height as u32;
                let bpp = pixels.len() / (width as usize * height as usize).max(1);
                const MAX_DIM: u32 = 1024;
                let (out_w, out_h) = if width > MAX_DIM || height > MAX_DIM {
                    if width * MAX_DIM > height * MAX_DIM {
                        (MAX_DIM, (height * MAX_DIM / width).max(1))
                    } else {
                        ((width * MAX_DIM / height).max(1), MAX_DIM)
                    }
                } else {
                    (width, height)
                };
                let mut rgba = alloc::vec::Vec::with_capacity((out_w * out_h * 4) as usize);
                for row in 0..out_h {
                    let src_row = (row * height) / out_h;
                    for col in 0..out_w {
                        let src_col = (col * width) / out_w;
                        let i = (src_row * width + src_col) as usize;
                        let idx = i * bpp;
                        if idx + bpp <= pixels.len() {
                            let (r, g, b, a) = match bpp {
                                1 => (pixels[idx], pixels[idx], pixels[idx], 255),
                                2 => (pixels[idx], pixels[idx], pixels[idx], pixels[idx + 1]),
                                3 => (pixels[idx], pixels[idx + 1], pixels[idx + 2], 255),
                                4 => (
                                    pixels[idx],
                                    pixels[idx + 1],
                                    pixels[idx + 2],
                                    pixels[idx + 3],
                                ),
                                _ => (0, 0, 0, 255),
                            };
                            rgba.push(r);
                            rgba.push(g);
                            rgba.push(b);
                            rgba.push(a);
                        }
                    }
                }
                crate::debug!(
                    "[GPU] TRACE: decode_image PNG success {}x{} -> {}x{}",
                    width,
                    height,
                    out_w,
                    out_h
                );
                return Some(super::DecodedImage {
                    width: out_w,
                    height: out_h,
                    rgba,
                });
            }
        }
        crate::debug!("[GPU] TRACE: decode_image PNG failed");
    } else if data.len() > 2 && data[0] == 0xFF && data[1] == 0xD8 {
        crate::debug!("[GPU] TRACE: decode_image trying JPEG...");
        // 全体をデコードする前に SOF マーカから寸法だけ読む。
        //
        // 【2026-08-05 訂正】ここには「協調マルチタスク（プリエンプション無し）なので
        // UI が固まる」と書いてあったが、**プリエンプションは実装済みで配線もされている**
        // （`interrupt.rs:104`）。UI が止まっていた真因はヒープの spin ロックが
        // プリエンプション可能だったことで、`allocator.rs` 側で修正済み
        // （42 秒 → 10 秒、`spec/resource_loading.md`）。
        //
        // この寸法チェックは、桁違いの画像でメモリを食い潰さないための上限として残す。
        const MAX_JPEG_DIM: u32 = 8192;
        {
            let mut i = 2usize;
            let mut skip = false;
            while i + 3 < data.len() {
                if data[i] != 0xFF {
                    break;
                }
                let marker = data[i + 1];
                let is_sof =
                    matches!(marker, 0xC0..=0xC3 | 0xC5..=0xC7 | 0xC9..=0xCB | 0xCD..=0xCF);
                if is_sof && i + 8 < data.len() {
                    let h = u16::from_be_bytes([data[i + 5], data[i + 6]]) as u32;
                    let w = u16::from_be_bytes([data[i + 7], data[i + 8]]) as u32;
                    if w > MAX_JPEG_DIM || h > MAX_JPEG_DIM {
                        crate::debug!(
                            "[GPU] TRACE: decode_image JPEG too large {}x{}, skipping (max {})",
                            w,
                            h,
                            MAX_JPEG_DIM
                        );
                        skip = true;
                    }
                    break;
                }
                if i + 3 >= data.len() {
                    break;
                }
                let seg_len = u16::from_be_bytes([data[i + 2], data[i + 3]]) as usize;
                if seg_len < 2 {
                    break;
                }
                i += 2 + seg_len;
            }
            if skip {
                return None;
            }
        }
        let mut decoder = zune_jpeg::JpegDecoder::new(data);
        // 【2026-07-30診断】協調マルチタスクでは CPU 律速のデコードが
        // 別スレッドでも全体を止める。所要時間を実測する。
        let t0 = crate::kernel::timer::get_ticks();
        let decoded = decoder.decode();
        crate::warn!(
            "[IMGDIAG] jpeg decode ok={} bytes={} elapsed_ticks={}",
            decoded.is_ok(),
            data.len(),
            crate::kernel::timer::get_ticks().wrapping_sub(t0)
        );
        if let Ok(pixels) = decoded {
            if let Some(info) = decoder.info() {
                let width = info.width as u32;
                let height = info.height as u32;
                let bpp = pixels.len() / (width as usize * height as usize).max(1);
                const MAX_DIM: u32 = 1024;
                let (out_w, out_h) = if width > MAX_DIM || height > MAX_DIM {
                    if width * MAX_DIM > height * MAX_DIM {
                        (MAX_DIM, (height * MAX_DIM / width).max(1))
                    } else {
                        ((width * MAX_DIM / height).max(1), MAX_DIM)
                    }
                } else {
                    (width, height)
                };
                let mut rgba = alloc::vec::Vec::with_capacity((out_w * out_h * 4) as usize);
                for row in 0..out_h {
                    let src_row = (row * height) / out_h;
                    for col in 0..out_w {
                        let src_col = (col * width) / out_w;
                        let i = (src_row * width + src_col) as usize;
                        let idx = i * bpp;
                        if idx + bpp <= pixels.len() {
                            let (r, g, b) = match bpp {
                                1 => (pixels[idx], pixels[idx], pixels[idx]),
                                3 => (pixels[idx], pixels[idx + 1], pixels[idx + 2]),
                                _ => (0, 0, 0),
                            };
                            rgba.push(r);
                            rgba.push(g);
                            rgba.push(b);
                            rgba.push(255);
                        }
                    }
                }
                crate::debug!(
                    "[GPU] TRACE: decode_image JPEG success {}x{} -> {}x{}",
                    width,
                    height,
                    out_w,
                    out_h
                );
                return Some(super::DecodedImage {
                    width: out_w,
                    height: out_h,
                    rgba,
                });
            }
        }
        crate::debug!("[GPU] TRACE: decode_image JPEG failed");
    } else if data.len() > 6 && &data[0..3] == b"GIF" {
        crate::debug!("[GPU] TRACE: decode_image trying GIF...");
        if let Some(img) = decode_gif(data) {
            crate::debug!("[GPU] TRACE: decode_image GIF success");
            return Some(img);
        }
        crate::debug!("[GPU] TRACE: decode_image GIF failed");
    } else if data.len() > 12 && &data[0..4] == b"RIFF" && &data[8..12] == b"WEBP" {
        crate::debug!("[GPU] TRACE: decode_image trying WEBP...");
        if let Some((w, h, rgba)) = crate::os_lib::webp::decode_webp(data) {
            crate::debug!("[GPU] TRACE: decode_image WEBP success");
            return Some(super::DecodedImage {
                width: w,
                height: h,
                rgba,
            });
        }
        crate::debug!("[GPU] TRACE: decode_image WEBP failed");
    } else if data.len() >= 54 && &data[0..2] == b"BM" {
        crate::debug!("[GPU] TRACE: decode_image trying BMP...");
        let off_bits = u32::from_le_bytes(data[10..14].try_into().unwrap_or([0; 4])) as usize;
        let width = i32::from_le_bytes(data[18..22].try_into().unwrap_or([0; 4]));
        let height = i32::from_le_bytes(data[22..26].try_into().unwrap_or([0; 4]));
        let bit_count = u16::from_le_bytes(data[28..30].try_into().unwrap_or([0; 2]));
        let compression = u32::from_le_bytes(data[30..34].try_into().unwrap_or([0; 4]));
        if compression == 0 && (bit_count == 24 || bit_count == 32) {
            let abs_h = height.unsigned_abs();
            let bpp = (bit_count / 8) as usize;
            let row_stride = (width.unsigned_abs() as usize * bpp).div_ceil(4) * 4;
            let mut rgba =
                alloc::vec::Vec::with_capacity((width.unsigned_abs() * abs_h * 4) as usize);
            for row in 0..abs_h {
                let src_row = if height > 0 { abs_h - 1 - row } else { row };
                let row_off = off_bits + (src_row as usize * row_stride);
                for col in 0..width.unsigned_abs() {
                    let pix_off = row_off + (col as usize * bpp);
                    if pix_off + bpp <= data.len() {
                        let b = data[pix_off];
                        let g = data[pix_off + 1];
                        let r = data[pix_off + 2];
                        let a = if bpp == 4 { data[pix_off + 3] } else { 255 };
                        rgba.push(r);
                        rgba.push(g);
                        rgba.push(b);
                        rgba.push(a);
                    } else {
                        rgba.push(0);
                        rgba.push(0);
                        rgba.push(0);
                        rgba.push(255);
                    }
                }
            }
            crate::debug!("[GPU] TRACE: decode_image BMP success");
            return Some(super::DecodedImage {
                width: width.unsigned_abs(),
                height: abs_h,
                rgba,
            });
        }
        crate::debug!("[GPU] TRACE: decode_image BMP failed");
    }
    crate::debug!("[GPU] TRACE: decode_image unsupported/unknown");
    None
}

/// GIF (87a/89a) デコーダ。先頭イメージフレームを RGBA で返す。
/// グローバル/ローカルパレット・LZW・透過(Graphic Control Extension)・インターレース対応。
/// アニメーションは先頭フレームのみ描画（静止画扱い）。
fn decode_gif(data: &[u8]) -> Option<super::DecodedImage> {
    let mut p = 6usize; // "GIF87a"/"GIF89a" をスキップ
    if data.len() < 13 {
        return None;
    }

    let screen_w = u16::from_le_bytes([data[p], data[p + 1]]) as u32;
    let screen_h = u16::from_le_bytes([data[p + 2], data[p + 3]]) as u32;
    let packed = data[6 + 4];
    p = 13;

    // グローバルカラーテーブル
    let gct_flag = (packed & 0x80) != 0;
    let gct_size = 2usize << (packed & 0x07); // 2^(n+1)
    let mut global_palette: Vec<[u8; 3]> = Vec::new();
    if gct_flag {
        for _ in 0..gct_size {
            if p + 3 > data.len() {
                return None;
            }
            global_palette.push([data[p], data[p + 1], data[p + 2]]);
            p += 3;
        }
    }

    let mut transparent_idx: Option<u8> = None;

    // ブロックを走査して先頭イメージを見つける
    while p < data.len() {
        match data[p] {
            0x21 => {
                // 拡張ブロック
                p += 1;
                if p >= data.len() {
                    return None;
                }
                let label = data[p];
                p += 1;
                if label == 0xF9 {
                    // Graphic Control Extension: 透過色インデックスを取得
                    if p < data.len() {
                        let blk_size = data[p] as usize; // 通常 4
                        if p + 1 + blk_size <= data.len() && blk_size >= 4 {
                            let gce_packed = data[p + 1];
                            if gce_packed & 0x01 != 0 {
                                transparent_idx = Some(data[p + 4]);
                            }
                        }
                    }
                }
                // サブブロックをスキップ
                p = skip_gif_subblocks(data, p)?;
            }
            0x2C => {
                // イメージ記述子
                if p + 10 > data.len() {
                    return None;
                }
                let img_w = u16::from_le_bytes([data[p + 5], data[p + 6]]) as u32;
                let img_h = u16::from_le_bytes([data[p + 7], data[p + 8]]) as u32;
                let ipacked = data[p + 9];
                let lct_flag = (ipacked & 0x80) != 0;
                let interlace = (ipacked & 0x40) != 0;
                let lct_size = 2usize << (ipacked & 0x07);
                p += 10;

                // ローカルカラーテーブル
                let palette = if lct_flag {
                    let mut lp: Vec<[u8; 3]> = Vec::new();
                    for _ in 0..lct_size {
                        if p + 3 > data.len() {
                            return None;
                        }
                        lp.push([data[p], data[p + 1], data[p + 2]]);
                        p += 3;
                    }
                    lp
                } else {
                    global_palette.clone()
                };
                if palette.is_empty() {
                    return None;
                }
                if img_w == 0 || img_h == 0 || img_w > 4096 || img_h > 4096 {
                    return None;
                }

                // LZW 最小コードサイズ
                if p >= data.len() {
                    return None;
                }
                let min_code_size = data[p];
                p += 1;

                // データサブブロックを結合
                let mut lzw_data: Vec<u8> = Vec::new();
                loop {
                    if p >= data.len() {
                        return None;
                    }
                    let bs = data[p] as usize;
                    p += 1;
                    if bs == 0 {
                        break;
                    }
                    if p + bs > data.len() {
                        return None;
                    }
                    lzw_data.extend_from_slice(&data[p..p + bs]);
                    p += bs;
                }

                let indices = gif_lzw_decode(&lzw_data, min_code_size, (img_w * img_h) as usize)?;

                // インデックス → RGBA（インターレース解除込み）
                let total = (img_w * img_h) as usize;
                let mut rgba = alloc::vec![0u8; total * 4];
                let row_order: Vec<u32> = if interlace {
                    gif_interlace_rows(img_h)
                } else {
                    (0..img_h).collect()
                };
                let mut src = 0usize;
                for &dst_row in row_order.iter() {
                    for col in 0..img_w {
                        if src >= indices.len() {
                            break;
                        }
                        let ci = indices[src];
                        src += 1;
                        let dst = ((dst_row * img_w + col) as usize) * 4;
                        if Some(ci) == transparent_idx {
                            rgba[dst + 3] = 0; // 透過
                        } else {
                            let c = palette.get(ci as usize).copied().unwrap_or([0, 0, 0]);
                            rgba[dst] = c[0];
                            rgba[dst + 1] = c[1];
                            rgba[dst + 2] = c[2];
                            rgba[dst + 3] = 255;
                        }
                    }
                }
                let _ = (screen_w, screen_h);
                return Some(super::DecodedImage {
                    width: img_w,
                    height: img_h,
                    rgba,
                });
            }
            0x3B => break, // トレーラ
            _ => {
                p += 1;
            }
        }
    }
    None
}

/// GIF サブブロック列を読み飛ばし、終端(0x00)の次位置を返す
fn skip_gif_subblocks(data: &[u8], mut p: usize) -> Option<usize> {
    loop {
        if p >= data.len() {
            return None;
        }
        let bs = data[p] as usize;
        p += 1;
        if bs == 0 {
            return Some(p);
        }
        p += bs;
    }
}

/// GIF インターレース行順を展開（4パス）
fn gif_interlace_rows(h: u32) -> Vec<u32> {
    let mut rows = Vec::with_capacity(h as usize);
    let mut y = 0;
    while y < h {
        rows.push(y);
        y += 8;
    }
    y = 4;
    while y < h {
        rows.push(y);
        y += 8;
    }
    y = 2;
    while y < h {
        rows.push(y);
        y += 4;
    }
    y = 1;
    while y < h {
        rows.push(y);
        y += 2;
    }
    rows
}

/// GIF の可変長 LZW デコード。出力はパレットインデックス列。
fn gif_lzw_decode(data: &[u8], min_code_size: u8, expected: usize) -> Option<Vec<u8>> {
    let clear_code = 1u16 << min_code_size;
    let end_code = clear_code + 1;
    let mut code_size = min_code_size + 1;

    // 辞書: 各エントリは「前エントリ index」と「末尾バイト」。文字列は逆引きで復元。
    let mut prefix: Vec<i32> = Vec::with_capacity(4096);
    let mut suffix: Vec<u8> = Vec::with_capacity(4096);
    let reset_dict = |prefix: &mut Vec<i32>, suffix: &mut Vec<u8>| {
        prefix.clear();
        suffix.clear();
        for i in 0..clear_code {
            prefix.push(-1);
            suffix.push(i as u8);
        }
        prefix.push(-1);
        suffix.push(0); // clear_code
        prefix.push(-1);
        suffix.push(0); // end_code
    };
    reset_dict(&mut prefix, &mut suffix);

    let mut out: Vec<u8> = Vec::with_capacity(expected);
    let mut bit_pos = 0usize;
    let total_bits = data.len() * 8;
    let mut prev_code: i32 = -1;
    let mut stack: Vec<u8> = Vec::with_capacity(4096);

    let read_code = |bit_pos: &mut usize, code_size: u8| -> Option<u16> {
        if *bit_pos + code_size as usize > total_bits {
            return None;
        }
        let mut val = 0u32;
        for i in 0..code_size as usize {
            let byte = data[(*bit_pos + i) >> 3];
            let bit = (byte >> ((*bit_pos + i) & 7)) & 1;
            val |= (bit as u32) << i;
        }
        *bit_pos += code_size as usize;
        Some(val as u16)
    };

    while let Some(code) = read_code(&mut bit_pos, code_size) {
        if code == clear_code {
            reset_dict(&mut prefix, &mut suffix);
            code_size = min_code_size + 1;
            prev_code = -1;
            continue;
        }
        if code == end_code {
            break;
        }

        // 現コードを文字列に展開（stack に逆順で積む）
        stack.clear();
        let mut cur = code as i32;
        let first_byte;
        if (cur as usize) < suffix.len() {
            // 既知コード
            while cur >= 0 && (cur as usize) < suffix.len() {
                stack.push(suffix[cur as usize]);
                cur = prefix[cur as usize];
            }
            first_byte = *stack.last()?;
        } else {
            // 未知コード（KwKwK ケース）: prev + prev先頭
            if prev_code < 0 {
                return None;
            }
            let mut c2 = prev_code;
            while c2 >= 0 && (c2 as usize) < suffix.len() {
                stack.push(suffix[c2 as usize]);
                c2 = prefix[c2 as usize];
            }
            first_byte = *stack.last()?;
            stack.insert(0, first_byte); // 末尾に first を追加（逆順なので先頭 insert）
        }

        // stack を正順で出力
        for &b in stack.iter().rev() {
            out.push(b);
        }

        // 辞書追加: prev + first_byte
        if prev_code >= 0 && suffix.len() < 4096 {
            prefix.push(prev_code);
            suffix.push(first_byte);
            // コードサイズ拡張
            if suffix.len() == (1usize << code_size) && code_size < 12 {
                code_size += 1;
            }
        }
        prev_code = code as i32;

        if out.len() >= expected {
            break;
        }
    }

    Some(out)
}

/// 溜まっている取得要求に対してワーカーを起こし直す。
/// 理由は `font_queue::pump` と同じ（門が閉じている間の投入を拾い直す）。
pub(super) fn pump() {
    // 【2026-09-06 バグ修正】`font_queue::pump` と同じ理由で `try_lock`。
    // 毎フレーム `draw()` から呼ばれるため、高優先度側がここで
    // 回り続けると低優先度のワーカーが走れなくなる。
    let Some(mut q) = IMAGE_QUEUE.try_lock() else {
        return;
    };
    // 【2026-08-25】パニックで死んだワーカーぶんの枠を戻す。
    let dead = super::fetch_limit::take_image_deaths();
    if dead > 0 {
        crate::warn!("[IMG] パニックで死んだワーカー {} 本を回収", dead);
        q.active_workers = q.active_workers.saturating_sub(dead);
        store_worker_count(q.active_workers);
    }
    if q.pending.is_empty() {
        return;
    }
    // CSS など、より優先度の高いリソースが待っている間は起こさない。
    let higher = super::font_queue::pending_higher_than(
        super::fetch_limit::Kind::Image.priority(),
    );
    if q.active_workers < MAX_IMAGE_WORKERS
        && super::fetch_limit::may_spawn_lower(
            super::fetch_limit::main_load_in_flight(),
            super::fetch_limit::active(),
            q.pending.len(),
            higher,
        )
        && super::fetch_limit::try_acquire(q.pending.len())
    {
        q.active_workers += 1;
        store_worker_count(q.active_workers);
        // 【2026-08-05 バグ修正】`spawn` はヒープ不足で **0 を返す**。
        // 戻り値を見ずに枠だけ確保していたため、失敗すると
        // 「ワーカーは居ないのに枠は埋まったまま」になり、
        // 以後**永久にワーカーを起こせなくなる**。失敗したら必ず返す。
        let pid = crate::kernel::scheduler::spawn(
            image_loader_thread,
            crate::kernel::scheduler::Priority::Low,
            "img_load",
        );
        if pid == 0 {
            q.active_workers = q.active_workers.saturating_sub(1);
            store_worker_count(q.active_workers);
            super::fetch_limit::release();
        }
    }
}

fn image_loader_thread() {
    // 枠の所有を自分の PID で宣言する（`fetch_limit` 参照）。
    let my_pid = crate::kernel::scheduler::get_current_process_id().unwrap_or(0);
    super::fetch_limit::claim(my_pid, super::fetch_limit::KIND_IMAGE);
    loop {
        // pop と「キューが空なら終了」の判定を同一ロック内で行い、
        // enqueue_image との終了レース（アイテムが永久に処理されない）を防ぐ。
        let req = {
            let mut q = IMAGE_QUEUE.lock();
            let popped = q.pending.pop();
            IMG_PENDING.store(q.pending.len(), core::sync::atomic::Ordering::Release);
            match popped {
                Some(r) => r,
                None => {
                    q.active_workers = q.active_workers.saturating_sub(1);
                    store_worker_count(q.active_workers);
                    drop(q);
                    super::fetch_limit::unclaim(my_pid);
                    super::fetch_limit::release();
                    // 【2026-08-05 重大】ここは `return` だった。
                    // カーネルスレッドの入口関数から `return` しても
                    // スレッドは終わらず、入口から再実行され続ける
                    // （フォント側で実測 3 億回。`font_queue.rs` 参照）。
                    crate::kernel::scheduler::exit();
                }
            }
        };

        // 【2026-08-05 計測】取得とデコードのどちらが支配的かを切り分ける。
        // これが分からないまま片方だけ速くしても意味が無い。
        // 目的: 画像パスの律速の特定。1 画像につき 1 回で毎フレームではない。
        // 破棄条件: 律速が確定して対処が済んだら削除する。
        let t_fetch_start = crate::kernel::timer::get_ticks();
        let polls_before =
            crate::kernel::net::tcp::RECV_POLLS.load(core::sync::atomic::Ordering::Relaxed);
        let ec_before =
            crate::kernel::usb::ETH_POLL_CALLS.load(core::sync::atomic::Ordering::Relaxed);
        let et_before =
            crate::kernel::usb::ETH_POLL_US.load(core::sync::atomic::Ordering::Relaxed);
        let em_before =
            crate::kernel::usb::ETH_POLL_LOCK_MISS.load(core::sync::atomic::Ordering::Relaxed);
        let hc_before =
            crate::kernel::usb::HID_POLL_CALLS.load(core::sync::atomic::Ordering::Relaxed);
        let ht_before =
            crate::kernel::usb::HID_POLL_US.load(core::sync::atomic::Ordering::Relaxed);
        let he_before =
            crate::kernel::usb::HID_ETH_US.load(core::sync::atomic::Ordering::Relaxed);
        let frames_before =
            crate::kernel::usb::RX_FRAME_COUNT.load(core::sync::atomic::Ordering::Relaxed);
        let mut from_cache = false;
        let raw: Option<Vec<u8>> = if req.is_local {
            // 【2026-08-05】ここは**ワーカースレッド**（最大 4 本）の中。
            // `cache.rs` 側だけロックしても、この直接呼び出しが残っていると
            // 同じビットマップを無防備に触ることになる
            // （`kernel::fs::FS_LOCK` の説明を参照）。
            let _fs_guard = crate::kernel::fs::FS_LOCK.lock();
            let fs = crate::kernel::fs::get_fs();
            fs.read_file(&req.path).map(|(_m, d)| d)
        } else {
            if let Some(cached) = read_cache(&req.host, &req.path) {
                from_cache = true;
                Some(cached)
            } else {
                let stack = crate::kernel::net_stack::TcpIpStack::new();
                match stack.web_get_binary(req.is_https, &req.host, &req.path) {
                    Ok(d) => {
                        write_cache(&req.host, &req.path, &d);
                        Some(d)
                    }
                    Err(e) => {
                        crate::warn!(
                            "IMAGE_LOADER: fetch failed for {}{}: {}",
                            req.host,
                            req.path,
                            e.message
                        );
                        None
                    }
                }
            }
        };

        if let Some(bytes) = raw {
            // 【2026-07-30】サイズ・画素数による打ち切りは撤去した。
            // 取得は非同期（このスレッド）なので描画をブロックしない。
            // 「大きいから捨てる」のはブラウザの挙動として誤り
            // （`spec/resource_loading.md` の R-2）。
            // 時間がかかっても最後まで取得し、デコードできたら反映する。
            let t_fetch_end = crate::kernel::timer::get_ticks();
            let _t_dec = super::perf::start();
            let decoded_result = decode_image(&bytes);
            super::perf::add(super::perf::Slot::ImageDecode, _t_dec);
            crate::warn!(
                "[IMGPERF] path={} bytes={} cache={} fetch={}tick decode={}tick polls={} eth_calls={} eth_us={} eth_lockmiss={} frames={} hid_calls={} hid_us={} hid_eth_us={}",
                req.path,
                bytes.len(),
                from_cache,
                t_fetch_end.wrapping_sub(t_fetch_start),
                crate::kernel::timer::get_ticks().wrapping_sub(t_fetch_end),
                crate::kernel::net::tcp::RECV_POLLS
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(polls_before),
                crate::kernel::usb::ETH_POLL_CALLS
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(ec_before),
                crate::kernel::usb::ETH_POLL_US
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(et_before),
                crate::kernel::usb::ETH_POLL_LOCK_MISS
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(em_before),
                crate::kernel::usb::RX_FRAME_COUNT
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(frames_before),
                crate::kernel::usb::HID_POLL_CALLS
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(hc_before),
                crate::kernel::usb::HID_POLL_US
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(ht_before),
                crate::kernel::usb::HID_ETH_US
                    .load(core::sync::atomic::Ordering::Relaxed)
                    .wrapping_sub(he_before)
            );
            match decoded_result {
                Some(decoded) => {
                    // 【2026-08-02】取得・デコードの完了が**どこにも出ていなかった**ため、
                    // 「画像が届いていないのか、届いたが描かれていないのか」を
                    // 切り分けられなかった。フォント側（`[FONT] 背景取得完了`）と
                    // 揃えて 1 画像につき 1 回だけ出す（`spec/logging_policy.md` L-3 の
                    // 「節目で 1 回」に該当。毎フレームは出さない）。
                    crate::warn!(
                        "[IMG] 取得・デコード完了 host={} path={} bytes={} {}x{}",
                        req.host,
                        req.path,
                        bytes.len(),
                        decoded.width,
                        decoded.height
                    );
                    let mut q = IMAGE_QUEUE.lock();
                    q.results.push((req.src_key, decoded));
                    store_results_len(q.results.len());
                }
                None => {
                    // 非対応フォーマット（WebP/GIF/SVG 等）や破損データ
                    let fmt =
                        if bytes.len() >= 12 && &bytes[0..4] == b"RIFF" && &bytes[8..12] == b"WEBP"
                        {
                            "WebP (unsupported)"
                        } else if bytes.len() >= 6
                            && (&bytes[0..6] == b"GIF89a" || &bytes[0..6] == b"GIF87a")
                        {
                            "GIF (unsupported)"
                        } else if bytes.len() >= 5 && &bytes[0..5] == b"<?xml"
                            || (bytes.len() >= 4 && &bytes[0..4] == b"<svg")
                        {
                            "SVG (unsupported)"
                        } else {
                            "unknown/corrupt"
                        };
                    crate::warn!(
                        "IMAGE_LOADER: decode failed for {} ({} bytes, format={})",
                        req.src_key,
                        bytes.len(),
                        fmt
                    );
                }
            }
        }
    }
}

/// デコード完了した画像が「取り込み待ち」で存在するか（エッジトリガ再描画用）。
/// 旧実装は pending/thread_active も見ていたため、画像のロード待ちの間ずっと
/// 全画面再描画が走り続け（画面が波打つ）原因になっていた。
/// 完了結果がある時だけ true を返すことで、完了ごとに1回だけ再描画する。
pub fn image_results_ready() -> bool {
    IMG_RESULTS.load(core::sync::atomic::Ordering::Acquire) > 0
}

/// 取り込み待ちの完了件数の写し。
///
/// 【2026-09-04 バグ修正】ここは `IMAGE_QUEUE.lock()` していた。
///
/// この関数は**毎フレームの再描画判定**（`needs_timer_redraw`）から
/// 呼ばれる。呼び出し元は提示ループ側の高優先度な文脈で、
/// `spin::Mutex` は譲らずに回り続けるので、低優先度のワーカーが
/// このロックを握っている間に入ると**ワーカーが走れず解放もされない**。
/// 同じ優先度逆転は `pending_count`／`font_queue::pending_len` で
/// 既に踏んでおり（実測で取得が残ったまま静止）、
/// **待機・再描画の判定はロックを取ってはいけない**という規則になっている。
/// ここはその規則から漏れていた。
///
/// 正確さは、`results` を変更する側（既にロックを持っている側）が
/// 毎回ここへ書き写すことで保つ。
static IMG_RESULTS: core::sync::atomic::AtomicUsize =
    core::sync::atomic::AtomicUsize::new(0);

/// `results` の件数を写す。ロックを持っている側から呼ぶ。
pub(super) fn store_results_len(n: usize) {
    IMG_RESULTS.store(n, core::sync::atomic::Ordering::Release);
}

/// 画像 src をキューに追加し、必要ならローダースレッドを起動する
/// 取得待ちの画像枚数の写し。
///
/// 【2026-08-25 バグ修正】以前はここで `IMAGE_QUEUE.lock()` していた。
/// 待機判定（`[IDLE]` 行）はウィンドウマネージャの提示ループから
/// 呼ばれる。あちらは高優先度で、`spin::Mutex` は譲らずに回るので、
/// 低優先度のワーカーがこのロックを握っている間に提示ループが
/// スピンに入ると、**ワーカーが走れず解放もされない**（優先度逆転）。
/// 実測で取得が 7 件やり残しのまま 900 秒動かなくなった。
///
/// 待機判定は**ロックを取らずに読む**。正確さは、キューを
/// 変更する側（ロックを持っている側）が毎回書き写すことで保つ。
static IMG_PENDING: core::sync::atomic::AtomicUsize =
    core::sync::atomic::AtomicUsize::new(0);

pub(super) fn pending_count() -> usize {
    IMG_PENDING.load(core::sync::atomic::Ordering::Acquire)
}

/// 稼働中の画像ワーカー本数の写し（`font_queue::worker_count` と同じ理由）。
static IMG_WORKERS: core::sync::atomic::AtomicUsize =
    core::sync::atomic::AtomicUsize::new(0);

pub(super) fn worker_count() -> usize {
    IMG_WORKERS.load(core::sync::atomic::Ordering::Acquire)
}

/// 稼働本数を写す。ロックを持っている側から呼ぶ。
pub(super) fn store_worker_count(n: usize) {
    IMG_WORKERS.store(n, core::sync::atomic::Ordering::Release);
}

pub(super) fn enqueue_image(req: ImageFetchReq) {
    let mut q = IMAGE_QUEUE.lock();
    // 既にキューにある場合はスキップ
    if q.pending.iter().any(|r| r.src_key == req.src_key) {
        return;
    }
    q.pending.push(req);
    IMG_PENDING.store(q.pending.len(), core::sync::atomic::Ordering::Release);
    // 待ち行列があるうちはワーカーを増やす（上限まで）。
    // 【2026-08-05】同上。上限は `fetch_limit` が全体で持つ。
    if q.active_workers < MAX_IMAGE_WORKERS
        && super::fetch_limit::try_acquire(q.pending.len())
    {
        q.active_workers += 1;
        store_worker_count(q.active_workers);
        // 【2026-08-05 バグ修正】`spawn` はヒープ不足で **0 を返す**。
        // 戻り値を見ずに枠だけ確保していたため、失敗すると
        // 「ワーカーは居ないのに枠は埋まったまま」になり、
        // 以後**永久にワーカーを起こせなくなる**。失敗したら必ず返す。
        let pid = crate::kernel::scheduler::spawn(
            image_loader_thread,
            crate::kernel::scheduler::Priority::Normal,
            "img_load",
        );
        if pid == 0 {
            q.active_workers = q.active_workers.saturating_sub(1);
            store_worker_count(q.active_workers);
            super::fetch_limit::release();
        }
    }
}

// ───────────── canvas から読むための共有 ─────────────

/// デコード済み画像を `src` で引ける共有の置き場。
///
/// `WebEngine::image_cache` は `WebEngine` の中にあり、JS 組み込み
/// （`drawImage`）からは届かない。かといって複製すると数 MB の写真を
/// 二重に持つことになるので、`Arc` で**同じ画素を共有**する。
///
/// 【注意】ここのロックは**待機・再描画の判定から取ってはいけない**。
/// 提示ループ側は高優先度で `spin::Mutex` は譲らないため、
/// 低優先度のワーカーが握っていると優先度逆転で止まる
/// （`image_results_ready` で実際に踏んだ）。
/// 読むのは JS の `drawImage` からだけにし、`Arc` を複製して即座に放す。
static SHARED_IMAGES: spin::Mutex<
    alloc::collections::BTreeMap<alloc::string::String, alloc::sync::Arc<super::DecodedImage>>,
> = spin::Mutex::new(alloc::collections::BTreeMap::new());

/// 共有の置き場へ登録する。取り込み側から呼ぶ。
pub fn share_image(key: &str, img: alloc::sync::Arc<super::DecodedImage>) {
    SHARED_IMAGES.lock().insert(alloc::string::String::from(key), img);
}

/// `src` からデコード済み画像を引く。無ければ `None`。
pub fn shared_image(key: &str) -> Option<alloc::sync::Arc<super::DecodedImage>> {
    SHARED_IMAGES.lock().get(key).cloned()
}

/// ページを移ったら捨てる（`image_cache` の破棄と対で呼ぶ）。
pub fn clear_shared_images() {
    SHARED_IMAGES.lock().clear();
}