mos_fonts/

shape.rs

use std::borrow::Cow;

use crate::{
    EmbeddedFontId, Font, ShapedGlyph, advance_units_to_pt, normalize::nfc_text, shape, text_width,
};

/// Shape `text` against `font`.
///
/// Returns both glyph stream and advance width. Callers that will emit glyphs
/// downstream should use this to avoid shaping twice.
///
/// Input is normalized through [`crate::nfc_text`] before shaping, so
/// decomposed sequences are precomposed to Unicode NFC. Returned glyph
/// cluster offsets are byte offsets into that normalized text, not
/// necessarily the caller's original string.
///
/// For Base14 faces, `glyphs` is empty (Base14 runs go out as
/// `WinAnsi`-byte strings, not glyph IDs); only the width is computed.
///
/// # Examples
///
/// ```
/// use mos_fonts::{Base14Font, Font, shape_text};
///
/// let run = shape_text(Font::Base14(Base14Font::Helvetica), 10.0, "A");
///
/// assert!(run.glyphs.is_empty());
/// assert_eq!(run.advance_pt, 6.67);
/// ```
#[must_use]
pub fn shape_text(font: Font, size: f32, text: &str) -> ShapedRun {
    let text = nfc_text(text);
    let text = text.as_ref();
    match font {
        Font::Base14(_) => ShapedRun {
            glyphs: Vec::new(),
            advance_pt: text_width(font, size, text),
        },
        Font::Embedded(id) => {
            let ef = id.data();
            let glyphs = shape(ef, text);
            let upem = f32::from(ef.units_per_em);
            let advance_pt: f32 = glyphs
                .iter()
                .map(|g| advance_units_to_pt(g.advance_units, size, upem))
                .sum();
            ShapedRun { glyphs, advance_pt }
        }
    }
}

/// Output of [`shape_text`]: the shaped glyph stream and the total
/// advance width at the requested point size.
///
/// # Examples
///
/// ```
/// use mos_fonts::ShapedRun;
///
/// let run = ShapedRun {
///     glyphs: Vec::new(),
///     advance_pt: 12.0,
/// };
///
/// assert_eq!(run.advance_pt, 12.0);
/// ```
#[derive(Debug, Clone)]
pub struct ShapedRun {
    /// Glyphs in visual order (LTR). Empty for Base14 runs.
    pub glyphs: Vec<ShapedGlyph>,
    /// Total horizontal advance of the run, in PDF user-space units.
    pub advance_pt: f32,
}

/// One face's slice of a per-glyph-fallback shaping result.
///
/// Each sub-run is self-contained: its `text` is the covered source slice,
/// cluster offsets are rebased to local text, and `advance_pt` is the sum of
/// per-glyph advances at the requested point size.
///
/// Caller emits **one PDF `TextRun` per `WordSubRun`**: same
/// baseline, x-cursor advances by `advance_pt` between sub-runs: and
/// PDF emit's existing `Tf` switch fires naturally on the font change.
///
/// # Examples
///
/// ```
/// use mos_fonts::{Base14Font, Font, WordSubRun};
///
/// let subrun = WordSubRun {
///     font: Font::Base14(Base14Font::Helvetica),
///     text: "A".to_owned(),
///     glyphs: Vec::new(),
///     advance_pt: 6.67,
/// };
///
/// assert_eq!(subrun.text, "A");
/// ```
#[derive(Debug, Clone)]
pub struct WordSubRun {
    /// Which face owns the glyphs in this slice. May be the primary
    /// (no fallback was needed for this span) or a fallback face that
    /// covered codepoints the primary lacked.
    pub font: Font,
    /// Source byte slice covered by this sub-run. `glyphs`' `cluster`
    /// values are byte offsets into **this** field, not into the parent
    /// word's text.
    pub text: String,
    /// Shaped glyphs in visual order (LTR). Cluster offsets are local
    /// to `text` (rebased from the parent word's full text). Empty for
    /// Base14 sub-runs (Base14 has no glyph stream: PDF emit goes via
    /// `WinAnsi`-byte encoding instead).
    pub glyphs: Vec<ShapedGlyph>,
    /// Total horizontal advance of this sub-run, in PDF user-space
    /// units. Sum of PDF-emittable `glyphs[i].advance_units` scaled by
    /// `size_pt / units_per_em`.
    pub advance_pt: f32,
}

