fast_unicode-display_width 0.1.1-x86_64-linux

data/ext/fast_unicode/display_width/extconf.rb

@@ -0,0 +1,4 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("fast_unicode/display_width/display_width")

data/ext/fast_unicode/display_width/src/lib.rs

@@ -0,0 +1,520 @@
+use magnus::{
+    function,
+    prelude::*,
+    r_hash::ForEach,
+    value::ReprValue,
+    Error, RHash, RString, Ruby, Value,
+};
+use std::collections::HashMap;
+use unicode_segmentation::UnicodeSegmentation;
+use unicode_width::UnicodeWidthChar;
+
+include!(concat!(env!("OUT_DIR"), "/rgi_set.rs"));
+include!(concat!(env!("OUT_DIR"), "/width_delta.rs"));
+
+/// Look up the per-codepoint width-correction delta vs `unicode-width` 0.2.
+///
+/// Returns the (delta_amb1, delta_amb2) the runtime must add on top of the
+/// `unicode-width` value so we land on upstream's table. `0` is returned for
+/// codepoints that match upstream verbatim — the common case — and the early
+/// MIN/MAX screen lets bulk paths skip the binary search entirely on inputs
+/// that touch no diverging codepoints.
+#[inline]
+fn width_delta(cp: u32) -> (i8, i8) {
+    // Latin-1 codepoints get a direct array lookup — they're dense in the
+    // delta table (most Latin-1 letters carry a d2 delta because upstream
+    // treats them as ambiguous=wide), so the binary search dominated the
+    // cost on accented-Latin and middle-dot inputs.
+    if cp < 0x100 {
+        return LATIN1_DELTA[cp as usize];
+    }
+    if cp < WIDTH_DELTA_MIN || cp > WIDTH_DELTA_MAX {
+        return (0, 0);
+    }
+    match WIDTH_DELTA.binary_search_by(|&(start, end, _, _)| {
+        if cp < start {
+            std::cmp::Ordering::Greater
+        } else if cp > end {
+            std::cmp::Ordering::Less
+        } else {
+            std::cmp::Ordering::Equal
+        }
+    }) {
+        Ok(idx) => {
+            let (_, _, d1, d2) = WIDTH_DELTA[idx];
+            (d1, d2)
+        }
+        Err(_) => (0, 0),
+    }
+}
+
+#[inline]
+fn runtime_error<E: ToString>(ruby: &Ruby, e: E) -> Error {
+    Error::new(ruby.exception_runtime_error(), e.to_string())
+}
+
+#[inline]
+fn type_error(ruby: &Ruby, msg: &'static str) -> Error {
+    Error::new(ruby.exception_type_error(), msg)
+}
+
+#[inline]
+fn argument_error<E: ToString>(ruby: &Ruby, e: E) -> Error {
+    Error::new(ruby.exception_arg_error(), e.to_string())
+}
+
+#[derive(Copy, Clone, Eq, PartialEq)]
+enum EmojiMode {
+    None,
+    All,
+    AllNoVs16,
+    Vs16,
+    Rgi,
+    RgiAt,
+    Possible,
+}
+
+/// Canonical symbol↔integer mapping for emoji modes. The integer code is the
+/// index into this slice, so `from_code` and the Ruby-facing `EMOJI_MODE_CODES`
+/// hash (built in `init`) stay in sync by construction. To add a mode, append
+/// here and extend `EmojiMode`.
+const EMOJI_MODES: &[(&str, EmojiMode)] = &[
+    ("none", EmojiMode::None),
+    ("all", EmojiMode::All),
+    ("all_no_vs16", EmojiMode::AllNoVs16),
+    ("vs16", EmojiMode::Vs16),
+    ("rgi", EmojiMode::Rgi),
+    ("rgi_at", EmojiMode::RgiAt),
+    ("possible", EmojiMode::Possible),
+];
+
+impl EmojiMode {
+    fn from_code(code: i64) -> Option<Self> {
+        let idx = usize::try_from(code).ok()?;
+        EMOJI_MODES.get(idx).map(|&(_, m)| m)
+    }
+}
+
+/// Compute the monospace display width of `data`, treating it as UTF-8.
+///
+/// - `ambiguous`: 1 → narrow (`width()`), 2 → wide (`width_cjk()`).
+/// - `overwrite`: `nil` or `Hash{Integer => Integer}` codepoint→width.
+/// - `emoji_mode`: integer code, see `EmojiMode::from_code`.
+fn width_native(
+    ruby: &Ruby,
+    data: RString,
+    ambiguous: i64,
+    overwrite: Value,
+    emoji_mode: i64,
+) -> Result<i64, Error> {
+    let cjk = match ambiguous {
+        1 => false,
+        2 => true,
+        _ => return Err(argument_error(ruby, "ambiguous must be 1 or 2")),
+    };
+    let mode = EmojiMode::from_code(emoji_mode)
+        .ok_or_else(|| argument_error(ruby, "invalid emoji mode code"))?;
+
+    let overwrites = build_overwrite_map(ruby, overwrite)?;
+    let bytes = unsafe { data.as_slice() };
+
+    // Pure-ASCII inputs can't contain emoji sequences, so the emoji branches
+    // are irrelevant. Skip both `from_utf8` and grapheme iteration.
+    if overwrites.is_none() && bytes.is_ascii() {
+        return Ok(width_ascii(bytes) as i64);
+    }
+
+    let s = std::str::from_utf8(bytes).map_err(|e| runtime_error(ruby, e))?;
+
+    if mode == EmojiMode::None {
+        return Ok(width_none(s, cjk, overwrites.as_ref()) as i64);
+    }
+
+    // vs16 is a 2-/3-codepoint lookahead pattern (`base + FE0F [+ 20E3]`),
+    // not a true grapheme construct. Walking codepoints directly avoids the
+    // per-cluster cost of `unicode-segmentation`, which dominated the
+    // measured runtime on every vs16 input.
+    if mode == EmojiMode::Vs16 {
+        return Ok(width_vs16(s, cjk, overwrites.as_ref()));
+    }
+
+    Ok(width_with_emoji(s, cjk, mode, overwrites.as_ref()))
+}
+
+#[inline]
+fn width_none(s: &str, cjk: bool, ow: Option<&HashMap<u32, i64>>) -> usize {
+    if let Some(map) = ow {
+        return sum_with_overwrites(s, cjk, map);
+    }
+    if let Some(n) = common_narrow_shortcut(s, cjk) {
+        return n;
+    }
+    // Can't use `s.width()` / `s.width_cjk()`: unicode-width 0.2 applies
+    // its own emoji-cluster logic at the string level (VS16 promotes the
+    // preceding text-presentation char to width 2, skin-tone sequences
+    // collapse, …). Upstream's `emoji: :none` walks codepoints one at a
+    // time, so we do too. `codepoint_width` already folds in the delta
+    // table per-cp; ASCII goes through `ascii_codepoint_contribution`.
+    let mut total: i64 = 0;
+    for c in s.chars() {
+        let cp = c as u32;
+        if cp < 0x80 {
+            total += ascii_codepoint_contribution(cp as u8);
+        } else {
+            total += codepoint_width(c, cjk);
+        }
+    }
+    total.max(0) as usize
+}
+
+/// Upstream's "common narrow" early-exit: when *every* codepoint sits inside
+/// the common-narrow band (0x10..=0x2FF for `width()`, 0x10..=0xA1 for
+/// `width_cjk()`), upstream returns `string.size` and never consults the
+/// INDEX. That bypass intentionally collapses a handful of ambiguous
+/// codepoints (e.g. U+00A1 under cjk, which the INDEX records as 2) down to
+/// 1, so we mirror it exactly. Mirrors `NOT_COMMON_NARROW_REGEX` in
+/// `display_width.rb`.
+#[inline]
+fn common_narrow_shortcut(s: &str, cjk: bool) -> Option<usize> {
+    let max_common: u32 = if cjk { 0xA1 } else { 0x2FF };
+    let mut count = 0usize;
+    for c in s.chars() {
+        let cp = c as u32;
+        if cp < 0x10 || cp > max_common {
+            return None;
+        }
+        count += 1;
+    }
+    Some(count)
+}
+
+/// vs16-specific fast path: scan codepoints linearly, handling the two
+/// upstream patterns by lookahead instead of grapheme segmentation.
+///
+/// Patterns matched (each → width 2, consumes the whole run):
+///   - `BASE + FE0F` where BASE is not `#`, `*`, or `0..=9` (text-presentation
+///     promotion).
+///   - `BASE + FE0F + 20E3` where BASE is `#`, `*`, or `0..=9` (keycap).
+///
+/// All other codepoints contribute their per-codepoint width — combining
+/// marks and ZWJ are width 0 in the upstream table, so codepoint-sum agrees
+/// with cluster-sum for the non-emoji portion.
+fn width_vs16(s: &str, cjk: bool, ow: Option<&HashMap<u32, i64>>) -> i64 {
+    let mut total: i64 = 0;
+    let mut chars = s.chars().peekable();
+    while let Some(c) = chars.next() {
+        if chars.peek().copied() == Some('\u{FE0F}') {
+            let is_keycap_base = matches!(c, '#' | '*' | '0'..='9');
+            if !is_keycap_base {
+                chars.next(); // consume FE0F
+                total += 2;
+                continue;
+            }
+            // Keycap candidate: peek past FE0F for U+20E3 without consuming
+            // unless the full sequence matches. `Peekable<Chars>` is Clone
+            // (just a slice cursor), so this is cheap.
+            let mut probe = chars.clone();
+            probe.next(); // skip FE0F in the probe
+            if probe.peek().copied() == Some('\u{20E3}') {
+                chars.next(); // FE0F
+                chars.next(); // 20E3
+                total += 2;
+                continue;
+            }
+            // Digit + FE0F without the 20E3 follow-up: fall through to the
+            // per-codepoint sum so digit contributes 1 and FE0F contributes 0.
+        }
+        let cp = c as u32;
+        if let Some(map) = ow {
+            if let Some(&w) = map.get(&cp) {
+                total += w;
+                continue;
+            }
+        }
+        if cp < 0x80 {
+            total += ascii_codepoint_contribution(cp as u8);
+        } else {
+            total += codepoint_width(c, cjk);
+        }
+    }
+    total.max(0)
+}
+
+fn width_with_emoji(s: &str, cjk: bool, mode: EmojiMode, ow: Option<&HashMap<u32, i64>>) -> i64 {
+    // Byte-level screen: when no codepoint that *could* trigger a multi-
+    // codepoint emoji cluster (ZWJ, FE0F, skin tone, keycap, regional
+    // indicator) appears anywhere in the input, every grapheme cluster is
+    // necessarily a single codepoint. For single-codepoint clusters the
+    // emoji-mode branches all collapse to the per-codepoint width
+    // (`emoji_cluster_width` returns `None` for the multi-codepoint patterns
+    // and RGI single-codepoint matches always equal the codepoint width
+    // because upstream's table agrees with `unicode-width` on those points).
+    // Falling back to `width_none` avoids the grapheme iterator entirely.
+    if !could_emit_emoji_cluster(s.as_bytes(), mode) {
+        return width_none(s, cjk, ow) as i64;
+    }
+    let mut total: i64 = 0;
+    for cluster in s.graphemes(true) {
+        if let Some(w) = emoji_cluster_width(cluster, mode, cjk) {
+            total += w;
+        } else {
+            total += cluster_width_via_tables(cluster, cjk, ow);
+        }
+    }
+    total.max(0)
+}
+
+/// Byte-level prescan for codepoints that begin or participate in a
+/// multi-codepoint emoji cluster. Returns `true` if such a codepoint *might*
+/// be present (the screen is conservative — false positives just route the
+/// caller through the grapheme path, which is always correct).
+///
+/// Triggers checked:
+///   - 0xE2 (3-byte UTF-8 lead) → covers ZWJ (E2 80 8D) and U+20E3 keycap.
+///   - 0xEF → covers FE0F (EF B8 8F).
+///   - 0xF0 0x9F 0x8F → skin tones (1F3FB..1F3FF, 4-byte lead 0xF0).
+///   - 0xF0 0x9F 0x87 → regional indicators (1F1E6..1F1FF, flag clusters).
+///
+/// For modes that don't react to FE0F (e.g. `AllNoVs16`) the 0xEF check is
+/// still safe — it just routes a few more inputs through the slow path. The
+/// RGI/Possible modes need every multi-codepoint trigger because RGI clusters
+/// can join via ZWJ or RI pairs.
+#[inline]
+fn could_emit_emoji_cluster(bytes: &[u8], _mode: EmojiMode) -> bool {
+    let n = bytes.len();
+    let mut i = 0;
+    while i < n {
+        let b = bytes[i];
+        if b == 0xE2 || b == 0xEF {
+            return true;
+        }
+        if b == 0xF0 && i + 2 < n && bytes[i + 1] == 0x9F {
+            let third = bytes[i + 2];
+            if third == 0x8F || third == 0x87 {
+                return true;
+            }
+        }
+        i += 1;
+    }
+    false
+}
+
+/// Returns `Some(width)` if the given grapheme cluster is consumed by the
+/// emoji mode, else `None` (caller falls back to per-codepoint widths).
+///
+/// `EmojiMode::None` and `EmojiMode::Vs16` are routed to dedicated paths in
+/// `width_native` before reaching here; they're rejected by the caller, not
+/// matched here.
+fn emoji_cluster_width(cluster: &str, mode: EmojiMode, cjk: bool) -> Option<i64> {
+    match mode {
+        EmojiMode::All => is_emoji_sequence_or_vs16(cluster).then_some(2),
+        EmojiMode::AllNoVs16 => is_emoji_sequence_no_vs16(cluster).then_some(2),
+        EmojiMode::Rgi | EmojiMode::Possible => {
+            RGI_SEQUENCES.contains(cluster).then_some(2)
+        }
+        EmojiMode::RgiAt => RGI_SEQUENCES.contains(cluster).then(|| {
+            let first = cluster.chars().next().unwrap();
+            if (first as u32) < 0x80 {
+                ascii_codepoint_contribution(first as u8)
+            } else {
+                codepoint_width(first, cjk)
+            }
+        }),
+        EmojiMode::None | EmojiMode::Vs16 => unreachable!(
+            "EmojiMode::None and EmojiMode::Vs16 are dispatched before width_with_emoji"
+        ),
+    }
+}
+
+/// Multi-codepoint cluster containing ZWJ, skin-tone modifier, VS16, or
+/// COMBINING ENCLOSING KEYCAP. Matches upstream's REGEX_EMOJI_ALL_SEQUENCES
+/// + REGEX_EMOJI_KEYCAP + REGEX_TEXT_PRESENTATION+VS16 union.
+fn is_emoji_sequence_or_vs16(cluster: &str) -> bool {
+    let mut chars = cluster.chars();
+    if chars.next().is_none() {
+        return false;
+    }
+    let mut count = 1usize;
+    let mut has_marker = false;
+    for c in chars {
+        count += 1;
+        if matches!(
+            c,
+            '\u{200D}' | '\u{FE0F}' | '\u{1F3FB}'..='\u{1F3FF}' | '\u{20E3}'
+        ) {
+            has_marker = true;
+        }
+    }
+    count > 1 && has_marker
+}
+
+/// Same as above but excludes pure-VS16 (text-presentation + VS16) clusters.
+fn is_emoji_sequence_no_vs16(cluster: &str) -> bool {
+    let mut chars = cluster.chars();
+    if chars.next().is_none() {
+        return false;
+    }
+    let mut count = 1usize;
+    let mut has_non_vs16_marker = false;
+    for c in chars {
+        count += 1;
+        if matches!(
+            c,
+            '\u{200D}' | '\u{1F3FB}'..='\u{1F3FF}' | '\u{20E3}'
+        ) {
+            has_non_vs16_marker = true;
+        }
+    }
+    count > 1 && has_non_vs16_marker
+}
+
+#[inline]
+fn cluster_width_via_tables(cluster: &str, cjk: bool, ow: Option<&HashMap<u32, i64>>) -> i64 {
+    let mut total: i64 = 0;
+    for c in cluster.chars() {
+        let cp = c as u32;
+        if let Some(map) = ow {
+            if let Some(&w) = map.get(&cp) {
+                total += w;
+                continue;
+            }
+        }
+        if cp < 0x80 {
+            total += ascii_codepoint_contribution(cp as u8);
+        } else {
+            total += codepoint_width(c, cjk);
+        }
+    }
+    total
+}
+
+/// Per-codepoint width matching upstream's table — `unicode-width` lookup
+/// (with the same None→1 fallback `UnicodeWidthStr` uses) plus the delta
+/// correction. ASCII is handled separately via `ascii_codepoint_contribution`.
+#[inline]
+fn codepoint_width(c: char, cjk: bool) -> i64 {
+    let base = if cjk {
+        UnicodeWidthChar::width_cjk(c)
+    } else {
+        UnicodeWidthChar::width(c)
+    }
+    .unwrap_or(1) as i64;
+    let (d1, d2) = width_delta(c as u32);
+    let delta = if cjk { d2 } else { d1 } as i64;
+    base + delta
+}
+
+#[inline]
+fn ascii_codepoint_contribution(b: u8) -> i64 {
+    // Upstream's ASCII rule: zero-list bytes contribute 0, backspace
+    // contributes -1, everything else (tab, DEL, other C0, printable) 1.
+    if b == 0x08 {
+        -1
+    } else if is_zero_width_ascii(b) {
+        0
+    } else {
+        1
+    }
+}
+
+/// Upstream's `ASCII_NON_ZERO_STRING` decoded: bytes whose display width is 0.
+/// 0x00, 0x05, BEL (0x07), BS (0x08), LF (0x0A), VT/FF/CR/SO/SI (0x0B..=0x0F).
+#[inline]
+fn is_zero_width_ascii(b: u8) -> bool {
+    b < 0x10 && !matches!(b, 0x01..=0x04 | 0x06 | 0x09)
+}
+
+#[inline]
+fn width_ascii(bytes: &[u8]) -> usize {
+    // Two-pass: a SIMD-friendly screen first to short-circuit the very common
+    // all-printable case (`bytes.len()` directly), and only walk a second time
+    // when there's actually a C0 or DEL byte to subtract. A single-pass loop
+    // counting `zero`/`bs` unconditionally regressed long-ASCII throughput by
+    // ~3x because the all-printable case is by far the dominant input.
+    if count_c0_and_del(bytes) == 0 {
+        return bytes.len();
+    }
+    let (zero, bs) = count_zero_and_bs(bytes);
+    bytes.len().saturating_sub(zero).saturating_sub(bs)
+}
+
+#[inline]
+fn count_c0_and_del(bytes: &[u8]) -> usize {
+    bytes
+        .iter()
+        .map(|&b| (b < 0x20 || b == 0x7F) as usize)
+        .sum()
+}
+
+#[inline]
+fn count_zero_and_bs(bytes: &[u8]) -> (usize, usize) {
+    let mut zero: usize = 0;
+    let mut bs: usize = 0;
+    for &b in bytes {
+        zero += is_zero_width_ascii(b) as usize;
+        bs += (b == 0x08) as usize;
+    }
+    (zero, bs)
+}
+
+fn build_overwrite_map(
+    ruby: &Ruby,
+    overwrite: Value,
+) -> Result<Option<HashMap<u32, i64>>, Error> {
+    if overwrite.is_nil() {
+        return Ok(None);
+    }
+    let hash = RHash::from_value(overwrite)
+        .ok_or_else(|| type_error(ruby, "overwrite must be a Hash or nil"))?;
+    let mut map: HashMap<u32, i64> = HashMap::with_capacity(hash.len());
+    hash.foreach(|cp: i64, w: i64| {
+        if !(0..=0x10_FFFF).contains(&cp) {
+            return Err(argument_error(
+                ruby,
+                format!("overwrite codepoint {cp} is out of range (0..=0x10FFFF)"),
+            ));
+        }
+        map.insert(cp as u32, w);
+        Ok(ForEach::Continue)
+    })?;
+    Ok(Some(map))
+}
+
+#[inline]
+fn sum_with_overwrites(s: &str, cjk: bool, map: &HashMap<u32, i64>) -> usize {
+    let mut total: i64 = 0;
+    for c in s.chars() {
+        let cp = c as u32;
+        if let Some(&w) = map.get(&cp) {
+            total += w;
+        } else if cp < 0x80 {
+            total += ascii_codepoint_contribution(cp as u8);
+        } else {
+            total += codepoint_width(c, cjk);
+        }
+    }
+    total.max(0) as usize
+}
+
+#[magnus::init(name = "display_width")]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("FastUnicode")?;
+    let klass = module.define_class("DisplayWidth", ruby.class_object())?;
+
+    // FFI binding lives under `DisplayWidth::Native` so the public surface
+    // doesn't advertise `width_native` (which bypasses encoding normalization
+    // and can crash the extension on invalid UTF-8). The Ruby side marks
+    // `Native` as `private_constant`.
+    let native = klass.define_module("Native")?;
+    native.define_singleton_method("width_native", function!(width_native, 4))?;
+
+    // Single source of truth for the symbol↔code mapping: derived from
+    // `EMOJI_MODES` so Ruby and Rust can't drift apart.
+    let codes = ruby.hash_new();
+    for (idx, (name, _)) in EMOJI_MODES.iter().enumerate() {
+        codes.aset(ruby.to_symbol(name), idx as i64)?;
+    }
+    codes.freeze();
+    klass.const_set("EMOJI_MODE_CODES", codes)?;
+    Ok(())
+}

