atmos/kernel/

vector_font.rs

// src/vector_font.rs - ベクトルフォント（TrueType）レンダリングエンジン
// ttf-parser を使用したアウトライン抽出、4x4スーパーサンプリングEven-Oddラスタライザ、グリフキャッシュ。

#![allow(dead_code)]

extern crate alloc;
use alloc::collections::BTreeMap;
use alloc::string::String;
use alloc::vec::Vec;

/// Brotli 圧縮されたデータを取り、展開されたバイト列を返す。
/// Brotli 展開用のヒープ確保アロケータ。
///
/// 【2026-08-03 発見・修正】従来は `alloc_no_stdlib::StackAllocator` に
/// **型ごとにスロットを 1 個**しか渡していなかった（`[&mut [u8]; 1]`）。
/// Brotli は同じ型の領域を複数同時に要求するため、2 個目以降が取れず
/// `BrotliDecompressStream` から**戻ってこなくなる**。
///
/// 実測（`fa-v4compatibility.woff2`, 4132 バイト）:
/// ```text
/// [FONT][BR] u8 プール確保 完了
/// [FONT][BR] u32 プール確保 完了
/// [FONT][BR] HuffmanCode プール確保 完了
/// [FONT][BR] BrotliState 構築 完了
/// [FONT][BR] 展開開始 in=4060 out_cap=8750
/// （以降なし。待機 300/420/540 秒すべて同じ地点で停止）
/// ```
///
/// カーネルには 512MB のヒープがあるので、固定プールをやめて
/// **必要なだけヒープから確保する**。プールサイズの見積りが不要になり、
/// 「大きいフォントで枯渇して落ちる／止まる」という失敗モードごと消える。
struct HeapBuf<T>(Vec<T>);

impl<T> Default for HeapBuf<T> {
    fn default() -> Self {
        Self(Vec::new())
    }
}

impl<T> alloc_no_stdlib::SliceWrapper<T> for HeapBuf<T> {
    fn slice(&self) -> &[T] {
        &self.0
    }
}

impl<T> alloc_no_stdlib::SliceWrapperMut<T> for HeapBuf<T> {
    fn slice_mut(&mut self) -> &mut [T] {
        &mut self.0
    }
}

struct HeapAllocator;

impl<T: Clone + Default> alloc_no_stdlib::Allocator<T> for HeapAllocator {
    type AllocatedMemory = HeapBuf<T>;

    /// 計算量: **O(len)**（ゼロ初期化）。
    fn alloc_cell(&mut self, len: usize) -> HeapBuf<T> {
        HeapBuf(alloc::vec![T::default(); len])
    }

    /// 解放は `Vec` の Drop に任せる。
    fn free_cell(&mut self, _data: HeapBuf<T>) {}
}

/// WOFF2 の Brotli ストリームを展開する。
///
/// 計算量: **O(展開後サイズ)**。
///
/// 失敗は必ずログに残す（`spec/logging_policy.md` L-1）。
pub fn decompress_brotli(compressed: &[u8], decompressed_size: usize) -> Option<Vec<u8>> {
    let mut s = brotli_decompressor::BrotliState::new(
        HeapAllocator,
        HeapAllocator,
        HeapAllocator,
    );

    // 展開結果が 0 バイトの場合に `available_out` が最初から 0 だと
    // ストリーミングデコーダが `ResultSuccess` ではなく `NeedsMoreOutput` を
    // 返すため、最小 16 バイトの余裕を持たせる（2026-07-22 に自己テストで確認）。
    let mut out_vec = alloc::vec![0u8; decompressed_size.max(16)];

    let mut available_in: usize = compressed.len();
    let mut input_offset: usize = 0;
    let mut available_out: usize = out_vec.len();
    let mut output_offset: usize = 0;
    let mut total_out: usize = 0;

    let result = brotli_decompressor::BrotliDecompressStream(
        &mut available_in,
        &mut input_offset,
        compressed,
        &mut available_out,
        &mut output_offset,
        &mut out_vec,
        &mut total_out,
        &mut s,
    );

    if matches!(result, brotli_decompressor::BrotliResult::ResultSuccess) {
        out_vec.truncate(total_out);
        Some(out_vec)
    } else {
        crate::warn!(
            "[FONT][BR] Brotli 展開に失敗 result={:?} in={} total_out={} in_left={}",
            result,
            compressed.len(),
            total_out,
            available_in
        );
        None
    }
}

static WOFF2_KNOWN_TAGS: [&[u8; 4]; 63] = [
    b"cmap", b"head", b"hhea", b"hmtx", b"maxp", b"name", b"OS/2", b"post",
    b"cvt ", b"fpgm", b"glyf", b"loca", b"prep", b"CFF ", b"VORG", b"EBDT",
    b"EBLC", b"gasp", b"hdmx", b"kern", b"LTSH", b"PCLT", b"VDMX", b"vhea",
    b"vmtx", b"BASE", b"GDEF", b"GPOS", b"GSUB", b"JSTF", b"DSIG", b"MATH",
    b"CBDT", b"CBLC", b"COLR", b"CPAL", b"SVG ", b"sbix", b"acnt", b"avar",
    b"bdat", b"bloc", b"bsln", b"cvar", b"fdsc", b"fmtx", b"fvar", b"gvar",
    b"hsty", b"just", b"lcar", b"mort", b"morx", b"opbd", b"prop", b"trak",
    b"Zapf", b"Silf", b"Gloc", b"Glat", b"Feat", b"Sill", b"SVG ",
];

fn read_woff2_uint16(data: &[u8], offset: &mut usize) -> Option<u16> {
    if *offset + 2 > data.len() {
        return None;
    }
    let val = u16::from_be_bytes([data[*offset], data[*offset + 1]]);
    *offset += 2;
    Some(val)
}

fn read_woff2_uint32(data: &[u8], offset: &mut usize) -> Option<u32> {
    if *offset + 4 > data.len() {
        return None;
    }
    let val = u32::from_be_bytes([
        data[*offset],
        data[*offset + 1],
        data[*offset + 2],
        data[*offset + 3],
    ]);
    *offset += 4;
    Some(val)
}

fn read_woff2_base128(data: &[u8], offset: &mut usize) -> Option<u32> {
    let mut accum: u32 = 0;
    for _ in 0..5 {
        if *offset >= data.len() {
            return None;
        }
        let code = data[*offset];
        *offset += 1;
        if accum & 0xFE00_0000 != 0 {
            return None;
        }
        accum = (accum << 7) | ((code & 0x7F) as u32);
        if (code & 0x80) == 0 {
            return Some(accum);
        }
    }
    None
}

struct Woff2Table {
    tag: [u8; 4],
    orig_length: u32,
    transform_length: Option<u32>,
    flags: u8,
}