/// Split shaped runs at a byte offset in their concatenated [`WordSubRun::text`].
///
/// Complete runs on either side retain their glyphs and measured advances.
/// A run crossed by the split is reshaped on both sides with its own font and
/// the supplied fallback chain, so ligatures and positioning across the cut
/// are recalculated. Each output run's cluster offsets remain local to its text.
/// Use the same `size_pt` and fallback chain used to produce the input runs.
/// The offset refers to the runs' text, which may already have been normalized,
/// not to the document text before shaping.
///
/// Returns `None` if the offset exceeds the concatenated text length, falls
/// inside a UTF-8 codepoint, or the accumulated text length overflows.
/// Empty input accepts only offset zero. Splitting at either end reuses all
/// runs without shaping. This operation does not insert a hyphen or choose a
/// line-break opportunity.
///
/// # Examples
/// ```
/// use mos_fonts::{Base14Font, Font, shape_with_fallback, split_runs_at};
///
/// let runs = shape_with_fallback(Font::Base14(Base14Font::Helvetica), &[], 12.0, "hello");
/// let (left, right) = split_runs_at(&runs, 2, 12.0, &[]).expect("valid split");
/// assert_eq!(left[0].text, "he");
/// assert_eq!(right[0].text, "llo");
/// ```
#[must_use]
pub fn split_runs_at(
    runs: &[WordSubRun],
    offset: usize,
    size_pt: f32,
    fallbacks: &[EmbeddedFontId],
) -> Option<(Vec<WordSubRun>, Vec<WordSubRun>)> {
    let mut prefix = Vec::new();
    let mut suffix = Vec::new();
    let mut start = 0_usize;
    for run in runs {
        let end = start.checked_add(run.text.len())?;
        if end <= offset {
            prefix.push(run.clone());
        } else if start >= offset {
            suffix.push(run.clone());
        } else {
            let local_offset = offset - start;
            let before = run.text.get(..local_offset)?;
            let after = run.text.get(local_offset..)?;
            prefix.extend(shape_with_fallback(run.font, fallbacks, size_pt, before));
            suffix.extend(shape_with_fallback(run.font, fallbacks, size_pt, after));
        }
        start = end;
    }
    (offset <= start).then_some((prefix, suffix))
}