data/lib/fast_unicode/display_width/emoji_support.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module FastUnicode
+  class DisplayWidth
+    # Ported from upstream's `Unicode::DisplayWidth::EmojiSupport`. Picks a
+    # default emoji mode based on which terminal emulator the process is
+    # running under, so the gem's default behavior matches the upstream
+    # gem's recommendation for the same environment.
+    module EmojiSupport
+      # No memoization here: callers that need the value frozen at load time
+      # (e.g. `DEFAULT_EMOJI_CODE`) cache it themselves. Recomputing on each
+      # call keeps the function ENV-honest and makes it testable.
+      def self.recommended
+        # Upstream returns `:rqi` here (a typo); it falls through to the
+        # `else` branch in `emoji_width` and behaves like `:none`. We
+        # preserve the typo so our default exactly matches upstream's.
+        return :rqi if ENV["CI"]
+
+        case ENV["TERM_PROGRAM"]
+        when "iTerm.app"      then return :all
+        when "Apple_Terminal" then return :rgi_at
+        when "WezTerm"        then return :all_no_vs16
+        end
+
+        case ENV["TERM"]
+        when "contour", "foot" then return :all
+        when /kitty/           then return :vs16
+        end
+
+        return :vs16 if ENV["WT_SESSION"]
+
+        :none
+      end
+    end
+  end
+end

