Skip to main content

text_typeset/shaping/
shaper.rs

1use harfrust::{Buffer, Direction, Feature, ShapeOptions, ShaperFont, Tag};
2
3use crate::font::color::{GlyphPaint, glyph_paint};
4use crate::font::registry::FontRegistry;
5use crate::font::resolve::{
6    FaceStyle, Presentation, ResolvedFont, face_covers, find_fallback_face,
7};
8use crate::font::script_fallback::{ScriptContext, preferred_families};
9use crate::font::synthesis;
10use crate::shaping::emoji;
11use crate::shaping::run::{ShapedGlyph, ShapedRun};
12use crate::types::FontFaceId;
13use crate::types::FontFeature;
14
15/// Convert public [`FontFeature`] toggles into harfrust [`Feature`]s,
16/// applied across the whole shaped string (global range). Script-mandated
17/// features apply regardless; these are the discretionary toggles.
18pub fn to_harfrust_features(features: &[FontFeature]) -> Vec<Feature> {
19    features
20        .iter()
21        .map(|f| Feature::new(Tag::new(&f.tag), f.value, ..))
22        .collect()
23}
24
25/// Read units-per-em for a font face.
26///
27/// `harfrust::FontRef` is a thin wrapper over read-fonts and exposes
28/// the `head` table only through the `read_fonts::TableProvider` trait,
29/// which harfrust doesn't re-export. Since we already depend on swash
30/// for `font_metrics_px` further down, we reuse swash's `Metrics` to
31/// pull UPEM — one less dependency surface to maintain.
32fn units_per_em(bytes: &[u8], face_index: u32) -> Option<u16> {
33    let font_ref = swash::FontRef::from_index(bytes, face_index as usize)?;
34    let upem = font_ref.metrics(&[]).units_per_em;
35    if upem == 0 { None } else { Some(upem) }
36}
37
38/// Text direction for shaping.
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
40pub enum TextDirection {
41    /// Auto-detect from text content (default).
42    #[default]
43    Auto,
44    LeftToRight,
45    RightToLeft,
46}
47
48/// Shape a text string with the given resolved font.
49///
50/// Returns a ShapedRun with glyph IDs and pixel-space positions.
51/// The `text_offset` is the byte offset of this text within the block
52/// (used for cluster mapping back to document positions).
53/// Shape a text string with automatic glyph fallback.
54///
55/// After shaping with the primary font, any .notdef glyphs (glyph_id==0)
56/// are detected and re-shaped with fallback fonts. If no fallback font
57/// covers a character, it remains as .notdef (renders as blank space
58/// with correct advance).
59pub fn shape_text(
60    registry: &FontRegistry,
61    resolved: &ResolvedFont,
62    text: &str,
63    text_offset: usize,
64) -> Option<ShapedRun> {
65    shape_text_with_fallback(
66        registry,
67        resolved,
68        text,
69        text_offset,
70        TextDirection::Auto,
71        &[],
72    )
73}
74
75/// Shape text with an explicit direction and glyph fallback.
76///
77/// Like `shape_text`, but caller supplies the direction instead of letting
78/// rustybuzz guess. Used by the bidi-aware layout path, which splits text
79/// into directional runs before shaping.
80pub fn shape_text_with_fallback(
81    registry: &FontRegistry,
82    resolved: &ResolvedFont,
83    text: &str,
84    text_offset: usize,
85    direction: TextDirection,
86    features: &[Feature],
87) -> Option<ShapedRun> {
88    shape_text_in_paragraph(
89        registry,
90        resolved,
91        text,
92        text_offset,
93        direction,
94        features,
95        &ScriptContext::new(text, None),
96        0,
97    )
98}
99
100/// [`shape_text_with_fallback`] for text that is part of a paragraph: the
101/// paragraph and the language its block is in (`context`), and the byte
102/// where `text` starts in the paragraph (`para_pos`), decide which faces
103/// fallback prefers for Han (see [`crate::font::script_fallback`]).
104#[allow(clippy::too_many_arguments)]
105pub(crate) fn shape_text_in_paragraph(
106    registry: &FontRegistry,
107    resolved: &ResolvedFont,
108    text: &str,
109    text_offset: usize,
110    direction: TextDirection,
111    features: &[Feature],
112    context: &ScriptContext<'_>,
113    para_pos: usize,
114) -> Option<ShapedRun> {
115    let mut run = shape_text_directed(registry, resolved, text, text_offset, direction, features)?;
116    blank_hard_breaks(text, &mut run);
117
118    // Look for another face for every glyph the primary font lacks (a hard
119    // break is glyph 0 on purpose and needs none) and every emoji it does not
120    // draw in colour.
121    let may_need = run.glyphs.iter().any(|g| g.glyph_id == 0) || emoji::may_contain_emoji(text);
122    let needs = if may_need {
123        fallback_needs(registry, text, &run)
124    } else {
125        Vec::new()
126    };
127    if needs.iter().any(|n| n.needed) {
128        let style = FaceStyle::of_face(registry, resolved.font_face_id, resolved.weight);
129        apply_glyph_fallback(
130            registry,
131            resolved,
132            style,
133            text,
134            text_offset,
135            features,
136            &mut run,
137            &needs,
138            &[resolved.font_face_id],
139            context,
140            para_pos,
141            0,
142        );
143        // A break beside a character the primary font lacks is re-shaped with
144        // it, in a font that may well draw it.
145        blank_hard_breaks(text, &mut run);
146    }
147
148    Some(run)
149}
150
151/// Whether `glyph` stands for a hard line break of `text`, the text its run was shaped
152/// from.
153fn is_hard_break_glyph(text: &str, glyph: &ShapedGlyph) -> bool {
154    text.get(glyph.cluster as usize..)
155        .and_then(|rest| rest.chars().next())
156        .is_some_and(crate::types::is_hard_break)
157}
158
159/// Lay out every hard line break in `run` as nothing: glyph 0, which is never
160/// drawn, with no advance and no offset (see [`crate::types::is_hard_break`]).
161/// Returns how many there are.
162///
163/// A font draws a line separator as it likes (a box, a pilcrow) or not at all,
164/// and gives it whatever advance it likes, which pushed a right-aligned or
165/// centred line off its place by that much.
166fn blank_hard_breaks(text: &str, run: &mut ShapedRun) -> usize {
167    let mut count = 0;
168    for glyph in &mut run.glyphs {
169        if is_hard_break_glyph(text, glyph) {
170            glyph.glyph_id = 0;
171            glyph.x_advance = 0.0;
172            glyph.x_offset = 0.0;
173            glyph.y_offset = 0.0;
174            count += 1;
175        }
176    }
177    if count > 0 {
178        run.advance_width = run.glyphs.iter().map(|g| g.x_advance).sum();
179    }
180    count
181}
182
183/// How deep fallback goes: the part of a span its fallback face does not
184/// draw is handed to another face, and what that one cannot draw to another,
185/// each time with every face tried so far left out. A span of one script
186/// takes one face and a mixed one (Han then Hangul, say) a second; the cap
187/// only bounds a pathological font set.
188const MAX_FALLBACK_DEPTH: usize = 6;
189
190/// What fallback makes of one glyph of a shaped run.
191#[derive(Debug, Clone, Copy)]
192struct FallbackNeed {
193    /// Whether another face is looked for.
194    needed: bool,
195    /// Whether the glyph has no glyph at all (`.notdef`), as against one that
196    /// is drawn but not as it should be (an emoji drawn in monochrome).
197    missing: bool,
198    /// Whether the glyph's cluster asks for emoji presentation.
199    emoji: bool,
200}
201
202/// Decide, glyph by glyph, which glyphs of `run` (shaped from `text`) want
203/// another face: those with no glyph, and those of an emoji cluster drawn
204/// in anything but colour. A hard break needs none.
205fn fallback_needs(registry: &FontRegistry, text: &str, run: &ShapedRun) -> Vec<FallbackNeed> {
206    let emoji = emoji_clusters(text, &run.glyphs);
207    run.glyphs
208        .iter()
209        .zip(emoji)
210        .map(|(glyph, emoji)| {
211            if is_hard_break_glyph(text, glyph) {
212                return FallbackNeed {
213                    needed: false,
214                    missing: false,
215                    emoji,
216                };
217            }
218            let missing = glyph.glyph_id == 0;
219            let not_in_color = emoji
220                && !missing
221                && registry
222                    .get(glyph.font_face_id)
223                    .is_some_and(|entry| glyph_paint(entry, glyph.glyph_id) != GlyphPaint::Color);
224            FallbackNeed {
225                needed: missing || not_in_color,
226                missing,
227                emoji,
228            }
229        })
230        .collect()
231}
232
233/// For each glyph of `glyphs` (shaped from `text`), whether its cluster asks
234/// for emoji presentation (see [`crate::shaping::emoji`]).
235fn emoji_clusters(text: &str, glyphs: &[ShapedGlyph]) -> Vec<bool> {
236    if !emoji::may_contain_emoji(text) {
237        return vec![false; glyphs.len()];
238    }
239    // A cluster runs from its own start to the next start in the text, which
240    // works for an RTL run too, whose glyphs carry descending clusters.
241    let mut starts: Vec<usize> = glyphs.iter().map(|g| g.cluster as usize).collect();
242    starts.sort_unstable();
243    starts.dedup();
244    glyphs
245        .iter()
246        .map(|g| {
247            let start = g.cluster as usize;
248            let end = match starts.binary_search(&start) {
249                Ok(i) => starts.get(i + 1).copied().unwrap_or(text.len()),
250                Err(_) => text.len(),
251            };
252            text.get(start..end).is_some_and(emoji::cluster_wants_emoji)
253        })
254        .collect()
255}
256
257/// Re-shape the glyphs of `run` that need another face in fallback fonts.
258///
259/// Works on **spans** of consecutive glyphs that need one, not on glyphs one
260/// at a time: each span is mapped back to the character range that produced
261/// it and that whole range is re-shaped in the fallback font, then spliced
262/// in.
263///
264/// Shaping a span as a unit is what makes complex scripts survive fallback.
265/// Re-shaping character by character, which this used to do, cannot join
266/// Arabic, because a letter shaped alone has no neighbours and can only take
267/// its isolated form. It also kept only the *first* glyph of each result, so
268/// any letter whose isolated form is a base plus a mark lost the mark. An
269/// Arabic word set in a font without Arabic came out as disconnected,
270/// dotless stumps.
271///
272/// A span is cut where emoji presentation starts or stops, so that an emoji
273/// after CJK text gets a face of its own rather than the CJK font's
274/// `.notdef`. The span is re-shaped in the face found for its first
275/// character, and whatever that face does not draw goes through the same
276/// steps again, with every face tried so far left out: before, a span was
277/// shaped in one face and what that face lacked stayed blank. When the face
278/// found for the first character a span's face lacks draws the whole span,
279/// the span is set in that face instead, so that a word is not split
280/// between two CJK fonts of different designs.
281///
282/// Every face is chosen to match `style`, the weight, style and width of the
283/// text (see [`find_fallback_face`]), and for kana, hangul and Han among the
284/// faces the system ships for their language first, which for Han is found
285/// in `context`, the paragraph `text` starts at byte `para_pos` of (see
286/// [`crate::font::script_fallback`]).
287///
288/// A span is re-shaped with the run's own direction rather than `Auto`, so
289/// the substituted glyphs come back in the same visual order as the ones
290/// around them.
291#[allow(clippy::too_many_arguments)]
292fn apply_glyph_fallback(
293    registry: &FontRegistry,
294    primary: &ResolvedFont,
295    style: FaceStyle,
296    text: &str,
297    text_offset: usize,
298    features: &[Feature],
299    run: &mut ShapedRun,
300    needs: &[FallbackNeed],
301    tried: &[FontFaceId],
302    context: &ScriptContext<'_>,
303    para_pos: usize,
304    depth: usize,
305) {
306    // The faces the fallback table prefers for the character at byte `at` of
307    // `text`.
308    let preferred = |ch: char, at: usize| {
309        preferred_families(
310            ch,
311            context,
312            para_pos + at,
313            registry.default_language(),
314            registry.fallback_platform(),
315        )
316    };
317    // Maximal spans of consecutive glyphs that need a face, cut where emoji
318    // presentation changes. A hard break needs none and so ends a span:
319    // inside one it would choose the span's font, since a span is re-shaped
320    // in the font that draws its first character, and a character beside it
321    // would lose its own.
322    let mut spans: Vec<(std::ops::Range<usize>, bool)> = Vec::new();
323    let mut i = 0;
324    while i < needs.len() {
325        if !needs[i].needed {
326            i += 1;
327            continue;
328        }
329        let start = i;
330        let emoji = needs[i].emoji;
331        while i < needs.len() && needs[i].needed && needs[i].emoji == emoji {
332            i += 1;
333        }
334        spans.push((start..i, emoji));
335    }
336    if spans.is_empty() {
337        return;
338    }
339
340    // Splice from the back so earlier ranges stay valid as lengths change.
341    for (span, emoji) in spans.into_iter().rev() {
342        let any_missing = needs[span.clone()].iter().any(|n| n.missing);
343        let Some((byte_start, byte_end)) = span_char_range(&run.glyphs, &span, text) else {
344            continue;
345        };
346        let Some(slice) = text.get(byte_start..byte_end) else {
347            continue;
348        };
349        let Some(first_char) = slice.chars().next() else {
350            continue;
351        };
352
353        // An emoji drawn in monochrome is left out with the faces tried
354        // already, so the search is for a face that draws it otherwise.
355        let mut excluded: Vec<FontFaceId> = tried.to_vec();
356        for glyph in &run.glyphs[span.clone()] {
357            if !excluded.contains(&glyph.font_face_id) {
358                excluded.push(glyph.font_face_id);
359            }
360        }
361        let presentation = if emoji {
362            Presentation::Emoji
363        } else {
364            Presentation::Text
365        };
366        let Some((mut fallback_id, paint)) = find_fallback_face(
367            registry,
368            first_char,
369            presentation,
370            style,
371            &excluded,
372            preferred(first_char, byte_start),
373        ) else {
374            continue; // no fallback available: leave the span as it is
375        };
376        // An emoji already drawn, if in monochrome, is only worth replacing
377        // by one drawn in colour.
378        if emoji && !any_missing && paint != GlyphPaint::Color {
379            continue;
380        }
381
382        let reshape = |face: FontFaceId| -> Option<(ResolvedFont, ShapedRun)> {
383            let entry = registry.get(face)?;
384            let resolved = ResolvedFont {
385                font_face_id: face,
386                size_px: primary.size_px,
387                face_index: entry.face_index,
388                swash_cache_key: entry.swash_cache_key,
389                scale_factor: primary.scale_factor,
390                weight: primary.weight,
391                italic: primary.italic,
392            };
393            // Clusters come back local to `slice`.
394            let run = shape_text_directed(
395                registry,
396                &resolved,
397                slice,
398                text_offset + byte_start,
399                run.direction,
400                features,
401            )?;
402            (!run.glyphs.is_empty()).then_some((resolved, run))
403        };
404        let Some((mut fallback_resolved, mut fallback_run)) = reshape(fallback_id) else {
405            continue;
406        };
407        blank_hard_breaks(slice, &mut fallback_run);
408
409        excluded.push(fallback_id);
410        let mut still = fallback_needs(registry, slice, &fallback_run);
411        if !emoji
412            && let Some((at, lacking)) = fallback_run
413                .glyphs
414                .iter()
415                .zip(&still)
416                .find(|(_, n)| n.missing)
417                .and_then(|(g, _)| {
418                    let at = g.cluster as usize;
419                    Some((at, slice.get(at..)?.chars().next()?))
420                })
421            && let Some((whole_id, _)) = find_fallback_face(
422                registry,
423                lacking,
424                Presentation::Text,
425                style,
426                &excluded,
427                preferred(lacking, byte_start + at),
428            )
429            && face_covers(registry, whole_id, slice)
430            && let Some((resolved, mut whole_run)) = reshape(whole_id)
431        {
432            blank_hard_breaks(slice, &mut whole_run);
433            fallback_id = whole_id;
434            fallback_resolved = resolved;
435            fallback_run = whole_run;
436            excluded.push(fallback_id);
437            still = fallback_needs(registry, slice, &fallback_run);
438        }
439
440        if depth < MAX_FALLBACK_DEPTH && still.iter().any(|n| n.needed) {
441            apply_glyph_fallback(
442                registry,
443                &fallback_resolved,
444                style,
445                slice,
446                text_offset + byte_start,
447                features,
448                &mut fallback_run,
449                &still,
450                &excluded,
451                context,
452                para_pos + byte_start,
453                depth + 1,
454            );
455        }
456
457        // Lift the clusters from `slice` into `text` space, which is what the
458        // rest of the pipeline expects of this run. Each glyph keeps the face
459        // it was shaped in, which deeper fallback may have changed.
460        let replacement: Vec<ShapedGlyph> = fallback_run
461            .glyphs
462            .into_iter()
463            .map(|mut g| {
464                g.cluster += byte_start as u32;
465                g
466            })
467            .collect();
468
469        run.glyphs.splice(span, replacement);
470    }
471
472    run.advance_width = run.glyphs.iter().map(|g| g.x_advance).sum();
473}
474
475/// The byte range of `text` that a span of consecutive glyphs covers.
476///
477/// Glyphs sit in visual order, so clusters ascend across an LTR run and
478/// descend across an RTL one. Taking the min and max over the span rather
479/// than its first and last glyph keeps this direction-agnostic.
480///
481/// The span's end is the nearest cluster *after* it among the glyphs outside
482/// it (the start of whatever follows it in the text), or the end of the text
483/// when the span runs to the edge.
484fn span_char_range(
485    glyphs: &[ShapedGlyph],
486    span: &std::ops::Range<usize>,
487    text: &str,
488) -> Option<(usize, usize)> {
489    let inside = glyphs.get(span.clone())?;
490    let start = inside.iter().map(|g| g.cluster as usize).min()?;
491    let last = inside.iter().map(|g| g.cluster as usize).max()?;
492
493    let end = glyphs
494        .iter()
495        .enumerate()
496        .filter(|(i, _)| !span.contains(i))
497        .map(|(_, g)| g.cluster as usize)
498        .filter(|&c| c > last)
499        .min()
500        .unwrap_or(text.len());
501
502    if start >= end || !text.is_char_boundary(start) || !text.is_char_boundary(end) {
503        return None;
504    }
505    Some((start, end))
506}
507
508/// Shape text with an explicit direction.
509pub fn shape_text_directed(
510    registry: &FontRegistry,
511    resolved: &ResolvedFont,
512    text: &str,
513    text_offset: usize,
514    direction: TextDirection,
515    features: &[Feature],
516) -> Option<ShapedRun> {
517    let entry = registry.get(resolved.font_face_id)?;
518    let font = entry.shaping_font()?;
519
520    let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
521    if upem == 0.0 {
522        return None;
523    }
524    // Shape at physical ppem, then divide results by scale_factor so
525    // downstream layout stays in logical pixels. See ResolvedFont.
526    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
527    let physical_size = resolved.size_px * sf;
528    let physical_scale = physical_size / upem;
529    let inv_sf = 1.0 / sf;
530
531    let mut buffer = Buffer::new();
532    buffer.push_str(text);
533    match direction {
534        TextDirection::LeftToRight => buffer.set_direction(Direction::LeftToRight),
535        TextDirection::RightToLeft => buffer.set_direction(Direction::RightToLeft),
536        TextDirection::Auto => {}
537    }
538    // Always guess, including after an explicit set_direction. The guess
539    // only fills in what is still unset — it assigns `script` when it is
540    // `None` and `direction` when it is `Invalid` — so the caller's
541    // direction survives untouched and the script gets populated.
542    //
543    // That script is what picks the shaper: with `script: None` harfrust
544    // falls back to DEFAULT_SHAPER, which never requests init/medi/fina/
545    // isol, and Arabic comes out in disconnected isolated forms. Setting
546    // it selects ARABIC_SHAPER and the letters join. It also keeps
547    // harfrust from panicking on a still-Invalid direction in the Auto
548    // case, which is why this call used to live in that branch alone.
549    buffer.guess_segment_properties();
550
551    // Resolve the concrete direction (Auto is now decided by the buffer).
552    // Stored on the run so hit-testing knows RTL glyph order.
553    let resolved_direction = if buffer.direction() == Direction::RightToLeft {
554        TextDirection::RightToLeft
555    } else {
556        TextDirection::LeftToRight
557    };
558
559    // The font is opened once per face and cached on the FontEntry, and
560    // it keeps its preprocessed tables, so repeated shape calls (every
561    // relayout/keystroke) reuse them; the ShaperFont over it is cheap.
562    harfrust::shape(
563        &ShaperFont::new(font),
564        &mut buffer,
565        ShapeOptions::new().features(features),
566    )
567    .ok()?;
568
569    let infos = buffer.glyph_infos();
570    let positions = buffer.glyph_positions();
571
572    let mut glyphs = Vec::with_capacity(infos.len());
573    let mut total_advance = 0.0f32;
574
575    for (info, pos) in infos.iter().zip(positions.iter()) {
576        let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
577        let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
578        let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
579        let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
580
581        glyphs.push(ShapedGlyph {
582            glyph_id: info.glyph_id as u16,
583            cluster: info.cluster,
584            x_advance,
585            y_advance,
586            x_offset,
587            y_offset,
588            font_face_id: resolved.font_face_id,
589        });
590
591        total_advance += x_advance;
592    }
593    if entry.synthesis().synthesizes_bold(resolved.weight) {
594        total_advance = widen_for_synthetic_bold(&mut glyphs, resolved.size_px);
595    }
596
597    Some(ShapedRun {
598        font_face_id: resolved.font_face_id,
599        size_px: resolved.size_px,
600        weight: resolved.weight,
601        italic: resolved.italic,
602        glyphs,
603        advance_width: total_advance,
604        text_range: text_offset..text_offset + text.len(),
605        direction: resolved_direction,
606        bidi_level: if resolved_direction == TextDirection::RightToLeft {
607            1
608        } else {
609            0
610        },
611        underline_style: crate::types::UnderlineStyle::None,
612        overline: false,
613        strikeout: false,
614        is_link: false,
615        foreground_color: None,
616        underline_color: None,
617        background_color: None,
618        anchor_href: None,
619        tooltip: None,
620        vertical_alignment: crate::types::VerticalAlignment::Normal,
621        image_name: None,
622        image_height: 0.0,
623    })
624}
625
626/// Shape a text string, reusing a harfrust `Buffer` to avoid allocations.
627pub fn shape_text_with_buffer(
628    registry: &FontRegistry,
629    resolved: &ResolvedFont,
630    text: &str,
631    text_offset: usize,
632    buffer: Buffer,
633    features: &[Feature],
634) -> Option<(ShapedRun, Buffer)> {
635    let entry = registry.get(resolved.font_face_id)?;
636    let font = entry.shaping_font()?;
637
638    let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
639    if upem == 0.0 {
640        return None;
641    }
642    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
643    let physical_size = resolved.size_px * sf;
644    let physical_scale = physical_size / upem;
645    let inv_sf = 1.0 / sf;
646
647    let mut buffer = buffer;
648    buffer.push_str(text);
649    // Recycled buffers come back without segment properties; explicitly
650    // guess them so harfrust doesn't panic on Direction::Invalid.
651    buffer.guess_segment_properties();
652
653    let resolved_direction = if buffer.direction() == Direction::RightToLeft {
654        TextDirection::RightToLeft
655    } else {
656        TextDirection::LeftToRight
657    };
658
659    harfrust::shape(
660        &ShaperFont::new(font),
661        &mut buffer,
662        ShapeOptions::new().features(features),
663    )
664    .ok()?;
665
666    let infos = buffer.glyph_infos();
667    let positions = buffer.glyph_positions();
668
669    let mut glyphs = Vec::with_capacity(infos.len());
670    let mut total_advance = 0.0f32;
671
672    for (info, pos) in infos.iter().zip(positions.iter()) {
673        let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
674        let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
675        let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
676        let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
677
678        glyphs.push(ShapedGlyph {
679            glyph_id: info.glyph_id as u16,
680            cluster: info.cluster,
681            x_advance,
682            y_advance,
683            x_offset,
684            y_offset,
685            font_face_id: resolved.font_face_id,
686        });
687
688        total_advance += x_advance;
689    }
690    if entry.synthesis().synthesizes_bold(resolved.weight) {
691        total_advance = widen_for_synthetic_bold(&mut glyphs, resolved.size_px);
692    }
693
694    let run = ShapedRun {
695        font_face_id: resolved.font_face_id,
696        size_px: resolved.size_px,
697        weight: resolved.weight,
698        italic: resolved.italic,
699        glyphs,
700        advance_width: total_advance,
701        text_range: text_offset..text_offset + text.len(),
702        direction: resolved_direction,
703        bidi_level: if resolved_direction == TextDirection::RightToLeft {
704            1
705        } else {
706            0
707        },
708        underline_style: crate::types::UnderlineStyle::None,
709        overline: false,
710        strikeout: false,
711        is_link: false,
712        foreground_color: None,
713        underline_color: None,
714        background_color: None,
715        anchor_href: None,
716        tooltip: None,
717        vertical_alignment: crate::types::VerticalAlignment::Normal,
718        image_name: None,
719        image_height: 0.0,
720    };
721    let mut run = run;
722    blank_hard_breaks(text, &mut run);
723
724    // Reclaim the buffer for reuse: clearing keeps the allocation and
725    // drops the contents and segment properties.
726    buffer.clear();
727    Some((run, buffer))
728}
729
730/// Widen every advancing glyph by what synthetic bold adds to its outline
731/// (see [`crate::font::synthesis`]), so the layout, the caret and hit testing
732/// measure the glyph as the rasterizer draws it. Returns the run's new
733/// advance.
734fn widen_for_synthetic_bold(glyphs: &mut [ShapedGlyph], size_px: f32) -> f32 {
735    let extra = synthesis::embolden_strength(size_px);
736    for glyph in glyphs.iter_mut().filter(|g| g.x_advance > 0.0) {
737        glyph.x_advance += extra;
738    }
739    glyphs.iter().map(|g| g.x_advance).sum()
740}
741
742#[non_exhaustive]
743pub struct FontMetricsPx {
744    pub ascent: f32,
745    pub descent: f32,
746    pub leading: f32,
747    pub underline_offset: f32,
748    pub strikeout_offset: f32,
749    pub stroke_size: f32,
750}
751
752/// Get font metrics (ascent, descent, leading) scaled to logical pixels.
753///
754/// Scales at `size_px * scale_factor` (physical) and divides by
755/// `scale_factor`, so callers always see logical-pixel metrics.
756pub fn font_metrics_px(registry: &FontRegistry, resolved: &ResolvedFont) -> Option<FontMetricsPx> {
757    let entry = registry.get(resolved.font_face_id)?;
758    let font_ref = swash::FontRef::from_index(entry.bytes(), entry.face_index as usize)?;
759    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
760    let physical_size = resolved.size_px * sf;
761    let metrics = font_ref.metrics(&[]).scale(physical_size);
762    let inv_sf = 1.0 / sf;
763
764    Some(FontMetricsPx {
765        ascent: metrics.ascent * inv_sf,
766        descent: metrics.descent * inv_sf,
767        leading: metrics.leading * inv_sf,
768        underline_offset: metrics.underline_offset * inv_sf,
769        strikeout_offset: metrics.strikeout_offset * inv_sf,
770        stroke_size: metrics.stroke_size * inv_sf,
771    })
772}
773
774/// A bidi run: a contiguous range of text with the same direction.
775#[non_exhaustive]
776pub struct BidiRun {
777    pub byte_range: std::ops::Range<usize>,
778    pub direction: TextDirection,
779    /// Visual order index (for reordering after line breaking).
780    pub visual_order: usize,
781    /// UAX #9 embedding level: even is LTR, odd is RTL.
782    ///
783    /// Rule L2 reorders by level, not by direction, and the two are not
784    /// interchangeable: a Latin phrase quoted inside Arabic inside an
785    /// English paragraph sits at level 2, and reordering it as though it
786    /// were level 0 puts it on the wrong side of the Arabic. `direction`
787    /// cannot tell those apart — `level` can.
788    pub level: u8,
789}
790
791/// A paragraph's bidi structure in **logical** order.
792///
793/// [`bidi_runs`] returns runs already reordered for display, which suits
794/// a single-line label that is shaped and painted in one go. The
795/// multi-line editor cannot use that: line breaking is a logical
796/// operation, so runs have to stay in logical order until the breaker has
797/// decided where the lines fall, and only then get reordered *per line*.
798/// Reordering the paragraph up front and breaking afterwards would
799/// scramble any paragraph that wraps.
800#[non_exhaustive]
801pub struct BidiParagraph {
802    /// Runs of uniform embedding level, in logical order.
803    pub runs: Vec<BidiRun>,
804    /// The paragraph embedding level actually used — the explicit base
805    /// direction when one was given, else the rule P2/P3 auto-detection.
806    pub para_level: u8,
807}
808
809impl BidiParagraph {
810    /// The paragraph's base direction, as resolved.
811    pub fn base_direction(&self) -> TextDirection {
812        if self.para_level % 2 == 1 {
813            TextDirection::RightToLeft
814        } else {
815            TextDirection::LeftToRight
816        }
817    }
818}
819
820/// The unicode-bidi paragraph level that expresses `base`.
821///
822/// `None` asks unicode-bidi to auto-detect (rules P2/P3: the first strong
823/// character wins, defaulting to LTR when the text has none). An explicit
824/// level overrides that — which is the point of honouring a stored
825/// paragraph direction, since P2/P3 incorrectly classifies any RTL
826/// paragraph that happens to open with a digit, a Latin acronym or an
827/// opening quote.
828fn base_para_level(base: TextDirection) -> Option<unicode_bidi::Level> {
829    match base {
830        TextDirection::Auto => None,
831        TextDirection::LeftToRight => Some(unicode_bidi::Level::ltr()),
832        TextDirection::RightToLeft => Some(unicode_bidi::Level::rtl()),
833    }
834}
835
836/// Resolve `text`'s bidi structure under an explicit or auto base direction.
837///
838/// Runs come back in logical order, each tagged with its embedding level.
839/// Callers shape each run with its own direction and later reorder the
840/// runs of each line with [`visual_order`].
841pub fn analyze_paragraph(text: &str, base: TextDirection) -> BidiParagraph {
842    use unicode_bidi::BidiInfo;
843
844    if text.is_empty() {
845        return BidiParagraph {
846            runs: Vec::new(),
847            para_level: base_para_level(base).map_or(0, |l| l.number()),
848        };
849    }
850
851    let bidi_info = BidiInfo::new(text, base_para_level(base));
852
853    // A block is one paragraph as far as layout is concerned; if the text
854    // somehow carries a hard break, the first paragraph's level is the
855    // one that governs alignment.
856    let para_level = bidi_info
857        .paragraphs
858        .first()
859        .map(|p| p.level.number())
860        .or_else(|| base_para_level(base).map(|l| l.number()))
861        .unwrap_or(0);
862
863    // Group consecutive characters of equal level. Iterating by
864    // `char_indices` rather than by byte keeps a run boundary from ever
865    // landing inside a multi-byte character.
866    let mut starts: Vec<(usize, u8)> = Vec::new();
867    for (idx, _) in text.char_indices() {
868        let level = bidi_info.levels[idx].number();
869        if starts.last().map(|&(_, l)| l) != Some(level) {
870            starts.push((idx, level));
871        }
872    }
873
874    // Each run ends where the next begins; the last ends with the text.
875    let ends = starts
876        .iter()
877        .skip(1)
878        .map(|&(start, _)| start)
879        .chain(std::iter::once(text.len()));
880
881    let runs: Vec<BidiRun> = starts
882        .iter()
883        .zip(ends)
884        .map(|(&(start, level), end)| BidiRun {
885            byte_range: start..end,
886            direction: if level % 2 == 1 {
887                TextDirection::RightToLeft
888            } else {
889                TextDirection::LeftToRight
890            },
891            // Always 0 here: these runs are in *logical* order and the
892            // block path reorders per line after breaking, so a
893            // paragraph-wide visual index would be both unused and
894            // misleading. `bidi_runs` fills it in for the single-line
895            // path, which does lay a paragraph out in one go.
896            visual_order: 0,
897            level,
898        })
899        .collect();
900
901    BidiParagraph { runs, para_level }
902}
903
904/// Reorder items from logical into visual order per UAX #9 rule L2.
905///
906/// Returns indices into `levels`: `result[0]` is the item to paint
907/// leftmost. L2 reads "from the highest level down to the lowest odd
908/// level, reverse any contiguous sequence of items at that level or
909/// higher", which is what the loop below does literally.
910pub fn visual_order(levels: &[u8]) -> Vec<usize> {
911    let mut order: Vec<usize> = (0..levels.len()).collect();
912    let Some(&max) = levels.iter().max() else {
913        return order;
914    };
915    // With no odd level nothing is RTL, so logical order is already visual.
916    let Some(min_odd) = levels.iter().copied().filter(|l| l % 2 == 1).min() else {
917        return order;
918    };
919
920    let mut level = max;
921    while level >= min_odd {
922        let mut i = 0;
923        while i < order.len() {
924            if levels[order[i]] >= level {
925                let start = i;
926                while i < order.len() && levels[order[i]] >= level {
927                    i += 1;
928                }
929                order[start..i].reverse();
930            } else {
931                i += 1;
932            }
933        }
934        // min_odd is odd, hence >= 1, so this cannot wrap past zero.
935        level -= 1;
936    }
937    order
938}
939
940/// Analyze text for bidirectional content and return directional runs
941/// in **visual order** per UAX #9 (Unicode Bidirectional Algorithm, rule L2).
942///
943/// The returned runs can be shaped independently and concatenated left-to-right
944/// to produce correctly-ordered mixed-script text (e.g. Latin embedded in
945/// Arabic). For pure-LTR text, returns a single LTR run. For pure-RTL text,
946/// returns a single RTL run.
947pub fn bidi_runs(text: &str) -> Vec<BidiRun> {
948    use unicode_bidi::BidiInfo;
949
950    if text.is_empty() {
951        return Vec::new();
952    }
953
954    let bidi_info = BidiInfo::new(text, None);
955    let mut runs = Vec::new();
956
957    for para in &bidi_info.paragraphs {
958        let (levels, level_runs) = bidi_info.visual_runs(para, para.range.clone());
959        for level_run in level_runs {
960            if level_run.is_empty() {
961                continue;
962            }
963            let level = levels[level_run.start];
964            let direction = if level.is_rtl() {
965                TextDirection::RightToLeft
966            } else {
967                TextDirection::LeftToRight
968            };
969            let visual_order = runs.len();
970            runs.push(BidiRun {
971                byte_range: level_run,
972                direction,
973                visual_order,
974                level: level.number(),
975            });
976        }
977    }
978
979    if runs.is_empty() {
980        runs.push(BidiRun {
981            byte_range: 0..text.len(),
982            direction: TextDirection::LeftToRight,
983            visual_order: 0,
984            level: 0,
985        });
986    }
987
988    runs
989}
990
991#[cfg(test)]
992mod bidi_tests {
993    use super::*;
994
995    const ARABIC: &str = "\u{0643}\u{062A}\u{0628}"; // كتب
996    const HEBREW: &str = "\u{05E9}\u{05DC}\u{05D5}\u{05DD}"; // שלום
997
998    #[test]
999    fn rule_l2_leaves_all_ltr_text_alone() {
1000        assert_eq!(visual_order(&[0, 0, 0]), vec![0, 1, 2]);
1001        assert_eq!(visual_order(&[]), Vec::<usize>::new());
1002    }
1003
1004    #[test]
1005    fn rule_l2_reverses_a_run_of_rtl() {
1006        // level 0 "a", level 1 RTL, level 0 "b" -> the RTL span reverses
1007        // in place but stays between its neighbours.
1008        assert_eq!(visual_order(&[0, 1, 1, 0]), vec![0, 2, 1, 3]);
1009    }
1010
1011    #[test]
1012    fn rule_l2_nests_an_ltr_island_inside_rtl() {
1013        // An English phrase (level 2) quoted inside Arabic (level 1)
1014        // inside an English paragraph (level 0). The level-2 island must
1015        // keep its own left-to-right order while the level-1 material
1016        // around it reverses — the case `direction` alone cannot express.
1017        let levels = [0, 1, 2, 2, 1, 0];
1018        assert_eq!(visual_order(&levels), vec![0, 4, 2, 3, 1, 5]);
1019    }
1020
1021    #[test]
1022    fn rule_l2_reverses_the_whole_line_in_an_rtl_paragraph() {
1023        // Level 1 throughout with a level-2 Latin word: the paragraph
1024        // reads right-to-left, so logical item 0 paints rightmost.
1025        assert_eq!(visual_order(&[1, 2, 1]), vec![2, 1, 0]);
1026    }
1027
1028    #[test]
1029    fn a_leading_digit_does_not_fool_auto_detection() {
1030        // Worth pinning, because it is easy to assume otherwise: digits
1031        // are type EN, not strong, so rule P2 skips them and finds the
1032        // Arabic. An Arabic paragraph opening with a number needs no
1033        // explicit direction.
1034        let text = "123 \u{0643}\u{062A}\u{0628}";
1035        assert_eq!(analyze_paragraph(text, TextDirection::Auto).para_level, 1);
1036    }
1037
1038    #[test]
1039    fn an_explicit_base_direction_overrides_first_strong_detection() {
1040        // A Latin acronym *is* strong (type L), so rule P2 stops at the
1041        // "NASA" and calls this Arabic paragraph left-to-right — the
1042        // real false detection, and the reason a stored paragraph
1043        // direction has to win over guessing.
1044        let text = "NASA \u{0623}\u{0639}\u{0644}\u{0646}\u{062A}";
1045        assert_eq!(
1046            analyze_paragraph(text, TextDirection::Auto).para_level,
1047            0,
1048            "auto-detection is expected to get this one wrong"
1049        );
1050
1051        let forced = analyze_paragraph(text, TextDirection::RightToLeft);
1052        assert_eq!(forced.para_level, 1);
1053        assert_eq!(forced.base_direction(), TextDirection::RightToLeft);
1054
1055        // And the override genuinely changes the layout, not just the
1056        // recorded level: the Arabic now leads visually. Runs come back
1057        // in logical order, so ask rule L2 which one paints leftmost —
1058        // the same thing a caller laying the paragraph out would do.
1059        let auto = analyze_paragraph(text, TextDirection::Auto);
1060        let first_visual = |p: &BidiParagraph| {
1061            let levels: Vec<u8> = p.runs.iter().map(|r| r.level).collect();
1062            visual_order(&levels).first().map(|&i| p.runs[i].direction)
1063        };
1064        assert_eq!(first_visual(&auto), Some(TextDirection::LeftToRight));
1065        assert_eq!(first_visual(&forced), Some(TextDirection::RightToLeft));
1066    }
1067
1068    #[test]
1069    fn pure_arabic_auto_detects_as_rtl() {
1070        let para = analyze_paragraph(ARABIC, TextDirection::Auto);
1071        assert_eq!(para.base_direction(), TextDirection::RightToLeft);
1072        assert_eq!(para.runs.len(), 1);
1073        assert_eq!(para.runs[0].direction, TextDirection::RightToLeft);
1074        assert_eq!(para.runs[0].byte_range, 0..ARABIC.len());
1075    }
1076
1077    #[test]
1078    fn runs_come_back_in_logical_order_and_cover_the_text() {
1079        // "hello <hebrew> world" — three runs, contiguous, logical order.
1080        let text = format!("hello {HEBREW} world");
1081        let para = analyze_paragraph(&text, TextDirection::Auto);
1082
1083        assert!(para.runs.len() >= 2, "expected a directional split");
1084        assert_eq!(para.runs[0].byte_range.start, 0);
1085        assert_eq!(para.runs.last().unwrap().byte_range.end, text.len());
1086        for pair in para.runs.windows(2) {
1087            assert_eq!(
1088                pair[0].byte_range.end, pair[1].byte_range.start,
1089                "runs must tile the text with no gap or overlap"
1090            );
1091            assert!(
1092                pair[0].byte_range.start < pair[1].byte_range.start,
1093                "runs must be in logical order"
1094            );
1095        }
1096        assert!(
1097            para.runs
1098                .iter()
1099                .any(|r| r.direction == TextDirection::RightToLeft),
1100            "the Hebrew span should have produced an RTL run"
1101        );
1102    }
1103
1104    #[test]
1105    fn run_boundaries_never_split_a_multibyte_character() {
1106        let text = format!("a{ARABIC}b{HEBREW}c");
1107        for run in analyze_paragraph(&text, TextDirection::Auto).runs {
1108            assert!(
1109                text.is_char_boundary(run.byte_range.start)
1110                    && text.is_char_boundary(run.byte_range.end),
1111                "run {:?} splits a character in {text:?}",
1112                run.byte_range
1113            );
1114        }
1115    }
1116
1117    #[test]
1118    fn rule_l2_over_a_real_paragraph_is_a_permutation() {
1119        let text = format!("hello {HEBREW} world {ARABIC} end");
1120        let para = analyze_paragraph(&text, TextDirection::Auto);
1121        let levels: Vec<u8> = para.runs.iter().map(|r| r.level).collect();
1122
1123        let mut seen = visual_order(&levels);
1124        seen.sort_unstable();
1125        assert_eq!(
1126            seen,
1127            (0..para.runs.len()).collect::<Vec<_>>(),
1128            "every run must appear exactly once in the visual order"
1129        );
1130    }
1131
1132    #[test]
1133    fn empty_text_analyzes_without_panicking() {
1134        let para = analyze_paragraph("", TextDirection::RightToLeft);
1135        assert!(para.runs.is_empty());
1136        assert_eq!(para.para_level, 1);
1137    }
1138}