/// Shape `text` against `primary` with per-glyph fallback.
///
/// Clusters containing `.notdef` are re-shaped against each fallback face. The
/// first fallback with no `.notdef` wins the whole cluster.
///
/// Returns one [`WordSubRun`] per contiguous source span that shares
/// a face. Each sub-run's `glyphs` `cluster` offsets are rebased to
/// the sub-run's local `text`, so `mos-pdf::plan_embedded` reads
/// `/ToUnicode` clusters with no awareness of the parent word.
///
/// Input is normalized through [`crate::nfc_text`] before fallback
/// shaping. Each returned [`WordSubRun::text`] is therefore a slice of
/// the normalized NFC string; decomposed caller input may not be
/// byte-identical to returned text.
///
/// Base14 `primary`: returns a single sub-run with empty `glyphs`
/// (Base14 has no glyph stream to inspect for `.notdef`; fallback
/// isn't meaningful for that path). The advance comes from the AFM
/// width sum via [`text_width`], same as the legacy `shape_text`
/// path.
///
/// All-fallback-fails behaviour: if no face in `fallbacks` covers a
/// `.notdef` cluster, the cluster stays in `primary` with `.notdef`
/// glyphs. `plan_embedded` already skips GID 0 from `gid_to_text`,
/// so copy-paste extraction is correct (empty for the un-renderable
/// span); the PDF reader renders an empty box.
///
/// # Examples
///
/// ```
/// use mos_fonts::{Base14Font, Font, shape_with_fallback};
///
/// let subruns = shape_with_fallback(Font::Base14(Base14Font::Helvetica), &[], 10.0, "A");
///
/// assert_eq!(subruns.len(), 1);
/// assert_eq!(subruns[0].text, "A");
/// ```
#[must_use]
pub fn shape_with_fallback(
    primary: Font,
    fallbacks: &[EmbeddedFontId],
    size_pt: f32,
    text: &str,
) -> Vec<WordSubRun> {
    let text = nfc_text(text);
    let text = text.as_ref();
    if text.is_empty() {
        return Vec::new();
    }

    let primary_id = match primary {
        Font::Base14(_) => {
            // Base14: no glyph stream available, fallback doesn't apply.
            return vec![WordSubRun {
                font: primary,
                text: text.to_owned(),
                glyphs: Vec::new(),
                advance_pt: text_width(primary, size_pt, text),
            }];
        }
        Font::Embedded(id) => id,
    };

    let primary_ef = primary_id.data();
    let primary_glyphs = shape(primary_ef, text);

    if primary_glyphs.iter().all(|g| g.gid != 0) || fallbacks.is_empty() {
        // No `.notdef`, OR no fallbacks configured. One sub-run.
        return vec![into_subrun(
            primary,
            text.to_owned(),
            primary_glyphs,
            primary_ef.units_per_em,
            size_pt,
        )];
    }

    // Group primary glyphs by cluster. Each cluster covers source
    // bytes `[c_n..c_{n+1})` (last cluster runs to `text.len()`).
    let clusters = glyph_clusters(&primary_glyphs, text.len());

    // Per-cluster resolution: which face owns it + which glyphs to use.
    // `glyphs` here carry `cluster` offsets into the *parent* `text`;
    // rebasing to sub-run-local offsets happens at the merge step.
    let resolutions = clusters.map(|cluster| {
        let has_notdef = cluster.glyphs.iter().any(|g| g.gid == 0);
        if !has_notdef {
            return ClusterResolution {
                font: primary,
                byte_range: cluster.byte_range,
                glyphs: Cow::Borrowed(cluster.glyphs),
            };
        }
        // Retry against each fallback. Cluster-granular: replace the
        // entire cluster's glyph slice if a fallback covers it.
        let cluster_text = &text[cluster.byte_range.clone()];
        let mut accepted: Option<(Font, Vec<ShapedGlyph>)> = None;
        for &fb_id in fallbacks {
            let fb_font = Font::Embedded(fb_id);
            let fb_ef = fb_id.data();
            let fb_glyphs = shape(fb_ef, cluster_text);
            if !fb_glyphs.is_empty() && fb_glyphs.iter().all(|g| g.gid != 0) {
                // Shift fallback glyph clusters into the parent text's
                // coordinate system; rebasing to the sub-run's local
                // text happens in the merge step.
                // `cluster.byte_range.start` is a byte offset into a `&str`
                // that's at most `text.len()` bytes long. We pipe through
                // `u32::try_from` for the lint, saturating to u32::MAX in the
                // unreachable case of source strings ≥ 4 GiB.
                let shift = u32::try_from(cluster.byte_range.start).unwrap_or(u32::MAX);
                let shifted: Vec<_> = fb_glyphs
                    .into_iter()
                    .map(|g| ShapedGlyph {
                        cluster: g.cluster + shift,
                        ..g
                    })
                    .collect();
                accepted = Some((fb_font, shifted));
                break;
            }
        }
        match accepted {
            Some((fb_font, fb_glyphs)) => ClusterResolution {
                font: fb_font,
                byte_range: cluster.byte_range,
                glyphs: Cow::Owned(fb_glyphs),
            },
            None => ClusterResolution {
                font: primary,
                byte_range: cluster.byte_range,
                glyphs: Cow::Borrowed(cluster.glyphs),
            },
        }
    });

    // Merge adjacent same-font resolutions into one sub-run apiece.
    let mut subruns: Vec<WordSubRun> = Vec::new();
    let mut current: Option<(Font, std::ops::Range<usize>, Vec<ShapedGlyph>)> = None;
    for res in resolutions {
        match current.take() {
            Some((font, range, mut glyphs)) if font == res.font => {
                let new_range = range.start..res.byte_range.end;
                glyphs.extend_from_slice(&res.glyphs);
                current = Some((font, new_range, glyphs));
            }
            Some((font, range, glyphs)) => {
                subruns.push(finalize_subrun(font, range, glyphs, text, size_pt));
                current = Some((res.font, res.byte_range, res.glyphs.into_owned()));
            }
            None => current = Some((res.font, res.byte_range, res.glyphs.into_owned())),
        }
    }
    if let Some((font, range, glyphs)) = current {
        subruns.push(finalize_subrun(font, range, glyphs, text, size_pt));
    }
    subruns
}