/// WOFF2 形式のフォントデータを受取り、TTF/OTF (sfnt) バイト列に展開する。
pub fn decompress_woff2(bytes: &[u8]) -> Option<Vec<u8>> {
    if bytes.len() < 48 || &bytes[0..4] != b"wOF2" {
        return None;
    }
    let mut offset = 4;
    let flavor = read_woff2_uint32(bytes, &mut offset)?;
    let _length = read_woff2_uint32(bytes, &mut offset)?;
    let num_tables = read_woff2_uint16(bytes, &mut offset)? as usize;
    let _reserved = read_woff2_uint16(bytes, &mut offset)?;
    let total_sfnt_size = read_woff2_uint32(bytes, &mut offset)? as usize;
    let total_compressed_size = read_woff2_uint32(bytes, &mut offset)? as usize;
    let _major_version = read_woff2_uint16(bytes, &mut offset)?;
    let _minor_version = read_woff2_uint16(bytes, &mut offset)?;
    let _meta_offset = read_woff2_uint32(bytes, &mut offset)?;
    let _meta_length = read_woff2_uint32(bytes, &mut offset)?;
    let _meta_orig_length = read_woff2_uint32(bytes, &mut offset)?;
    let _priv_offset = read_woff2_uint32(bytes, &mut offset)?;
    let _priv_length = read_woff2_uint32(bytes, &mut offset)?;

    let mut tables = Vec::with_capacity(num_tables);
    let mut total_uncompressed_stream_len: usize = 0;

    for _ in 0..num_tables {
        if offset >= bytes.len() {
            return None;
        }
        let flags = bytes[offset];
        offset += 1;
        let tag_idx = flags & 0x3F;

        let tag = if tag_idx == 63 {
            if offset + 4 > bytes.len() {
                return None;
            }
            let t = [bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]];
            offset += 4;
            t
        } else if (tag_idx as usize) < WOFF2_KNOWN_TAGS.len() {
            *WOFF2_KNOWN_TAGS[tag_idx as usize]
        } else {
            return None;
        };

        let orig_length = read_woff2_base128(bytes, &mut offset)?;
        let transform_version = (flags >> 6) & 0x03;

        // 【2026-08-05 発見・修正】変換の有無の判定が仕様と逆だった。
        //
        // WOFF2 仕様では **`glyf` と `loca` だけ意味が反転**する:
        //
        // | テーブル        | version 0 | version 3 |
        // |-----------------|-----------|-----------|
        // | `glyf` / `loca` | **変換あり** | 変換なし |
        // | その他          | 変換なし  | 変換あり  |
        //
        // 以前は「0 = 変換なし」と決め打ちしていたため、変換された `glyf` を
        // 「変換なし」と誤判定し、`transformLength` を読まずに元長で切り出していた。
        // **ストリーム上の位置がそこから全部ずれる**うえ、変換済みバイト列を
        // そのまま SFNT の `glyf` として書いていた。
        //
        // 結果、`head`/`cmap` は無事なのでフォントはパースに成功し
        // `glyph_index()` も引けるが、輪郭データが壊れているため
        // Font Awesome のアイコンが箱（☐）として描かれていた。
        let is_glyf_or_loca = &tag == b"glyf" || &tag == b"loca";
        let transformed = if is_glyf_or_loca {
            transform_version == 0
        } else {
            transform_version != 0
        };

        let transform_length = if transformed {
            let tl = read_woff2_base128(bytes, &mut offset)?;
            total_uncompressed_stream_len += tl as usize;
            Some(tl)
        } else {
            total_uncompressed_stream_len += orig_length as usize;
            None
        };

        tables.push(Woff2Table {
            tag,
            orig_length,
            transform_length,
            flags,
        });
    }

    if offset + total_compressed_size > bytes.len() {
        return None;
    }

    let compressed_data = &bytes[offset..offset + total_compressed_size];
    // 【2026-07-31診断】Font Awesome の woff2 展開で OOM した件。
    // 必要な展開後サイズを記録し、スクラッチバッファが足りているか確認する。
    crate::warn!(
        "[WOFF2] decompress compressed={} expected_uncompressed={}",
        compressed_data.len(),
        total_uncompressed_stream_len
    );
    let decompressed_stream = decompress_brotli(compressed_data, total_uncompressed_stream_len)?;

    // sfnt ファイルの再構築
    let mut sfnt = Vec::with_capacity(total_sfnt_size.max(12 + num_tables * 16));
    
    // sfnt Header (12 bytes)
    sfnt.extend_from_slice(&flavor.to_be_bytes());
    sfnt.extend_from_slice(&(num_tables as u16).to_be_bytes());

    let mut max_p2 = 1u16;
    while max_p2 * 2 <= (num_tables as u16) {
        max_p2 *= 2;
    }
    let search_range = max_p2 * 16;
    let entry_selector = (16 - max_p2.leading_zeros() - 1) as u16;
    let range_shift = (num_tables as u16) * 16 - search_range;

    sfnt.extend_from_slice(&search_range.to_be_bytes());
    sfnt.extend_from_slice(&entry_selector.to_be_bytes());
    sfnt.extend_from_slice(&range_shift.to_be_bytes());

    // sfnt Table Directory
    let table_dir_offset = 12;
    let data_start_offset = table_dir_offset + num_tables * 16;

    let mut sorted_indices: Vec<usize> = (0..num_tables).collect();
    sorted_indices.sort_by_key(|&idx| tables[idx].tag);

    // 空の Table Directory を確保
    sfnt.resize(data_start_offset, 0);

    // 【2026-08-03 発見・修正】展開ストリームを**タグ順**に読んでいた。
    //
    // WOFF2 仕様では、テーブルデータは**テーブルディレクトリに現れた順**で
    // 連結されている。タグ順に読むと各テーブルへ別のテーブルのバイト列が
    // 割り当たり、`head` が壊れる。
    // 実測: Brotli 展開は成功しているのに `VectorFont::new` が
    // **`NoHeadTable`** を返していた（Font Awesome 全ファイル）。
    //
    // 正しくは「ストリームの切り出しはディレクトリ順」「ディレクトリの
    // 出力はタグ順」と**分ける**。
    let mut stream_offset = 0usize;
    let mut table_ranges: Vec<(usize, usize)> = Vec::with_capacity(num_tables);
    for table in tables.iter().take(num_tables) {
        let len = table.orig_length as usize;
        let read_len = table.transform_length.map(|l| l as usize).unwrap_or(len);
        if stream_offset + read_len > decompressed_stream.len() {
            crate::warn!(
                "[FONT][WOFF2] 展開ストリームが短い tag={:?} 必要={} 残り={}",
                core::str::from_utf8(&table.tag).unwrap_or("????"),
                read_len,
                decompressed_stream.len().saturating_sub(stream_offset)
            );
            return None;
        }
        table_ranges.push((stream_offset, stream_offset + read_len));
        stream_offset += read_len;
    }

    // 【2026-08-05】変換された `glyf` を復元し、`loca` も作り直す。
    //
    // WOFF2 は `glyf`/`loca` を変換して格納する（仕様 §5.1）。
    // 復元しないと輪郭データが壊れたままで、フォントはパースに成功するのに
    // 字形が箱（☐）になる（実測: Font Awesome のアイコン全部）。
    //
    // 復元に失敗したら**フォント全体を諦める**（W-3）。
    // 壊れたテーブルを書くより、代替フォントで描く方がまし。
    let mut rebuilt: alloc::collections::BTreeMap<usize, Vec<u8>> =
        alloc::collections::BTreeMap::new();
    {
        let glyf_idx = tables.iter().take(num_tables).position(|t| {
            &t.tag == b"glyf" && t.transform_length.is_some()
        });
        if let Some(gi) = glyf_idx {
            let (rs, re) = table_ranges[gi];
            let raw = decompressed_stream.get(rs..re)?;
            match crate::kernel::woff2_glyf::reconstruct_glyf(raw) {
                Some((glyf_data, loca_data, _fmt)) => {
                    crate::warn!(
                        "[FONT][WOFF2] glyf 変換を復元 {} -> {} バイト（loca {} バイト）",
                        raw.len(),
                        glyf_data.len(),
                        loca_data.len()
                    );
                    rebuilt.insert(gi, glyf_data);
                    if let Some(li) = tables
                        .iter()
                        .take(num_tables)
                        .position(|t| &t.tag == b"loca")
                    {
                        rebuilt.insert(li, loca_data);
                    }
                }
                None => {
                    crate::warn!(
                        "[FONT][WOFF2] glyf 変換の復元に失敗（{} バイト）",
                        raw.len()
                    );
                    return None;
                }
            }
        }
    }

    let mut current_data_offset = data_start_offset;

    for &idx in &sorted_indices {
        let table = &tables[idx];
        let len = table.orig_length as usize;
        let (rs, re) = table_ranges[idx];
        // 復元済みテーブル（`glyf`/`loca`）があればそちらを使う。
        let table_raw: &[u8] = match rebuilt.get(&idx) {
            Some(v) => v.as_slice(),
            None => &decompressed_stream[rs..re],
        };
        let len = if rebuilt.contains_key(&idx) {
            table_raw.len()
        } else {
            len
        };

        // チェックサムの計算
        let mut sum: u32 = 0;
        let mut i = 0;
        while i < table_raw.len() {
            let b0 = table_raw[i] as u32;
            let b1 = table_raw.get(i + 1).copied().unwrap_or(0) as u32;
            let b2 = table_raw.get(i + 2).copied().unwrap_or(0) as u32;
            let b3 = table_raw.get(i + 3).copied().unwrap_or(0) as u32;
            sum = sum.wrapping_add((b0 << 24) | (b1 << 16) | (b2 << 8) | b3);
            i += 4;
        }

        let dir_entry_pos = table_dir_offset + sorted_indices.iter().position(|&x| x == idx)? * 16;
        sfnt[dir_entry_pos..dir_entry_pos + 4].copy_from_slice(&table.tag);
        sfnt[dir_entry_pos + 4..dir_entry_pos + 8].copy_from_slice(&sum.to_be_bytes());
        sfnt[dir_entry_pos + 8..dir_entry_pos + 12].copy_from_slice(&(current_data_offset as u32).to_be_bytes());
        sfnt[dir_entry_pos + 12..dir_entry_pos + 16].copy_from_slice(&(len as u32).to_be_bytes());

        sfnt.extend_from_slice(table_raw);
        let padding = (4 - (table_raw.len() % 4)) % 4;
        sfnt.extend(core::iter::repeat_n(0u8, padding));
        current_data_offset += table_raw.len() + padding;
    }

    Some(sfnt)
}

use spin::Mutex;
use ttf_parser::{Face, OutlineBuilder};

fn f32_floor(x: f32) -> i32 {
    if x >= 0.0 {
        x as i32
    } else {
        (x - 1.0) as i32
    }
}

fn f32_ceil(x: f32) -> i32 {
    if x >= 0.0 {
        (x + 1.0) as i32
    } else {
        x as i32
    }
}

#[derive(Debug, Clone, Copy, PartialEq)]
struct Point {
    x: f32,
    y: f32,
}

#[derive(Debug, Clone)]
enum Segment {
    Line(Point, Point),
}

/// グリフのアウトライン（直線線分リスト）を構築するビルダー
struct GlyphOutlineBuilder {
    segments: Vec<Segment>,
    current: Point,
    start: Point,
    scale: f32,
}

impl GlyphOutlineBuilder {
    fn new(scale: f32) -> Self {
        Self {
            segments: Vec::new(),
            current: Point { x: 0.0, y: 0.0 },
            start: Point { x: 0.0, y: 0.0 },
            scale,
        }
    }

    /// 2次ベジェ曲線を再帰/ステップ分割して直線セグメントにフラット化します
    fn flatten_quad(&mut self, p0: Point, p1: Point, p2: Point) {
        let steps = 6; // 計算量と品質のバランスが最適なステップ数
        let mut prev = p0;
        for i in 1..=steps {
            let t = (i as f32) / (steps as f32);
            let mt = 1.0 - t;
            // 2次ベジェ曲線の方程式
            let x = mt * mt * p0.x + 2.0 * mt * t * p1.x + t * t * p2.x;
            let y = mt * mt * p0.y + 2.0 * mt * t * p1.y + t * t * p2.y;
            let current = Point { x, y };
            self.segments.push(Segment::Line(prev, current));
            prev = current;
        }
    }
}