data/lib/fast_unicode/display_width/string_ext.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../display_width'
+
+module FastUnicode
+  class DisplayWidth
+    # Refinement adding `String#display_width`. Matches the shape of
+    # `Unicode::DisplayWidth::StringExt` so call sites can be swapped 1:1.
+    #
+    #   using FastUnicode::DisplayWidth::StringExt
+    #   "一二三".display_width  # => 6
+    module StringExt
+      refine String do
+        def display_width(*args, **kwargs)
+          FastUnicode::DisplayWidth.of(self, *args, **kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/fast_unicode/display_width/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module FastUnicode
+  class DisplayWidth
+    VERSION = '0.1.1'
+  end
+end

data/lib/fast_unicode/display_width.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'display_width/display_width'
+require_relative 'display_width/version'
+require_relative 'display_width/emoji_support'
+
+module FastUnicode
+  # Drop-in API shape for `Unicode::DisplayWidth` (v3.x). Renamed to the
+  # `FastUnicode` namespace so both gems can coexist without conflict.
+  #
+  # Supported:
+  #   - `ambiguous` (1 or 2) — East Asian Width ambiguous behavior.
+  #   - `overwrite` ({Integer => Integer}) — fixed widths for codepoints.
+  #   - `emoji:` (:none, :all, :all_no_vs16, :vs16, :rgi, :rgi_at, :possible,
+  #     true, :auto, false). `nil`/`true`/`:auto` resolve to
+  #     `EmojiSupport.recommended`. `false` is equivalent to `:none`.
+  #
+  # Returns an Integer (column count, never negative).
+  class DisplayWidth
+    # `Native` and `EMOJI_MODE_CODES` are defined by the Rust extension during
+    # `init` (see `ext/fast_unicode/display_width/src/lib.rs`). `Native` holds
+    # the unsafe FFI binding (no encoding normalization, raw integer enum
+    # codes) and is intentionally hidden — call `DisplayWidth.of` instead.
+    private_constant :Native
+
+    DEFAULT_EMOJI_CODE = EMOJI_MODE_CODES.fetch(EmojiSupport.recommended, 0)
+
+    # Private sentinel for "caller did not pass `emoji:`". Distinct from any
+    # user-supplied value, including `nil`, `true`, and `:auto`, which the
+    # upstream gem treats as explicit requests for the detected default.
+    OMITTED = Object.new.freeze
+    private_constant :OMITTED
+
+    # Encoding normalization + emoji-mode resolution. Public methods funnel
+    # through `Internal.compute` so the unsafe `Native.width_native` binding
+    # only has one caller and the normalization can't be bypassed.
+    module Internal
+      module_function
+
+      def compute(string, ambiguous, overwrite, emoji_code)
+        Native.width_native(normalize_encoding(string), ambiguous, overwrite, emoji_code)
+      end
+
+      # Mirrors the upstream gem's encoding contract: a BINARY string is
+      # reinterpreted as UTF-8 only if its bytes form valid UTF-8; otherwise
+      # it falls through to `String#encode` with replacement. Non-UTF-8
+      # encodings are always transcoded so the Rust side never sees invalid
+      # bytes.
+      def normalize_encoding(string)
+        if string.encoding == Encoding::BINARY
+          candidate = string.dup.force_encoding(Encoding::UTF_8)
+          return candidate if candidate.valid_encoding?
+          return string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+        return string if string.encoding == Encoding::UTF_8
+        string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+
+      # Resolves the user-facing `emoji:` argument to the integer code passed
+      # to Rust. `nil`/`true`/`:auto` collapse to the detected default,
+      # mirroring upstream. The `OMITTED` sentinel never reaches here — call
+      # sites short-circuit it to `DEFAULT_EMOJI_CODE` first.
+      def resolve_emoji_code(value)
+        case value
+        when nil, true, :auto then DEFAULT_EMOJI_CODE
+        when false then EMOJI_MODE_CODES[:none]
+        else
+          EMOJI_MODE_CODES.fetch(value) do
+            raise ArgumentError, "unknown emoji mode: #{value.inspect}"
+          end
+        end
+      end
+    end
+    private_constant :Internal
+
+    def self.of(string, ambiguous = 1, **opts)
+      if opts.empty?
+        return Internal.compute(string, ambiguous, nil, DEFAULT_EMOJI_CODE)
+      end
+      ambig = opts.key?(:ambiguous) ? opts[:ambiguous] : ambiguous
+      code = opts.key?(:emoji) ? Internal.resolve_emoji_code(opts[:emoji]) : DEFAULT_EMOJI_CODE
+      Internal.compute(string, ambig, opts[:overwrite], code)
+    end
+
+    def initialize(ambiguous: 1, overwrite: nil, emoji: OMITTED)
+      @ambiguous = ambiguous
+      @overwrite = overwrite
+      @emoji_code = emoji.equal?(OMITTED) ? DEFAULT_EMOJI_CODE : Internal.resolve_emoji_code(emoji)
+    end
+
+    def of(string)
+      Internal.compute(string, @ambiguous, @overwrite, @emoji_code)
+    end
+  end
+end