/// A borrowed group of consecutive glyphs sharing a source byte offset.
///
/// Glyph positions and cluster offsets remain unchanged from the input run.
#[derive(Clone, Debug)]
pub struct GlyphCluster<'a> {
    /// Source byte range, ending at the next cluster or the supplied text length.
    pub byte_range: std::ops::Range<usize>,
    /// Glyphs borrowed directly from the input, in their original order.
    pub glyphs: &'a [ShapedGlyph],
}

/// Internal: one cluster's resolution after fallback retry. `glyphs`
/// carry `cluster` offsets into the parent word text.
struct ClusterResolution<'a> {
    font: Font,
    byte_range: std::ops::Range<usize>,
    glyphs: Cow<'a, [ShapedGlyph]>,
}

/// Iterate over a left-to-right shaped glyph stream without allocating or copying glyphs.
///
/// Consecutive glyphs with equal cluster offsets form one group. Offsets must be
/// nondecreasing UTF-8 byte boundaries in the text used for shaping; `text_len`
/// must be that text's byte length. For [`shape_with_fallback`], use each
/// [`WordSubRun`]'s normalized text and local glyph stream separately.
///
/// This function only groups glyphs: it does not normalize text, validate byte
/// ranges, rebase offsets, or infer grapheme or line-break boundaries. Callers
/// accepting externally constructed glyph streams should use `str::get` to
/// validate each returned range before slicing. Descending RTL clusters are
/// not supported. Empty glyph streams yield no clusters, including Base-14 runs.
///
/// ```
/// use mos_fonts::{EmbeddedFontId, glyph_clusters, shape};
///
/// let text = "office";
/// let glyphs = shape(EmbeddedFontId::Regular.data(), text);
/// let parts: Vec<_> = glyph_clusters(&glyphs, text.len())
///     .filter_map(|cluster| text.get(cluster.byte_range))
///     .collect();
/// assert_eq!(parts.concat(), text);
/// ```
pub fn glyph_clusters(
    glyphs: &[ShapedGlyph],
    text_len: usize,
) -> impl std::iter::FusedIterator<Item = GlyphCluster<'_>> {
    let mut start = 0;
    std::iter::from_fn(move || {
        let cluster = glyphs.get(start)?.cluster;
        let mut end = start + 1;
        while glyphs
            .get(end)
            .is_some_and(|glyph| glyph.cluster == cluster)
        {
            end += 1;
        }
        let end_byte = glyphs
            .get(end)
            .map_or(text_len, |glyph| glyph.cluster as usize);
        let group = GlyphCluster {
            byte_range: cluster as usize..end_byte,
            glyphs: &glyphs[start..end],
        };
        start = end;
        Some(group)
    })
    .fuse()
}

/// Convert a `(font, byte_range, parent-relative glyphs)` triple into
/// a fully-baked [`WordSubRun`]: slices `parent_text` to the sub-run's
/// local string, rebases glyph clusters to that local string, sums
/// the advance.
fn finalize_subrun(
    font: Font,
    byte_range: std::ops::Range<usize>,
    glyphs: Vec<ShapedGlyph>,
    parent_text: &str,
    size_pt: f32,
) -> WordSubRun {
    let local_text = parent_text[byte_range.clone()].to_owned();
    // Sub-run byte ranges are bounded by the parent word's `text.len()`,
    // always well below u32::MAX in practice. Saturating cast keeps clippy
    // happy without an `#[allow]` annotation; the saturation branch is
    // unreachable for any realistic input.
    let shift = u32::try_from(byte_range.start).unwrap_or(u32::MAX);
    let rebased: Vec<_> = glyphs
        .into_iter()
        .map(|g| ShapedGlyph {
            cluster: g.cluster.saturating_sub(shift),
            ..g
        })
        .collect();
    let advance_pt: f32 = match font {
        Font::Embedded(id) => {
            let upem = embedded_upem(id);
            rebased
                .iter()
                .map(|g| advance_units_to_pt(g.advance_units, size_pt, upem))
                .sum()
        }
        Font::Base14(_) => text_width(font, size_pt, &local_text),
    };
    WordSubRun {
        font,
        text: local_text,
        glyphs: rebased,
        advance_pt,
    }
}