impl OutlineBuilder for GlyphOutlineBuilder {
    fn move_to(&mut self, x: f32, y: f32) {
        let p = Point {
            x: x * self.scale,
            y: y * self.scale,
        };
        self.current = p;
        self.start = p;
    }

    fn line_to(&mut self, x: f32, y: f32) {
        let p = Point {
            x: x * self.scale,
            y: y * self.scale,
        };
        self.segments.push(Segment::Line(self.current, p));
        self.current = p;
    }

    fn quad_to(&mut self, x1: f32, y1: f32, x: f32, y: f32) {
        let p1 = Point {
            x: x1 * self.scale,
            y: y1 * self.scale,
        };
        let p2 = Point {
            x: x * self.scale,
            y: y * self.scale,
        };
        self.flatten_quad(self.current, p1, p2);
        self.current = p2;
    }

    fn curve_to(&mut self, _x1: f32, _y1: f32, _x2: f32, _y2: f32, x: f32, y: f32) {
        // TrueTypeフォント（2次ベジェ）では基本的に呼ばれないが、
        // 3次ベジェが含まれる場合は線形補間で対応
        let p2 = Point {
            x: x * self.scale,
            y: y * self.scale,
        };
        self.segments.push(Segment::Line(self.current, p2));
        self.current = p2;
    }

    fn close(&mut self) {
        if self.current != self.start {
            self.segments.push(Segment::Line(self.current, self.start));
        }
    }
}

/// ヒープメモリにキャッシュされるラスタライズ済みグリフデータ
#[derive(Clone)]
pub struct CachedGlyph {
    pub width: u32,
    pub height: u32,
    pub x_offset: i32,
    pub y_offset: i32,
    pub advance: u32,
    pub data: Vec<u8>, // A8 フォーマットのアルファマスク (0-255)
}

/// アルファブレンド済みのカラーグリフデータ
#[derive(Clone)]
pub struct CachedColorGlyph {
    pub width: u32,
    pub height: u32,
    pub x_offset: i32,
    pub y_offset: i32,
    pub advance: u32,
    pub data: Vec<u32>, // ARGB8888 形式のブレンド済みピクセルカラー (透明部分は0)
}

/// 動的フォントキャッシュとフォントロードを管理するマネージャ
pub struct VectorFont {
    face: Face<'static>,
    /// フォールバックフォント（プライマリにグリフが無い文字をこの順で補う）。
    fallbacks: Vec<Face<'static>>,
    cache: BTreeMap<(char, u32), CachedGlyph>, // (文字, フォントサイズ) -> キャッシュグリフ
    color_cache: BTreeMap<(char, u32, u32, u32), CachedColorGlyph>, // (文字, サイズ, 文字色, 背景色) -> キャッシュカラーグリフ
    advance_cache: BTreeMap<(char, u32), u32>,                      // (文字, サイズ) -> advance幅
}

/// フォントに存在しない記号類を、視覚的に近い代替文字へマッピングする。
/// （M PLUS 2 などに含まれない矢印・約物・記号の文字化け/欠落を防ぐ）
fn fallback_glyph_char(c: char) -> Option<char> {
    let sub = match c {
        // 不可視文字可視化記号のフォールバック
        '␣' => '_', // 半角空白 (Open Box) はアンダーバー
        '⇥' => '>', // タブは不等号
        '↵' => '<', // CRLFは不等号
        '⇠' => '<', // CRは不等号
        // ダッシュ・ハイフン類
        '–' | '—' | '―' | '‐' | '‑' | '−' => '-',
        // 引用符
        '\u{2018}' | '\u{2019}' | '‚' | '‛' | '`' => '\'',
        '\u{201C}' | '\u{201D}' | '„' | '‟' => '"',
        // 中点・箇条書き
        '•' | '◦' | '‣' | '·' | '∙' => '*',
        // 乗算・除算
        '×' => 'x',
        '÷' => '/',
        // 省略記号（簡易的に1点へ）
        '…' => '.',
        // 全角スペースは呼び出し側で除外済みだが念のため通常空白へ
        '\u{00A0}' | '\u{202F}' | '\u{2009}' | '\u{200A}' => ' ',
        // FontAwesome（Private Use Area）アイコンのうち、明確で恣意的でない
        // テキスト等価物を持つものだけの限定的なフォールバック。
        //
        // 【2026-08-05 修正】絵文字への代替（📄 🛡 🎓 💻 ⚙ 🏠 …）を **50 件撤去**した。
        //
        // 内蔵の日本語フォントはこれらの字形を持たないが **cmap には登録されていて
        // 豆腐（□）が返る**。その結果、アイコン位置に ☐ が並んでいた
        // （実測: `#apps` の一覧、実サイトには無い）。
        //
        // アイコンが出せないなら**何も描かない**方が実ブラウザの挙動に近い。
        // 残すのは内蔵フォントが確実に持つ範囲（U+2600 未満の記号）だけ:
        // 矢印・山形・チェック・引用符など。
        //
        // なお `@font-face` / WOFF2 の読込は**実装済み**になった
        // （下記コメントは当時のもの）。Font Awesome は CFF ベースで、
        // 取得・展開・登録まで通っている。
        // アイコンフォントのグリフは常に欠落するが、矢印・情報記号のように
        // 一般的なUnicode記号で意味が一意に近似できるものに限り代替する
        // （それ以外の大半のアイコン、例えば microchip/leaf/home 等は恣意的な
        // 代替になり「アイコンが無い」より「別の意味の文字が出る」方が誤解を
        // 招くため、あえてマッピングせず既存の安全な欠落挙動のままにする）。
        // コードポイントは実サイト www.sugi-lab.net（Font Awesome 7.0.0）の
        // 実際のDOMから`getComputedStyle(el, '::before').content`で直接
        // 検証済み（2026-07-21、記憶からの推測ではない）。
        '\u{f060}' => '\u{2190}', // fa-arrow-left → ←
        '\u{f061}' => '\u{2192}', // fa-arrow-right → →
        '\u{f062}' => '\u{2191}', // fa-arrow-up → ↑
        '\u{f063}' => '\u{2193}', // fa-arrow-down → ↓
        '\u{f053}' => '\u{2039}', // fa-chevron-left → ‹
        '\u{f054}' => '\u{203A}', // fa-chevron-right → ›
        '\u{f077}' => '^',        // fa-chevron-up → ^
        '\u{f078}' => 'v',        // fa-chevron-down → v（下向き山形に近似）
        '\u{f104}' => '\u{2039}', // fa-angle-left → ‹
        '\u{f105}' => '\u{203A}', // fa-angle-right → ›
        '\u{f106}' => '^',        // fa-angle-up → ^
        '\u{f107}' => 'v',        // fa-angle-down → v
        '\u{f00c}' => '\u{2713}', // fa-check → ✓
        '\u{f00d}' => '\u{2715}', // fa-times / fa-xmark → ✕
        '\u{f05a}' => 'i',        // fa-info-circle → i（情報記号として一般的）
        // 2026-07-24: 実サイト www.sugi-lab.net の全ページ（index/profile/
        // smarthome/timeseries/forms/papers/access）を横断的に走査し、これまで
        // 未マッピングだった FontAwesome アイコンクラスのコードポイントを
        // `getComputedStyle(el, '::before').content`で実測・追加。ブランド
        // アイコン（facebook/github/google/notion等）や、意味が一意に近似
        // できないもの（filter/mouse-pointer/journal-whills等）は既存方針
        // どおり対象外のまま。
        '\u{f35d}' => '↗',        // fa-external-link-alt
        '\u{f10d}' => '"',        // fa-quote-left
        '\u{f10e}' => '"',        // fa-quote-right
        _ => return None,
    };
    Some(sub)
}

impl VectorFont {
    pub fn new(font_bytes: &'static [u8]) -> Result<Self, ttf_parser::FaceParsingError> {
        let face = Face::parse(font_bytes, 0)?;
        Ok(Self {
            face,
            fallbacks: Vec::new(),
            cache: BTreeMap::new(),
            color_cache: BTreeMap::new(),
            advance_cache: BTreeMap::new(),
        })
    }