/// Single-sub-run packaging when no fallback retry was needed. Skips
/// the rebasing branch: the input glyphs already have cluster offsets
/// relative to `local_text` (which is the full parent text).
fn into_subrun(
    font: Font,
    text: String,
    glyphs: Vec<ShapedGlyph>,
    upem: u16,
    size_pt: f32,
) -> WordSubRun {
    let upem_f = f32::from(upem);
    let advance_pt: f32 = glyphs
        .iter()
        .map(|g| advance_units_to_pt(g.advance_units, size_pt, upem_f))
        .sum();
    WordSubRun {
        font,
        text,
        glyphs,
        advance_pt,
    }
}

/// `units_per_em` for an embedded face.
fn embedded_upem(id: EmbeddedFontId) -> f32 {
    f32::from(id.data().units_per_em)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn adjacent_fallback_clusters_merge_and_rebase() {
        let runs = shape_with_fallback(
            Font::Embedded(EmbeddedFontId::Regular),
            &[EmbeddedFontId::Math],
            11.0,
            "office⨌⨌office",
        );
        assert_eq!(runs.len(), 3);
        assert_eq!(
            runs.iter().map(|run| run.text.as_str()).collect::<Vec<_>>(),
            ["office", "⨌⨌", "office"]
        );
        assert_eq!(runs[1].font, Font::Embedded(EmbeddedFontId::Math));
        let expected = shape_with_fallback(Font::Embedded(EmbeddedFontId::Math), &[], 11.0, "⨌⨌");
        assert_eq!(runs[1].glyphs, expected[0].glyphs);
        assert_eq!(runs[1].advance_pt, expected[0].advance_pt);
        assert_eq!(runs[0].glyphs, runs[2].glyphs);
    }

    #[test]
    fn unresolved_fallback_clusters_merge_with_original_positioning() {
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let text = "officeé🎉office🎉".repeat(32);
        let expected = shape_with_fallback(primary, &[], 11.0, &text);
        let actual = shape_with_fallback(primary, &[EmbeddedFontId::Math], 11.0, &text);
        assert_eq!(actual.len(), 1);
        assert_eq!(actual[0].font, expected[0].font);
        assert_eq!(actual[0].text, expected[0].text);
        assert_eq!(actual[0].glyphs, expected[0].glyphs);
        assert_eq!(actual[0].advance_pt, expected[0].advance_pt);
    }

    #[test]
    #[allow(clippy::expect_used, reason = "test requires nonempty cluster groups")]
    fn cluster_views_borrow_glyphs_and_preserve_positioning() {
        let glyph = ShapedGlyph {
            gid: 1,
            cluster: 0,
            advance_units: -17,
            x_offset_units: 23,
            y_offset_units: -9,
        };
        let glyphs = [
            glyph,
            ShapedGlyph { gid: 2, ..glyph },
            ShapedGlyph {
                gid: 3,
                cluster: 3,
                ..glyph
            },
        ];
        let mut clusters = glyph_clusters(&glyphs, "ffié".len());
        let first = clusters.next().expect("first cluster");
        assert_eq!(first.byte_range, 0..3);
        assert!(std::ptr::eq(first.glyphs.as_ptr(), glyphs.as_ptr()));
        assert_eq!(first.glyphs, &glyphs[..2]);
        let last = clusters.next().expect("last cluster");
        assert_eq!(last.byte_range, 3..5);
        assert_eq!(last.glyphs, &glyphs[2..]);
        assert!(clusters.next().is_none());
        assert!(clusters.next().is_none());
        assert!(glyph_clusters(&[], 4).next().is_none());
    }

    #[test]
    #[allow(
        clippy::expect_used,
        reason = "test requires valid shaped source ranges"
    )]
    fn cluster_views_use_normalized_subrun_text() {
        let runs = shape_with_fallback(
            Font::Embedded(EmbeddedFontId::Regular),
            &[EmbeddedFontId::Math],
            11.0,
            "e\u{301}office⨌",
        );
        assert!(
            runs.iter()
                .any(|run| run.font == Font::Embedded(EmbeddedFontId::Math))
        );
        let mut text = String::new();
        let mut saw_ligature = false;
        for run in &runs {
            for cluster in glyph_clusters(&run.glyphs, run.text.len()) {
                let part = run
                    .text
                    .get(cluster.byte_range)
                    .expect("valid source range");
                saw_ligature |= part == "ffi";
                text.push_str(part);
            }
        }
        assert_eq!(text, "éoffice⨌");
        assert!(saw_ligature);
    }

    #[test]
    fn cluster_views_leave_external_range_validation_to_caller() {
        let glyph = ShapedGlyph {
            gid: 1,
            cluster: 1,
            advance_units: 0,
            x_offset_units: 0,
            y_offset_units: 0,
        };
        for offsets in [[1, 3], [3, 0], [0, 9]] {
            let glyphs = offsets.map(|cluster| ShapedGlyph { cluster, ..glyph });
            let clusters: Vec<_> = glyph_clusters(&glyphs, "éx".len()).collect();
            assert_eq!(clusters.len(), 2);
            assert!(
                clusters
                    .iter()
                    .any(|cluster| "éx".get(cluster.byte_range.clone()).is_none())
            );
        }
    }

    use crate::Base14Font;

    #[test]
    #[allow(clippy::expect_used, reason = "test setup and required split results")]
    fn split_runs_preserves_untouched_geometry() {
        let font = Font::Embedded(EmbeddedFontId::Regular);
        let mut runs = shape_with_fallback(font, &[EmbeddedFontId::Math], 11.0, "a⨌b");
        assert!(runs.len() >= 3);
        // Callers can adjust positioning after shaping; boundary splits must
        // retain that geometry instead of recomputing it from the text.
        runs[0].advance_pt += 0.25;
        runs[0].glyphs[0].x_offset_units += 1;
        let offset = runs[0].text.len();
        let (left, right) =
            split_runs_at(&runs, offset, 11.0, &[EmbeddedFontId::Math]).expect("run boundary");
        let joined: Vec<_> = left.into_iter().chain(right).collect();
        assert_eq!(joined.len(), runs.len());
        for (actual, expected) in joined.iter().zip(&runs) {
            assert_eq!(actual.font, expected.font);
            assert_eq!(actual.text, expected.text);
            assert_eq!(actual.glyphs, expected.glyphs);
            assert_eq!(actual.advance_pt, expected.advance_pt);
        }
        for offset in [0, "a⨌b".len()] {
            let (left, right) = split_runs_at(&runs, offset, 11.0, &[]).expect("end boundary");
            assert_eq!(left.len() + right.len(), runs.len());
            assert_eq!(left.is_empty(), offset == 0);
            assert_eq!(right.is_empty(), offset != 0);
        }
    }

    #[test]
    #[allow(clippy::expect_used, reason = "test setup and required split results")]
    fn split_runs_reshapes_a_cut_ligature() {
        let font = Font::Embedded(EmbeddedFontId::Regular);
        let runs = shape_with_fallback(font, &[], 12.0, "office");
        assert!(runs.iter().map(|run| run.glyphs.len()).sum::<usize>() < 6);
        let (left, right) = split_runs_at(&runs, 2, 12.0, &[]).expect("inside ffi ligature");
        for (actual, text) in [(&left, "of"), (&right, "fice")] {
            let expected = shape_with_fallback(font, &[], 12.0, text);
            assert_eq!(actual.len(), expected.len());
            for (actual, expected) in actual.iter().zip(&expected) {
                assert_eq!(actual.text, expected.text);
                assert_eq!(actual.glyphs, expected.glyphs);
                assert_eq!(actual.advance_pt, expected.advance_pt);
            }
        }
    }

    #[test]
    #[allow(clippy::expect_used, reason = "required split results")]
    fn split_runs_checks_offsets_in_normalized_text() {
        let runs = shape_with_fallback(
            Font::Embedded(EmbeddedFontId::Regular),
            &[],
            12.0,
            "e\u{301}x",
        );
        assert_eq!(runs[0].text, "éx");
        assert!(split_runs_at(&runs, 1, 12.0, &[]).is_none());
        assert!(split_runs_at(&runs, 4, 12.0, &[]).is_none());
        assert!(split_runs_at(&runs, usize::MAX, 12.0, &[]).is_none());
        let (left, right) = split_runs_at(&runs, 2, 12.0, &[]).expect("normalized boundary");
        assert_eq!(left[0].text, "é");
        assert_eq!(right[0].text, "x");
        let (left, right) = split_runs_at(&[], 0, 12.0, &[]).expect("empty boundary");
        assert!(left.is_empty() && right.is_empty());
        assert!(split_runs_at(&[], 1, 12.0, &[]).is_none());
    }

    #[test]
    fn embedded_shape_is_empty_for_empty_string() {
        let ef = EmbeddedFontId::Regular.data();
        let glyphs = shape(ef, "");
        assert!(glyphs.is_empty());
    }

    #[test]
    fn embedded_shape_returns_clusters_in_byte_order() {
        let ef = EmbeddedFontId::Regular.data();
        let glyphs = shape(ef, "Привет");
        assert!(!glyphs.is_empty());
        // Cluster values are byte offsets into the source string and
        // must be monotonically non-decreasing for LTR text.
        let mut prev: u32 = 0;
        for g in &glyphs {
            assert!(
                g.cluster >= prev,
                "cluster regression: {prev} -> {}",
                g.cluster
            );
            prev = g.cluster;
        }
    }

    #[test]
    fn embedded_shape_preserves_gpos_kerning() {
        let ef = EmbeddedFontId::Regular.data();
        let glyphs = shape(ef, "AV");
        assert!(!glyphs.is_empty());
        let nominal: i32 = glyphs
            .iter()
            .map(|g| i32::from(ef.advance_units(g.gid)))
            .sum();
        let shaped: i32 = glyphs.iter().map(|g| g.advance_units).sum();

        assert!(
            shaped < nominal,
            "expected AV kerning to tighten advance: shaped={shaped} nominal={nominal}"
        );
    }

    #[test]
    fn embedded_shape_preserves_combining_mark_offsets() {
        let ef = EmbeddedFontId::Regular.data();
        let glyphs = shape(ef, "q\u{0302}\u{0301}");
        assert!(
            glyphs.len() >= 3,
            "expected base 'q' + 2 combining marks, got {glyphs:?}"
        );
        assert!(
            glyphs[1..]
                .iter()
                .any(|g| g.x_offset_units != 0 || g.y_offset_units != 0),
            "expected at least one combining mark offset, got {glyphs:?}"
        );
    }

    #[test]
    fn shape_text_normalizes_decomposed_romanian() {
        let font = Font::Embedded(EmbeddedFontId::Regular);
        let decomposed = shape_text(font, 12.0, "S\u{0326}");
        let precomposed = shape_text(font, 12.0, "\u{0218}");

        let decomposed_gids: Vec<u16> = decomposed.glyphs.iter().map(|g| g.gid).collect();
        let precomposed_gids: Vec<u16> = precomposed.glyphs.iter().map(|g| g.gid).collect();
        assert_eq!(decomposed_gids, precomposed_gids);
        assert!((decomposed.advance_pt - precomposed.advance_pt).abs() < f32::EPSILON);
    }

    #[test]
    fn embedded_fi_ligature_collapses_glyphs() {
        // Noto Sans contains an `fi` ligature; rustybuzz returns one
        // glyph for `fi` (not two). The substituted gid differs from
        // both the standalone `f` and `i` gids. (Noto Sans's `fi`
        // ligature has the same advance as f+i: purely visual,
        // joining the dot of `i` with the terminal of `f`, so width
        // is not a useful invariant for this font.)
        let ef = EmbeddedFontId::Regular.data();
        let fi = shape(ef, "fi");
        let f = shape(ef, "f");
        let i = shape(ef, "i");
        assert_eq!(fi.len(), 1, "expected fi ligature, got glyphs {fi:?}");
        assert_ne!(fi[0].gid, f[0].gid);
        assert_ne!(fi[0].gid, i[0].gid);
    }

    #[test]
    fn fallback_empty_text_returns_empty() {
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let fallbacks = &[EmbeddedFontId::Math];
        assert!(shape_with_fallback(primary, fallbacks, 11.0, "").is_empty());
    }

    #[test]
    fn fallback_pure_primary_returns_single_subrun() {
        // Pure ASCII is fully covered by Noto Sans Regular: no
        // fallback needed; one sub-run, primary-owned glyphs.
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let fallbacks = &[EmbeddedFontId::Math];
        let subs = shape_with_fallback(primary, fallbacks, 11.0, "Hello");
        assert_eq!(subs.len(), 1, "expected one sub-run, got {}", subs.len());
        assert_eq!(subs[0].font, primary);
        assert_eq!(subs[0].text, "Hello");
        assert!(!subs[0].glyphs.is_empty());
        assert!(subs[0].glyphs.iter().all(|g| g.gid != 0));
        assert!(subs[0].advance_pt > 0.0);
    }

    #[test]
    fn fallback_shape_normalizes_subrun_text() {
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let fallbacks = &[EmbeddedFontId::Math];
        let subs = shape_with_fallback(primary, fallbacks, 11.0, "S\u{0326}");

        assert_eq!(subs.len(), 1);
        assert_eq!(subs[0].text, "\u{0218}");
    }

    #[test]
    fn fallback_mixed_latin_and_math_produces_alternating_subruns() {
        // `a≤b`: Latin `a` covered by Regular, math `≤` (U+2264) needs
        // the Math fallback, Latin `b` covered by Regular again. Expect
        // three sub-runs in source order. Each sub-run's text is its
        // own slice; glyph clusters rebased to local text.
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let fallbacks = &[EmbeddedFontId::Math];
        let subs = shape_with_fallback(primary, fallbacks, 11.0, "a\u{2264}b");
        assert_eq!(subs.len(), 3, "expected 3 sub-runs, got {subs:?}");

        assert_eq!(subs[0].font, primary);
        assert_eq!(subs[0].text, "a");

        assert_eq!(subs[1].font, Font::Embedded(EmbeddedFontId::Math));
        assert_eq!(subs[1].text, "\u{2264}");
        // Math sub-run glyph clusters must be local: cluster 0 points
        // at the start of "≤", not at offset 1 in the parent word.
        assert!(
            subs[1]
                .glyphs
                .iter()
                .all(|g| (g.cluster as usize) < subs[1].text.len()),
            "math sub-run glyph clusters not rebased: {:?}",
            subs[1].glyphs,
        );

        assert_eq!(subs[2].font, primary);
        assert_eq!(subs[2].text, "b");
    }

    #[test]
    fn fallback_all_fail_keeps_primary_notdef() {
        // Emoji 🎉 (U+1F389) is not in Noto Sans Regular OR Math.
        // The cluster stays with primary as `.notdef`; no panic, no
        // duplication, copy-paste yields the source codepoint via the
        // existing `/ToUnicode` machinery (PDF reader paints empty box).
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let fallbacks = &[EmbeddedFontId::Math];
        let subs = shape_with_fallback(primary, fallbacks, 11.0, "\u{1F389}");
        assert_eq!(subs.len(), 1);
        assert_eq!(subs[0].font, primary);
        assert!(
            subs[0].glyphs.iter().any(|g| g.gid == 0),
            "expected .notdef for unsupported emoji, got {:?}",
            subs[0].glyphs,
        );
    }

    #[test]
    fn fallback_base14_primary_returns_empty_glyphs_subrun() {
        // Base14 has no glyph stream to inspect for `.notdef`; fallback
        // doesn't apply. One sub-run, empty glyphs, advance via the
        // AFM `text_width` path.
        let primary = Font::Base14(Base14Font::Helvetica);
        let fallbacks = &[EmbeddedFontId::Math];
        let subs = shape_with_fallback(primary, fallbacks, 11.0, "Hello");
        assert_eq!(subs.len(), 1);
        assert_eq!(subs[0].font, primary);
        assert!(subs[0].glyphs.is_empty());
        assert!(subs[0].advance_pt > 0.0);
    }

    #[test]
    fn fallback_no_fallbacks_configured_returns_single_subrun_even_with_notdef() {
        // Empty fallback chain: even if the primary has .notdef, we
        // produce one sub-run with whatever the primary shaped. PDF
        // reader paints empty boxes; no panic.
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let subs = shape_with_fallback(primary, &[], 11.0, "\u{2264}");
        assert_eq!(subs.len(), 1);
        assert_eq!(subs[0].font, primary);
    }

    #[test]
    fn fallback_math_subrun_advance_uses_math_face_upem() {
        // Sanity: the math sub-run's `advance_pt` is computed from
        // Math's `units_per_em`, not Regular's. Both happen to be
        // 1000 in Noto Sans, but the contract should hold regardless.
        let primary = Font::Embedded(EmbeddedFontId::Regular);
        let fallbacks = &[EmbeddedFontId::Math];
        let subs = shape_with_fallback(primary, fallbacks, 11.0, "\u{2264}");
        assert_eq!(subs.len(), 1);
        assert_eq!(subs[0].font, Font::Embedded(EmbeddedFontId::Math));
        assert!(subs[0].advance_pt > 0.0);
    }
}