    /// プライマリ + フォールバック群でフォントを構築する。
    /// `fallback_bytes` の各フォントは、プライマリにグリフが無い文字を順に補う。
    /// パース失敗したフォールバックは無視する（プライマリが失敗したらエラー）。
    pub fn new_with_fallbacks(
        font_bytes: &'static [u8],
        fallback_bytes: &[&'static [u8]],
    ) -> Result<Self, ttf_parser::FaceParsingError> {
        let face = Face::parse(font_bytes, 0)?;
        let mut fallbacks = Vec::new();
        for fb in fallback_bytes {
            if let Ok(f) = Face::parse(fb, 0) {
                fallbacks.push(f);
            }
        }
        Ok(Self {
            face,
            fallbacks,
            cache: BTreeMap::new(),
            color_cache: BTreeMap::new(),
            advance_cache: BTreeMap::new(),
        })
    }

    /// 新しいプライマリフォントへ切り替える。旧プライマリはフォールバック
    /// チェーンの先頭へ退避するため、既存のグリフカバレッジは失われない
    /// （`@font-face`で実行時に取得したフォントを、ページ全体で使う
    /// 主要フォントとして採用する用途。2026-07-22新設）。キャッシュ済み
    /// グリフは全てプライマリ変更前のフォントに基づくため破棄する。
    pub fn set_primary(&mut self, font_bytes: &'static [u8]) -> Result<(), ttf_parser::FaceParsingError> {
        let new_face = Face::parse(font_bytes, 0)?;
        let old_primary = core::mem::replace(&mut self.face, new_face);
        self.fallbacks.insert(0, old_primary);
        self.cache.clear();
        self.color_cache.clear();
        self.advance_cache.clear();
        Ok(())
    }

    /// 指定されたサイズでグリフをラスタライズ（またはキャッシュから取得）します
    /// 【2026-08-05診断】この符号位置の字形を持っているか。
    /// プライマリと代替の両方を見る（`get_glyph` と同じ探索）。
    /// 【2026-08-05】**プライマリだけ**が字形を持つか。
    ///
    /// Google Fonts は unicode-range でファイルを分割して配信するため、
    /// 「ウェイト 700 の Noto Sans JP」が Latin だけのサブセットということがある。
    /// ウェイト指定で選んだフォントがその文字を持たないと、
    /// 見出しの漢字が欠ける（実測: 「開発アプリケーション」→「□ 発プリケーション」）。
    /// 選ぶ前にこれで確かめる。
    pub fn primary_has_glyph(&self, c: char) -> bool {
        self.face.glyph_index(c).is_some()
    }

    pub fn has_glyph(&self, c: char) -> bool {
        // 【2026-08-05】私用領域は**プライマリだけ**を見る。
        // 代替フォント（内蔵和文）は私用領域に豆腐の字形を持つため、
        // 含めると「字形がある」と誤って報告してしまう
        // （実際 `Noto Sans JP` でも `字形F02D=true` になっていた）。
        if ('\u{e000}'..='\u{f8ff}').contains(&c) {
            return self.face.glyph_index(c).is_some();
        }
        if self.face.glyph_index(c).is_some() {
            return true;
        }
        self.fallbacks.iter().any(|f| f.glyph_index(c).is_some())
    }

    pub fn get_glyph(&mut self, c: char, size_px: u32) -> Option<&CachedGlyph> {
        let key = (c, size_px);
        if self.cache.contains_key(&key) {
            return self.cache.get(&key);
        }

        if self.cache.len() >= 8000 {
            crate::info!(
                "[vector_font] Cache limit (8000) reached. Clearing glyph cache to free memory."
            );
            self.cache.clear();
        }

        // キャッシュミス：グリフを持つ face を プライマリ→フォールバック の順で選ぶ。
        // face_idx 0 = プライマリ、1.. = fallbacks[idx-1]。
        let (face_idx, glyph_id) = {
            let find = |ch: char| -> Option<(usize, ttf_parser::GlyphId)> {
                if let Some(id) = self.face.glyph_index(ch) {
                    return Some((0, id));
                }
                // 【2026-08-05 発見・修正】私用領域（U+E000..U+F8FF）は
                // アイコンフォント専用の領域。ここを内蔵フォントへ
                // フォールバックさせてはいけない。
                //
                // 2026-08-04 に「字形が無い文字が消える」対策として
                // 内蔵フォントチェーンを代替に加えたが、内蔵フォントは
                // 私用領域に**箱（tofu）の字形を持っている**。その結果
                // Font Awesome のアイコンが ☐ として描かれていた
                // （実測: `字形F02D=true` が Noto Sans JP でも真だった）。
                //
                // アイコンが無いときは**何も描かない**のが正しい
                // （実ブラウザもアイコンフォント未取得時は空白になる）。
                if ('\u{e000}'..='\u{f8ff}').contains(&ch) {
                    return None;
                }
                for (i, f) in self.fallbacks.iter().enumerate() {
                    if let Some(id) = f.glyph_index(ch) {
                        return Some((i + 1, id));
                    }
                }
                None
            };
            match find(c) {
                Some(x) => x,
                None => {
                    // どのフォントにも無い文字は、視覚的に近い代替文字で再探索する
                    fallback_glyph_char(c).and_then(find)?
                }
            }
        };
        let face: &Face = if face_idx == 0 {
            &self.face
        } else {
            &self.fallbacks[face_idx - 1]
        };

        let units_per_em = face.units_per_em() as f32;
        let scale = (size_px as f32) / units_per_em;

        // メトリクスの取得
        let advance = (face.glyph_hor_advance(glyph_id)? as f32 * scale) as u32;

        // アウトラインを先に抽出する。スペース等の輪郭なし文字は glyph_bounding_box が None を
        // 返すため、? で early return してしまい advance が捨てられるのを防ぐ。
        let mut builder = GlyphOutlineBuilder::new(scale);
        face.outline_glyph(glyph_id, &mut builder);

        // 輪郭が存在しない文字（空白など）: advance だけ持つ空グリフとしてキャッシュする。
        // これを bounding_box の取得より前に行うことで、スペースの advance が正しく適用される。
        if builder.segments.is_empty() {
            let empty_glyph = CachedGlyph {
                width: 0,
                height: 0,
                x_offset: 0,
                y_offset: 0,
                advance,
                data: Vec::new(),
            };
            self.cache.insert(key, empty_glyph);
            return self.cache.get(&key);
        }

        // 輪郭がある文字は必ず bounding_box が存在する。
        let bounding_box = face.glyph_bounding_box(glyph_id)?;

        // ttf-parserのY軸は上方向が正、画面座標は下方向が正であるため、スケーリングとY軸反転を行います
        let scale_y = -scale;

        // Y軸方向の座標変換（反転）をセグメントに適用
        let mut segments = builder.segments;
        for seg in &mut segments {
            match seg {
                Segment::Line(p1, p2) => {
                    p1.y = -p1.y;
                    p2.y = -p2.y;
                }
            }
        }

        // Bounding Box のスケーリングと画面座標への変換
        let bx0 = bounding_box.x_min as f32 * scale;
        let by0 = bounding_box.y_max as f32 * scale_y; // Y軸反転
        let bx1 = bounding_box.x_max as f32 * scale;
        let by1 = bounding_box.y_min as f32 * scale_y; // Y軸反転

        let gx0 = f32_floor(bx0) - 1;
        let gy0 = f32_floor(by0) - 1;
        let gx1 = f32_ceil(bx1) + 1;
        let gy1 = f32_ceil(by1) + 1;

        let width = (gx1 - gx0).max(1) as u32;
        let height = (gy1 - gy0).max(1) as u32;
        let x_offset = gx0;
        let y_offset = gy0;

        if width > 500 || height > 500 || width == 0 || height == 0 {
            crate::warn!(
                "[NET][DIAG] glyph c={:?} units_per_em={} scale={} bbox=({},{},{},{}) w={} h={} face_idx={}",
                c,
                units_per_em,
                scale,
                bounding_box.x_min,
                bounding_box.y_min,
                bounding_box.x_max,
                bounding_box.y_max,
                width,
                height,
                face_idx
            );
        }

        // 4x4 スーパーサンプリング Even-Odd ラスタライザ（スキャンライン方式）。
        // セグメント走査を「ピクセルごと」ではなく「サブスキャンライン(sub_y)ごと」に一度だけ行い、
        // 交点 x をスパンに変換して各ピクセルのカバレッジを O(交点数) で求める。
        // これにより従来の 幅×高さ×16×全セグメント数 から、係数 幅 と 全セグメント数 を大幅に削減する。
        let mut data = alloc::vec![0u8; (width * height) as usize];
        let mut coverage = alloc::vec![0u8; width as usize];
        let mut xs: alloc::vec::Vec<f32> = alloc::vec::Vec::new();

        for py in 0..height {
            let screen_y = (gy0 + py as i32) as f32;
            for c in coverage.iter_mut() {
                *c = 0;
            }

            // 4 本のサブスキャンライン
            for sy in 0..4 {
                let sub_y = screen_y + (sy as f32 + 0.5) / 4.0;

                // このスキャンラインと交わる全セグメントの交点 x を一度だけ収集（ピクセル非依存）
                xs.clear();
                for seg in &segments {
                    match seg {
                        Segment::Line(p1, p2) => {
                            let y_min = p1.y.min(p2.y);
                            let y_max = p1.y.max(p2.y);
                            if sub_y >= y_min && sub_y < y_max && p1.y != p2.y {
                                let t = (sub_y - p1.y) / (p2.y - p1.y);
                                xs.push(p1.x + t * (p2.x - p1.x));
                            }
                        }
                    }
                }
                if xs.is_empty() {
                    continue;
                }
                // 昇順ソート → even-odd で内部スパンは [xs[0],xs[1]), [xs[2],xs[3]), ...
                xs.sort_by(|a, b| a.partial_cmp(b).unwrap_or(core::cmp::Ordering::Equal));

                // 各スパンが覆うサブピクセル列にカバレッジを加算する。
                // 元実装の判定「交点x > sub_x の個数が奇数なら内側」と等価。
                let mut i = 0;
                while i + 1 < xs.len() {
                    let span_start = xs[i];
                    let span_end = xs[i + 1];
                    i += 2;
                    if span_end <= span_start {
                        continue;
                    }
                    // span_start <= sub_x < span_end を満たすサブピクセル (px, sx) を加算
                    // sub_x = (gx0 + px) + (sx + 0.5)/4
                    // px 範囲を概算してクランプ
                    let px_lo = (f32_floor(span_start) - gx0 - 1).max(0) as u32;
                    let px_hi = ((f32_ceil(span_end) - gx0 + 1).max(0) as u32).min(width);
                    for px in px_lo..px_hi {
                        let screen_x = (gx0 + px as i32) as f32;
                        for sx in 0..4 {
                            let sub_x = screen_x + (sx as f32 + 0.5) / 4.0;
                            if sub_x >= span_start && sub_x < span_end {
                                coverage[px as usize] += 1;
                            }
                        }
                    }
                }
            }

            for px in 0..width {
                let alpha = ((coverage[px as usize] as u32 * 255) / 16).min(255) as u8;
                data[(py * width + px) as usize] = alpha;
            }
        }

        let cached = CachedGlyph {
            width,
            height,
            x_offset,
            y_offset,
            advance,
            data,
        };

        self.cache.insert(key, cached);
        self.cache.get(&key)
    }

    /// 指定されたサイズ、文字色、背景色でアルファブレンド済みのカラーグリフを取得（またはキャッシュから取得）します
    pub fn get_color_glyph(
        &mut self,
        c: char,
        size_px: u32,
        fg_color: u32,
        bg_color: u32,
    ) -> Option<&CachedColorGlyph> {
        let key = (c, size_px, fg_color, bg_color);
        if self.color_cache.contains_key(&key) {
            return self.color_cache.get(&key);
        }

        if self.color_cache.len() >= 16000 {
            self.color_cache.clear();
        }

        let glyph = self.get_glyph(c, size_px)?.clone();

        let mut color_data = Vec::with_capacity(glyph.data.len());
        let fg_r = (fg_color >> 16) & 0xFF;
        let fg_g = (fg_color >> 8) & 0xFF;
        let fg_b = fg_color & 0xFF;
        let bg_r = (bg_color >> 16) & 0xFF;
        let bg_g = (bg_color >> 8) & 0xFF;
        let bg_b = bg_color & 0xFF;

        for &alpha in &glyph.data {
            if alpha == 0 {
                color_data.push(0x00000000); // 完全透明マーク
            } else if alpha == 255 {
                color_data.push(fg_color | 0xFF000000); // 完全不透明
            } else {
                let a = alpha as u32;
                let inv_a = 255 - a;
                let r = ((fg_r * a + bg_r * inv_a) / 255) & 0xFF;
                let g = ((fg_g * a + bg_g * inv_a) / 255) & 0xFF;
                let b = ((fg_b * a + bg_b * inv_a) / 255) & 0xFF;
                color_data.push(0xFF000000 | (r << 16) | (g << 8) | b);
            }
        }

        let cached = CachedColorGlyph {
            width: glyph.width,
            height: glyph.height,
            x_offset: glyph.x_offset,
            y_offset: glyph.y_offset,
            advance: glyph.advance,
            data: color_data,
        };

        self.color_cache.insert(key, cached);
        self.color_cache.get(&key)
    }

    /// 指定されたサイズでグリフのアドバンス（幅）のみを高速に取得（またはキャッシュから取得）します。
    /// レイアウトの折り返し計算等で重いラスタライズ（Even-Odd法）を回避するために使用します。
    pub fn get_glyph_advance(&mut self, c: char, size_px: u32) -> u32 {
        let key = (c, size_px);
        if let Some(glyph) = self.cache.get(&key) {
            return glyph.advance;
        }
        if let Some(&adv) = self.advance_cache.get(&key) {
            return adv;
        }

        let (face_idx, glyph_id) = {
            let find = |ch: char| -> Option<(usize, ttf_parser::GlyphId)> {
                if let Some(id) = self.face.glyph_index(ch) {
                    return Some((0, id));
                }
                // 【2026-08-05 発見・修正】私用領域（U+E000..U+F8FF）は
                // アイコンフォント専用の領域。ここを内蔵フォントへ
                // フォールバックさせてはいけない。
                //
                // 2026-08-04 に「字形が無い文字が消える」対策として
                // 内蔵フォントチェーンを代替に加えたが、内蔵フォントは
                // 私用領域に**箱（tofu）の字形を持っている**。その結果
                // Font Awesome のアイコンが ☐ として描かれていた
                // （実測: `字形F02D=true` が Noto Sans JP でも真だった）。
                //
                // アイコンが無いときは**何も描かない**のが正しい
                // （実ブラウザもアイコンフォント未取得時は空白になる）。
                if ('\u{e000}'..='\u{f8ff}').contains(&ch) {
                    return None;
                }
                for (i, f) in self.fallbacks.iter().enumerate() {
                    if let Some(id) = f.glyph_index(ch) {
                        return Some((i + 1, id));
                    }
                }
                None
            };
            match find(c) {
                Some(x) => x,
                None => {
                    if let Some(alt) = fallback_glyph_char(c).and_then(find) {
                        alt
                    } else {
                        let default_adv = size_px / 2;
                        self.advance_cache.insert(key, default_adv);
                        return default_adv;
                    }
                }
            }
        };

        let face: &Face = if face_idx == 0 {
            &self.face
        } else {
            &self.fallbacks[face_idx - 1]
        };
        let units_per_em = face.units_per_em() as f32;
        let scale = (size_px as f32) / units_per_em;
        let advance = if let Some(adv) = face.glyph_hor_advance(glyph_id) {
            (adv as f32 * scale) as u32
        } else {
            size_px / 2
        };

        if self.advance_cache.len() >= 10000 {
            self.advance_cache.clear();
        }
        self.advance_cache.insert(key, advance);
        advance
    }

    /// 指定したサイズでの文字列全体のピクセル幅（advance合計）を計算します
    pub fn get_string_width(&mut self, s: &str, size_px: u32) -> u32 {
        self.get_string_width_ls(s, size_px, 0)
    }

    /// letter-spacing 対応版。各文字の advance に ls(px, 負も可) を加算する。
    pub fn get_string_width_ls(&mut self, s: &str, size_px: u32, ls: i32) -> u32 {
        self.get_string_width_ls_ws(s, size_px, ls, 0)
    }

    /// letter-spacing + word-spacing 対応版。半角スペース1文字ごとに ws(px, 負も可) も加算する。
    pub fn get_string_width_ls_ws(&mut self, s: &str, size_px: u32, ls: i32, ws: i32) -> u32 {
        let mut width = 0i32;
        for c in s.chars() {
            width += self.get_glyph_advance(c, size_px) as i32 + ls + if c == ' ' { ws } else { 0 };
        }
        width.max(0) as u32
    }

    /// 折返し後の (最大行幅, 全体高さ) を返す。
    ///
    /// 重要: この行分割規則は web_engine.rs flatten_layout のテキスト折返し
    /// (`'\n'` は強制改行・行頭/行末禁則・改行時に先頭文字を即消費) と
    /// **完全に同一** でなければならない。ここがズレると layout が計算する
    /// 段落高さと flatten が生成する行数が食い違い、後続要素 (<hr> 等) が
    /// テキストに重なる。どちらかを変更する際は必ず両方を同期すること。
    pub fn get_string_wrapped_size(&mut self, s: &str, size_px: u32, max_width: u32) -> (u32, u32) {
        self.get_string_wrapped_size_ls_ws(s, size_px, max_width, 0, 0)
    }

    /// letter-spacing 対応版。各文字 advance に ls を加算して折返し計算する。
    pub fn get_string_wrapped_size_ls(
        &mut self,
        s: &str,
        size_px: u32,
        max_width: u32,
        ls: i32,
    ) -> (u32, u32) {
        self.get_string_wrapped_size_ls_ws(s, size_px, max_width, ls, 0)
    }

    pub fn get_string_wrapped_size_ls_ws(
        &mut self,
        s: &str,
        size_px: u32,
        max_width: u32,
        ls: i32,
        ws: i32,
    ) -> (u32, u32) {
        self.get_string_wrapped_size_ext(s, size_px, max_width, ls, ws, false, false)
    }

    /// word-break / white-space 対応版
    pub fn get_string_wrapped_size_ext(
        &mut self,
        s: &str,
        size_px: u32,
        max_width: u32,
        ls: i32,
        ws: i32,
        word_break_all: bool,
        _white_space_pre_wrap: bool,
    ) -> (u32, u32) {
        // 【2026-09-26】折り返し位置は描画側と共通の純粋関数 `line_break::break_positions`
        // で決める（単語ごと次の行へ送る・禁則・行末空白のぶら下げ）。従来はここと描画側に
        // 「単語を送らずはみ出させる」同趣旨の実装が 2 つあった。
        // `\n` は（pre-wrap に限らず、flatten が送ってくる場合も）強制改行として数える。
        let line_height = size_px + 4;
        let chars: alloc::vec::Vec<char> = s.chars().collect();
        let advances: alloc::vec::Vec<i32> = chars
            .iter()
            .map(|&c| {
                if c == '\n' {
                    0
                } else {
                    let extra = ls + if c == ' ' { ws } else { 0 };
                    (self.get_glyph_advance(c, size_px) as i32 + extra).max(0)
                }
            })
            .collect();
        let breaks = crate::os_lib::layout::line_break::break_positions(
            &chars,
            &advances,
            max_width.min(i32::MAX as u32) as i32,
            word_break_all,
            |c| !word_break_all && is_line_start_forbidden(c),
            |c| !word_break_all && is_line_end_forbidden(c),
        );
        let mut max_w = 0u32;
        let mut emitted_lines = 0u32;
        let mut line_w = 0i32;
        // 行末の空白（ぶら下げ）を除いた幅。
        let mut line_w_no_trailing = 0i32;
        let mut seg_has_content = false;
        let mut bi = 0usize;
        for (i, &c) in chars.iter().enumerate() {
            if c == '\n' {
                max_w = max_w.max(line_w_no_trailing.max(0) as u32);
                emitted_lines += 1;
                line_w = 0;
                line_w_no_trailing = 0;
                seg_has_content = false;
                continue;
            }
            if bi < breaks.len() && breaks[bi] == i {
                bi += 1;
                max_w = max_w.max(line_w_no_trailing.max(0) as u32);
                emitted_lines += 1;
                line_w = 0;
                line_w_no_trailing = 0;
            }
            line_w += advances[i];
            if !c.is_whitespace() {
                line_w_no_trailing = line_w;
            }
            seg_has_content = true;
        }
        max_w = max_w.max(line_w_no_trailing.max(0) as u32);
        if seg_has_content {
            emitted_lines += 1;
        }
        (max_w, emitted_lines.max(1) * line_height)
    }
}

// 静的グローバルフォントマネージャ
pub static GLOBAL_VECTOR_FONT: Mutex<Option<VectorFont>> = Mutex::new(None);
pub static GLOBAL_TERMINAL_FONT: Mutex<Option<VectorFont>> = Mutex::new(None);

// ============ 実行時カスタムフォント登録（`@font-face`用） ============
//
// 従来はフォントが`include_bytes!`によるコンパイル時埋め込みのみに限られており
// （上記コメント参照）、`@font-face`でページが指定するWebフォントを実行時に
// 読み込む手段が丸ごと存在しなかった。TTF/OTF形式（WOFF2は非対応。`glyf`/`loca`
// テーブル変換を伴うため別途デコーダが必要で本対応の範囲外）に限定した実行時
// フォント登録レジストリを新設する（2026-07-21、www.sugi-lab.net互換性調査より。
// 実測ではGoogle FontsはAtmOSのUser-Agent文字列に対しTTF形式で応答するため
// （WOFF2形式でのみ配信されるFontAwesomeとは異なる）、この経路だけでも本文用
// Webフォントの読込が可能になる）。
//
// `VectorFont::new`は`&'static [u8]`を要求するが、実行時に取得したバイト列は
// 本来 'static ではない。ここでは`Box::leak`で意図的にリークして 'static
// 参照へ変換する（この処理系にはページ遷移でフォントを解放する仕組みが元々無く、
// 埋め込みフォントも実質的にプロセス終了まで生き続ける想定と同じ性質のため、
// 新規リークを許容する）。
pub static CUSTOM_FONTS: Mutex<BTreeMap<String, VectorFont>> = Mutex::new(BTreeMap::new());

/// バイト列の先頭シグネチャからTTF/OTFかどうかを判定する（WOFF2等は`false`）。
fn looks_like_ttf_or_otf(bytes: &[u8]) -> bool {
    if bytes.len() < 4 {
        return false;
    }
    matches!(
        &bytes[0..4],
        [0x00, 0x01, 0x00, 0x00] | [b'O', b'T', b'T', b'O'] | [b't', b'r', b'u', b'e']
    )
}

/// `@font-face`で参照されたフォントを実行時に登録する。TTF/OTF以外（WOFF2等）は
/// 安全に`false`を返して拒否する（`ttf_parser`側でも不正な形式は`Err`で弾かれ
/// クラッシュしないが、シグネチャの時点で早期に判定した方が無駄なパースを避けられる）。
/// 同じ`family`名で複数回呼ばれた場合は後勝ちで上書きする。
///
/// **`GLOBAL_VECTOR_FONT`のプライマリを新フォントへ切り替える**（`set_primary`。
/// 旧プライマリはフォールバックへ退避するため既存のグリフカバレッジは失わない）。
/// この処理系はまだ要素/ノード単位の`font-family`対応フォント選択
/// （`kernel/draw.rs`の描画箇所・幅計測箇所すべてに手を入れる大規模な
/// レンダラ統合が必要）を実装しておらず、それを安全に完成させるにはページ全体の
/// テキスト描画・幅計測の整合性（描画に使うフォントと幅計測に使うフォントが
/// 常に一致していないと文字が重なる既知の脆さがある）を壊さないよう慎重な
/// 段階的実装が必要と判断し見送っている。代わりに「取得できたWebフォントを
/// ページ全体の主要フォントとして採用する」という単純だが安全な戦略を採る
/// （`draw.rs`/`render.rs`側の変更が一切不要で、既存のグローバルフォント経由
/// の描画・幅計測パイプラインをそのまま使い回せるため、描画と幅計測の
/// 不整合が原理的に発生しない）。将来的に複数の`@font-face`ファミリーを
/// 要素ごとに使い分ける必要が生じた場合は、別途`font-family`対応の
/// レンダラ統合に着手すること。2026-07-22実装。
/// バイト列の先頭シグネチャからWOFF2かどうかを判定する。
fn looks_like_woff2(bytes: &[u8]) -> bool {
    bytes.len() >= 4 && &bytes[0..4] == b"wOF2"
}

/// `@font-face`で参照されたフォントを実行時に登録する。
/// TTF/OTF に加え、WOFF2 (Brotli圧縮) フォントの自動展開・登録に対応。
/// 同じ`family`名で複数回呼ばれた場合は後勝ちで上書きする。
///
/// **`GLOBAL_VECTOR_FONT`のプライマリを新フォントへ切り替える**（`set_primary`。
/// 旧プライマリはフォールバックへ退避するため既存のグリフカバレッジは失わない）。
/// `family` と `weight` から `CUSTOM_FONTS` のキーを作る。
///
/// 【2026-08-05】以前は family 名だけをキーにしていたため、
/// 同じ family でウェイト違いを定義する CSS（Font Awesome など）で
/// **後勝ちで上書き**され、solid の字形が失われていた。
pub fn font_key(family: &str, weight: u16) -> alloc::string::String {
    alloc::format!("{}|{}", family.trim().to_lowercase(), weight)
}

/// ウェイトを指定して登録する。
pub fn register_custom_font_weighted(family: &str, weight: u16, bytes: Vec<u8>) -> bool {
    register_custom_font_inner(family, weight, bytes)
}

pub fn register_custom_font(family: &str, bytes: Vec<u8>) -> bool {
    register_custom_font_inner(family, 400, bytes)
}

fn register_custom_font_inner(family: &str, weight: u16, bytes: Vec<u8>) -> bool {
    // **安全性ゲート解除（2026-07-24）**: 2026-07-22に発見された「`decompress_brotli`が
    // 特定の入力でQEMU起動をハングさせる」問題の根本原因は、2026-07-23に別途
    // 特定・修正済みである：`decompress_brotli`内部の3つのプールバッファ（合計
    // 約160KB）がスタック上の固定配列として確保されており、64KBしかない起動時
    // コアスタックを溢れさせていた（スタックオーバーフロー）。この関数自体を
    // ヒープ確保（`Vec`）へ移行したことで根本解決済み（詳細は`decompress_brotli`
    // 冒頭のコメント参照）。あわせて`main.rs`にソフトウェアスタック番兵による
    // 検知機構も追加済みのため、万一同種の問題が再発してもハングではなく明確な
    // 検知・報告に変わる。以上を踏まえ、WOFF2の自動展開を再度有効化する。
    // 【2026-08-03】この関数は失敗を**4 箇所すべて無言**で返していた
    // （WOFF2 展開失敗・未知の形式・パース失敗・`set_primary` の失敗）。
    // そのため「フォントを取得できているのに適用されない」ときに
    // どこで落ちたのか分からなかった。規約は `spec/logging_policy.md`（L-1/L-2）。
    // 【2026-08-03】キャッシュ命中後、成功も失敗も一切ログに出ないまま
    // 停止する事象を追う。300/420/540 秒すべて同じ地点で止まったので
    // 時間不足ではない。入口・各段の通過を記録する。
    crate::warn!(
        "[FONT] 登録開始 family={} bytes={}",
        family,
        bytes.len()
    );
    // 内蔵フォントチェーン（字形が無い文字の代替）。
    // ローカル変数 `font_bytes` が関数 `font_bytes()` を隠すため、
    // シャドウイングされる前にここで用意しておく。
    let fallback_chain: Vec<&'static [u8]> = DEFAULT_FONT_CHAIN
        .iter()
        .filter_map(|n| font_bytes(n))
        .collect();
    let font_bytes = if looks_like_woff2(&bytes) {
        match decompress_woff2(&bytes) {
            Some(sfnt) => sfnt,
            None => {
                crate::warn!(
                    "[FONT] WOFF2 の展開に失敗 family={} bytes={}",
                    family,
                    bytes.len()
                );
                return false;
            }
        }
    } else if looks_like_ttf_or_otf(&bytes) {
        bytes
    } else {
        crate::warn!(
            "[FONT] 未知のフォント形式 family={} bytes={} head={:02x?}",
            family,
            bytes.len(),
            &bytes[..bytes.len().min(4)]
        );
        return false;
    };

    let leaked: &'static [u8] = Vec::leak(font_bytes);
    let _pf = crate::os_lib::web_engine::perf::start();
    crate::warn!("[FONT] 解析開始 family={} bytes={}", family, leaked.len());
    // 【2026-08-04 発見・修正】`VectorFont::new` は `fallbacks` が空。
    //
    // `@font-face` で登録したフォントで文字を描くようにした結果、
    // **そのフォントに字形が無い文字が何も描かれなくなった**
    // （Font Awesome に日本語の字形は無い）。
    // 実ブラウザは字形が無ければ次のフォントへ落とす。
    //
    // 内蔵フォントチェーンを代替として与える（`fallback_chain` は関数冒頭で用意）。
    // これで「Web フォントで描けるものはそれで、無いものは内蔵で」になる。
    let _parsed = VectorFont::new_with_fallbacks(leaked, &fallback_chain);
    crate::os_lib::web_engine::perf::add(
        crate::os_lib::web_engine::perf::Slot::FontParse,
        _pf,
    );
    match _parsed {
        Ok(font) => {
            {
                let mut map = CUSTOM_FONTS.lock();
                // ウェイト付きキーで登録する（同名ファミリの後勝ちを防ぐ）。
                map.insert(font_key(family, weight), font);
                // family 名だけのキーも用意する（ウェイト指定が無い描画のため）。
                // `VectorFont` は `Clone` ではないので同じバイト列から作り直す。
                // **既に入っていれば上書きしない**（最初に届いたものを保つ）。
                let plain = family.trim().to_lowercase();
                if !map.contains_key(&plain) {
                    if let Ok(f2) = VectorFont::new_with_fallbacks(leaked, &fallback_chain) {
                        map.insert(plain, f2);
                    }
                }
            }
            // 【2026-08-03 発見・修正】ここで `set_primary` して
            // **グローバル既定フォントを差し替えていた**。
            //
            // WOFF2 の展開・再構築を直して Font Awesome が実際に登録できるように
            // なった途端、**アイコンフォントが全文字を乗っ取る**という
            // 明白なリグレッションが出た（OS のタイトルバーやタブまで
            // アイコン書体になった。スクリーンショットで確認）。
            //
            // `@font-face` の登録は「この family でこのフォントが使える」と
            // 記録するだけであって、**文書全体の既定フォントを変える操作ではない**。
            // 差し替えはしない。
            //
            // 【残作業】描画側（`draw_string_ja_size_ext_bg_ls_ws`）は
            // `GLOBAL_VECTOR_FONT` しか見ておらず `font-family` を受け取らない。
            // そのため登録しただけでは Web フォントは字形に反映されない。
            // family 指定で `CUSTOM_FONTS` から選ぶ経路が本来の実装
            // （`spec/webfont_loading.md`）。
            // 節目のログ（1 ファミリにつき事実上 1 回。L-3）。
            //
            // 【2026-08-05】Font Awesome のアイコンが ☐ になる件の切り分け。
            // カスケード側（family・content・エスケープ解除）は単体試験で
            // 正常と確定済み。残る疑いは**字形そのものが無い**こと。
            // 代表的な符号位置（U+F02D=fa-book, U+F015=fa-home）を引いて記録する。
            let probe = |c: char| -> bool {
                CUSTOM_FONTS
                    .lock()
                    .get(&family.trim().to_lowercase())
                    .map(|f| f.has_glyph(c))
                    .unwrap_or(false)
            };
            crate::warn!(
                "[FONT] 登録完了 family={} bytes={} 字形F02D={} 字形F015={}",
                family,
                leaked.len(),
                probe('\u{f02d}'),
                probe('\u{f015}')
            );
            true
        }
        Err(e) => {
            crate::warn!(
                "[FONT] フォントのパースに失敗 family={} bytes={} err={:?}",
                family,
                leaked.len(),
                e
            );
            false
        }
    }
}

/// 指定した`font-family`名で登録済みのカスタムフォントが存在するかを返す
/// （大小文字を区別しない）。
/// 【2026-08-05】ウェイトまで見て登録済みかを返す。
///
/// `has_custom_font` は family 名だけを見るため、
/// `@font-face` の取り込みループが「同じ family は登録済み」と判断し、
/// **別ウェイト（solid 900）を一度も取り込まなかった**。
/// 実測: `Font Awesome 7 Free` に regular(400) だけが入り、
/// `.fas`（solid）のアイコンが描けなかった。
pub fn has_custom_font_weighted(family: &str, weight: u16) -> bool {
    CUSTOM_FONTS.lock().contains_key(&font_key(family, weight))
}

pub fn has_custom_font(family: &str) -> bool {
    CUSTOM_FONTS.lock().contains_key(&family.trim().to_lowercase())
}

// ============ フォントレジストリ ============
//
// 実行時にフォントフォルダは存在しないため、選択可能なフォントは include_bytes! で
// 埋め込んだものに限る。設定アプリのセレクトボックスはこの一覧を提示する。
// （フォントを増やすとカーネルバイナリ(.rodata)が肥大するため、代表的なものに絞る）

/// 設定アプリで選択できるフォント名の一覧（フォントフォルダ相当）。
pub const AVAILABLE_FONTS: &[&str] = &[
    "Mplus1Code-Regular",
    "HackGenConsoleNF-Regular",
    "ipam",
    "ipag",
    "MPLUS2-Regular",
    "MPLUS2-Bold",
];

/// OS レベルのデフォルトのフォントフォールバック順。
pub const DEFAULT_FONT_CHAIN: [&str; 3] =
    ["Mplus1Code-Regular", "HackGenConsoleNF-Regular", "ipam"];

/// フォント名から埋め込みバイト列を解決する。未知の名前は None。
pub fn font_bytes(name: &str) -> Option<&'static [u8]> {
    Some(match name {
        "Mplus1Code-Regular" => include_bytes!("../../fonts/Mplus1Code/Mplus1Code-Regular.ttf"),
        "HackGenConsoleNF-Regular" => {
            include_bytes!("../../fonts/HackGen/HackGenConsoleNF-Regular.ttf")
        }
        "ipam" => include_bytes!("../../fonts/ipa/ipam.ttf"),
        "ipag" | "IPAg" => include_bytes!("../../fonts/ipa/ipag.ttf"),
        "MPLUS2-Regular" => include_bytes!("../../fonts/MPLUS2/MPLUS2-Regular.ttf"),
        "MPLUS2-Bold" => include_bytes!("../../fonts/MPLUS2/MPLUS2-Bold.ttf"),
        _ => return None,
    })
}

/// フォント名のフォールバックチェーンからグローバルフォントを初期化する。
/// 先頭がプライマリ、以降がフォールバック。未知/解決不能な名前は読み飛ばす。
/// 有効なフォントが 1 つも無ければデフォルトチェーンにフォールバックする。
pub fn init_global_font_chain(names: &[&str]) {
    let mut bytes: Vec<&'static [u8]> = names.iter().filter_map(|n| font_bytes(n)).collect();
    if bytes.is_empty() {
        bytes = DEFAULT_FONT_CHAIN
            .iter()
            .filter_map(|n| font_bytes(n))
            .collect();
    }
    if bytes.is_empty() {
        crate::info!("[vector_font] No embedded fonts available for chain init!");
        return;
    }
    let primary = bytes[0];
    let fallbacks: Vec<&'static [u8]> = bytes[1..].to_vec();
    match VectorFont::new_with_fallbacks(primary, &fallbacks) {
        Ok(font) => {
            crate::info!(
                "[vector_font] Global font chain initialized ({} fonts).",
                bytes.len()
            );
            *GLOBAL_VECTOR_FONT.lock() = Some(font);
        }
        Err(e) => {
            crate::info!("[vector_font] Failed to init font chain: {:?}", e);
        }
    }
}

/// 起動時にフォントデータをロードしてグローバルインスタンスを初期化します
pub fn init_global_font(font_bytes: &'static [u8]) {
    match VectorFont::new(font_bytes) {
        Ok(mut font) => {
            crate::info!("[vector_font] Successfully initialized global vector font.");
            crate::info!("[vector_font] Running test get_glyph('o', 16) for global font...");
            if font.get_glyph('o', 16).is_some() {
                crate::info!("[vector_font] Test get_glyph('o', 16) succeeded for global font!");
            } else {
                crate::info!("[vector_font] Test get_glyph('o', 16) failed for global font!");
            }
            *GLOBAL_VECTOR_FONT.lock() = Some(font);
        }
        Err(e) => {
            crate::info!(
                "[vector_font] Failed to initialize global vector font: {:?}",
                e
            );
        }
    }
}

/// ターミナル専用の等幅ベクターフォントをロードして初期化します
pub fn init_terminal_font() {
    let font_bytes = include_bytes!("../../fonts/Mplus1Code/Mplus1Code-Regular.ttf");
    match VectorFont::new(font_bytes) {
        Ok(mut font) => {
            crate::info!("[vector_font] Successfully initialized terminal monospace font.");
            crate::info!("[vector_font] Running test get_glyph('o', 16)...");
            if font.get_glyph('o', 16).is_some() {
                crate::info!("[vector_font] Test get_glyph('o', 16) succeeded!");
            } else {
                crate::info!("[vector_font] Test get_glyph('o', 16) failed!");
            }
            *GLOBAL_TERMINAL_FONT.lock() = Some(font);
        }
        Err(e) => {
            crate::info!(
                "[vector_font] Failed to initialize terminal monospace font: {:?}",
                e
            );
        }
    }
}

/// グローバルフォントを用いて、指定したサイズでの文字列全体のピクセル幅を計算します
/// `family_list` と太字指定から、`draw::draw_string_family` と**同じ規則**で Web フォントを選び、
/// `f` に渡す（希望ウェイト → 文字列を描ける最も近いウェイト → family 名だけのキー）。
/// 登録済みの family が無ければ `None`（呼び出し側は内蔵フォントへ落とす）。
pub fn with_family_font<R>(
    s: &str,
    family_list: &str,
    bold: bool,
    f: impl FnOnce(&mut VectorFont) -> R,
) -> Option<R> {
    if family_list.is_empty() {
        return None;
    }
    let want: &[u16] = if bold { &[900, 700] } else { &[400] };
    let mut fonts = CUSTOM_FONTS.lock();
    for fam in family_list.split(',') {
        let key = fam.trim().trim_matches('"').trim_matches('\'').to_lowercase();
        if key.is_empty() {
            continue;
        }
        let prefix = alloc::format!("{}|", key);
        let available: Vec<(u16, bool)> = fonts
            .range(prefix.clone()..)
            .take_while(|(k, _)| k.starts_with(&prefix))
            .filter_map(|(k, font)| {
                let w = k.get(prefix.len()..)?.parse::<u16>().ok()?;
                Some((w, crate::kernel::font_select::covers_all(s, |c| font.primary_has_glyph(c))))
            })
            .collect();
        let hit = crate::kernel::font_select::pick_weight(want, &available)
            .map(|w| font_key(&key, w))
            .unwrap_or(key.clone());
        if fonts.contains_key(&hit) {
            if let Some(font) = fonts.get_mut(&hit) {
                return Some(f(font));
            }
        }
        // 総称名（sans-serif 等）は、このページで読み込まれた該当系統の Web フォントへ割り当てる
        // （`font_select::generic_family_candidates`。内蔵フォントは等幅のため）。
        for cand in crate::kernel::font_select::generic_family_candidates(&key) {
            let prefix = alloc::format!("{}|", cand);
            let available: Vec<(u16, bool)> = fonts
                .range(prefix.clone()..)
                .take_while(|(k, _)| k.starts_with(&prefix))
                .filter_map(|(k, font)| {
                    let w = k.get(prefix.len()..)?.parse::<u16>().ok()?;
                    Some((w, crate::kernel::font_select::covers_all(s, |c| font.primary_has_glyph(c))))
                })
                .collect();
            if let Some(w) = crate::kernel::font_select::pick_weight(want, &available) {
                if let Some(font) = fonts.get_mut(&font_key(cand, w)) {
                    return Some(f(font));
                }
            }
        }
    }
    None
}

/// `font-family` を考慮した文字列幅（`draw::draw_string_family` と**同じ書体選択**で測る）。
///
/// 【2026-09-26 バグ修正】行の組み立て（`web_engine::layout` の折り返し）は内蔵フォントの
/// 幅で測り、描画は Web フォント（Noto Sans JP 等）で描いていた。書体によって文字幅が違うため
/// 行が実際より短く見積もられ、描画時に窓の右端を超えた分が描画関数の中で勝手に改行されて、
/// 次の行と重なっていた（sugi-lab.net/profile.htm の研究概要）。
/// 登録済みの family が無ければ内蔵フォントの幅（従来どおり）。
pub fn get_vector_string_width_family(
    s: &str,
    size_px: u32,
    family_list: &str,
    bold: bool,
    ls: i32,
    ws: i32,
) -> u32 {
    with_family_font(s, family_list, bold, |f| f.get_string_width_ls_ws(s, size_px, ls, ws))
        .unwrap_or_else(|| get_vector_string_width_ls_ws(s, size_px, ls, ws))
}

/// `get_vector_string_wrapped_size_ext` の `font-family` 考慮版（レイアウトの箱の計測用。
/// 描画と同じ書体で折り返し行数を測る）。
#[allow(clippy::too_many_arguments)]
pub fn get_vector_string_wrapped_size_family(
    s: &str,
    size_px: u32,
    max_width: u32,
    ls: i32,
    ws: i32,
    word_break_all: bool,
    white_space_pre_wrap: bool,
    family_list: &str,
    bold: bool,
) -> (u32, u32) {
    with_family_font(s, family_list, bold, |f| {
        f.get_string_wrapped_size_ext(s, size_px, max_width, ls, ws, word_break_all, white_space_pre_wrap)
    })
    .unwrap_or_else(|| {
        get_vector_string_wrapped_size_ext(s, size_px, max_width, ls, ws, word_break_all, white_space_pre_wrap)
    })
}

pub fn get_vector_string_width(s: &str, size_px: u32) -> u32 {
    if let Some(ref mut font) = *GLOBAL_VECTOR_FONT.lock() {
        font.get_string_width(s, size_px)
    } else {
        s.len() as u32 * (size_px / 2) // 静的フォールバック値
    }
}

/// letter-spacing 対応版の文字列幅。ls は文字間に加える px(負も可)。
pub fn get_vector_string_width_ls(s: &str, size_px: u32, ls: i32) -> u32 {
    get_vector_string_width_ls_ws(s, size_px, ls, 0)
}

/// letter-spacing + word-spacing 対応版の文字列幅。ws は半角スペース1文字ごとに加える px(負も可)。
pub fn get_vector_string_width_ls_ws(s: &str, size_px: u32, ls: i32, ws: i32) -> u32 {
    if let Some(ref mut font) = *GLOBAL_VECTOR_FONT.lock() {
        font.get_string_width_ls_ws(s, size_px, ls, ws)
    } else {
        let space_count = s.chars().filter(|&c| c == ' ').count() as i32;
        let base = s.len() as i32 * (size_px / 2) as i32
            + s.chars().count() as i32 * ls
            + space_count * ws;
        base.max(0) as u32
    }
}

/// 1 文字ぶんの advance 幅を返す。
/// 折返し計算で 1 文字ずつ幅を加算する用途向け（行全体の再計測を避けて O(n) にする）。
pub fn get_vector_char_width(c: char, size_px: u32) -> u32 {
    if let Some(ref mut font) = *GLOBAL_VECTOR_FONT.lock() {
        font.get_glyph_advance(c, size_px)
    } else {
        size_px / 2
    }
}

pub fn get_vector_string_wrapped_size(s: &str, size_px: u32, max_width: u32) -> (u32, u32) {
    if let Some(ref mut font) = *GLOBAL_VECTOR_FONT.lock() {
        font.get_string_wrapped_size(s, size_px, max_width)
    } else {
        let char_w = size_px / 2;
        let max_chars = (max_width / char_w).max(1);
        let chars_count = s.chars().count() as u32;
        let lines = chars_count.div_ceil(max_chars);
        (
            max_width.min(chars_count * char_w),
            lines.max(1) * (size_px + 4),
        )
    }
}

/// letter-spacing 対応版の折返しサイズ。ls は文字間に加える px(負も可)。
pub fn get_vector_string_wrapped_size_ls(
    s: &str,
    size_px: u32,
    max_width: u32,
    ls: i32,
) -> (u32, u32) {
    get_vector_string_wrapped_size_ls_ws(s, size_px, max_width, ls, 0)
}

/// letter-spacing + word-spacing 対応版の折返しサイズ。ws は半角スペース1文字ごとに加える px(負も可)。
pub fn get_vector_string_wrapped_size_ls_ws(
    s: &str,
    size_px: u32,
    max_width: u32,
    ls: i32,
    ws: i32,
) -> (u32, u32) {
    if let Some(ref mut font) = *GLOBAL_VECTOR_FONT.lock() {
        font.get_string_wrapped_size_ls_ws(s, size_px, max_width, ls, ws)
    } else {
        let char_w = ((size_px / 2) as i32 + ls).max(1) as u32;
        let max_chars = (max_width / char_w).max(1);
        let chars_count = s.chars().count() as u32;
        let lines = chars_count.div_ceil(max_chars);
        (
            max_width.min(chars_count * char_w),
            lines.max(1) * (size_px + 4),
        )
    }
}

pub fn get_vector_string_wrapped_size_ext(
    s: &str,
    size_px: u32,
    max_width: u32,
    ls: i32,
    ws: i32,
    word_break_all: bool,
    white_space_pre_wrap: bool,
) -> (u32, u32) {
    if let Some(ref mut font) = *GLOBAL_VECTOR_FONT.lock() {
        font.get_string_wrapped_size_ext(s, size_px, max_width, ls, ws, word_break_all, white_space_pre_wrap)
    } else {
        let char_w = ((size_px / 2) as i32 + ls).max(1) as u32;
        let max_chars = (max_width / char_w).max(1);
        let chars_count = s.chars().count() as u32;
        let lines = chars_count.div_ceil(max_chars);
        (
            max_width.min(chars_count * char_w),
            lines.max(1) * (size_px + 4),
        )
    }
}

pub fn is_line_start_forbidden(c: char) -> bool {
    matches!(
        c,
        '、' | '。'
            | '，'
            | '．'
            | '・'
            | '：'
            | '；'
            | '？'
            | '！'
            | '）'
            | '］'
            | '｝'
            | '〉'
            | '》'
            | '』'
            | '」'
            | '〕'
            | 'ー'
            | '〜'
            | '々'
            | '〆'
            | 'ぁ'
            | 'ぃ'
            | 'ぅ'
            | 'ぇ'
            | 'ぉ'
            | 'っ'
            | 'ゃ'
            | 'ゅ'
            | 'ょ'
            | 'ゎ'
            | 'ァ'
            | 'ィ'
            | 'ゥ'
            | 'ェ'
            | 'ォ'
            | 'ッ'
            | 'ャ'
            | 'ュ'
            | 'ョ'
            | 'ヮ'
            | 'ヶ'
            | 'ヵ'
    )
}

pub fn is_line_end_forbidden(c: char) -> bool {
    matches!(c, '（' | '［' | '｛' | '〈' | '《' | '『' | '「' | '〔')
}