feat: [WIP] generate alt text for ref elements

- fix marking repeated headers/footers as artifacts
- fix table row grouping with empty cells

Cargo.lock

@@ -1367,6 +1367,7 @@ dependencies = [
 [[package]]
 name = "krilla"
 version = "0.4.0"
+source = "git+https://github.com/saecki/krilla?branch=tag-attributes#2897351d6eeb139675b5e7e2765fe6f082e26efd"
 dependencies = [
  "base64",
  "bumpalo",
@@ -1395,6 +1396,7 @@ dependencies = [
 [[package]]
 name = "krilla-svg"
 version = "0.1.0"
+source = "git+https://github.com/saecki/krilla?branch=tag-attributes#2897351d6eeb139675b5e7e2765fe6f082e26efd"
 dependencies = [
  "flate2",
  "fontdb",

Cargo.toml

@@ -73,8 +73,8 @@ image = { version = "0.25.5", default-features = false, features = ["png", "jpeg
 indexmap = { version = "2", features = ["serde"] }
 infer = { version = "0.19.0", default-features = false }
 kamadak-exif = "0.6"
-krilla = { path = "../krilla/crates/krilla", default-features = false, features = ["raster-images", "comemo", "rayon"] }
-krilla-svg = { path = "../krilla/crates/krilla-svg" }
+krilla = { git = "https://github.com/saecki/krilla", branch = "tag-attributes", default-features = false, features = ["raster-images", "comemo", "rayon"] }
+krilla-svg = { git = "https://github.com/saecki/krilla", branch = "tag-attributes" }
 kurbo = "0.11"
 libfuzzer-sys = "0.4"
 lipsum = "0.9"

crates/typst-layout/src/inline/collect.rs

@@ -206,7 +206,7 @@ pub fn collect<'a>(
                     }
                     InlineItem::Frame(mut frame) => {
                         frame.modify(&FrameModifiers::get_in(styles));
-                        apply_baseline_shift(&mut frame, styles);
+                        apply_shift(&engine.world, &mut frame, styles);
                         collector.push_item(Item::Frame(frame));
                     }
                 }
@@ -221,7 +221,7 @@ pub fn collect<'a>(
                 let mut frame = layout_and_modify(styles, |styles| {
                     layout_box(elem, engine, loc, styles, region)
                 })?;
-                apply_baseline_shift(&mut frame, styles);
+                apply_shift(&engine.world, &mut frame, styles);
                 collector.push_item(Item::Frame(frame));
             }
         } else if let Some(elem) = child.to_packed::<TagElem>() {

crates/typst-layout/src/inline/line.rs

@@ -5,7 +5,7 @@ use typst_library::engine::Engine;
 use typst_library::introspection::{SplitLocator, Tag};
 use typst_library::layout::{Abs, Dir, Em, Fr, Frame, FrameItem, Point};
 use typst_library::model::ParLineMarker;
-use typst_library::text::{Lang, TextElem};
+use typst_library::text::{variant, Lang, TextElem};
 use typst_utils::Numeric;
 
 use super::*;
@@ -330,7 +330,7 @@ fn adjust_cj_at_line_start(p: &Preparation, items: &mut Items) {
         let glyph = shaped.glyphs.to_mut().first_mut().unwrap();
         let shrink = glyph.shrinkability().0;
         glyph.shrink_left(shrink);
-        shaped.width -= shrink.at(shaped.size);
+        shaped.width -= shrink.at(glyph.size);
     } else if p.config.cjk_latin_spacing
         && glyph.is_cj_script()
         && glyph.x_offset > Em::zero()
@@ -342,7 +342,7 @@ fn adjust_cj_at_line_start(p: &Preparation, items: &mut Items) {
         glyph.x_advance -= shrink;
         glyph.x_offset = Em::zero();
         glyph.adjustability.shrinkability.0 = Em::zero();
-        shaped.width -= shrink.at(shaped.size);
+        shaped.width -= shrink.at(glyph.size);
     }
 }
 
@@ -360,7 +360,7 @@ fn adjust_cj_at_line_end(p: &Preparation, items: &mut Items) {
         let shrink = glyph.shrinkability().1;
         let punct = shaped.glyphs.to_mut().last_mut().unwrap();
         punct.shrink_right(shrink);
-        shaped.width -= shrink.at(shaped.size);
+        shaped.width -= shrink.at(punct.size);
     } else if p.config.cjk_latin_spacing
         && glyph.is_cj_script()
         && (glyph.x_advance - glyph.x_offset) > Em::one()
@@ -371,7 +371,7 @@ fn adjust_cj_at_line_end(p: &Preparation, items: &mut Items) {
         let glyph = shaped.glyphs.to_mut().last_mut().unwrap();
         glyph.x_advance -= shrink;
         glyph.adjustability.shrinkability.1 = Em::zero();
-        shaped.width -= shrink.at(shaped.size);
+        shaped.width -= shrink.at(glyph.size);
     }
 }
 
@@ -412,9 +412,30 @@ fn should_repeat_hyphen(pred_line: &Line, text: &str) -> bool {
     }
 }
 
-/// Apply the current baseline shift to a frame.
-pub fn apply_baseline_shift(frame: &mut Frame, styles: StyleChain) {
-    frame.translate(Point::with_y(TextElem::baseline_in(styles)));
+/// Apply the current baseline shift and italic compensation to a frame.
+pub fn apply_shift<'a>(
+    world: &Tracked<'a, dyn World + 'a>,
+    frame: &mut Frame,
+    styles: StyleChain,
+) {
+    let mut baseline = TextElem::baseline_in(styles);
+    let mut compensation = Abs::zero();
+    if let Some(scripts) = TextElem::shift_settings_in(styles) {
+        let font_metrics = TextElem::font_in(styles)
+            .into_iter()
+            .find_map(|family| {
+                world
+                    .book()
+                    .select(family.as_str(), variant(styles))
+                    .and_then(|id| world.font(id))
+            })
+            .map_or(*scripts.kind.default_metrics(), |f| {
+                *scripts.kind.read_metrics(f.metrics())
+            });
+        baseline -= scripts.shift.unwrap_or(font_metrics.vertical_offset).resolve(styles);
+        compensation += font_metrics.horizontal_offset.resolve(styles);
+    }
+    frame.translate(Point::new(compensation, baseline));
 }
 
 /// Commit to a line and build its frame.
@@ -444,7 +465,7 @@ pub fn commit(
                 && TextElem::overhang_in(text.styles)
                 && (line.items.len() > 1 || text.glyphs.len() > 1)
             {
-                let amount = overhang(glyph.c) * glyph.x_advance.at(text.size);
+                let amount = overhang(glyph.c) * glyph.x_advance.at(glyph.size);
                 offset -= amount;
                 remaining += amount;
             }
@@ -458,7 +479,7 @@ pub fn commit(
                 && TextElem::overhang_in(text.styles)
                 && (line.items.len() > 1 || text.glyphs.len() > 1)
             {
-                let amount = overhang(glyph.c) * glyph.x_advance.at(text.size);
+                let amount = overhang(glyph.c) * glyph.x_advance.at(glyph.size);
                 remaining += amount;
             }
         }
@@ -519,7 +540,7 @@ pub fn commit(
                     let mut frame = layout_and_modify(*styles, |styles| {
                         layout_box(elem, engine, loc.relayout(), styles, region)
                     })?;
-                    apply_baseline_shift(&mut frame, *styles);
+                    apply_shift(&engine.world, &mut frame, *styles);
                     push(&mut offset, frame, idx);
                 } else {
                     offset += amount;

crates/typst-layout/src/inline/linebreak.rs

@@ -927,9 +927,9 @@ impl Estimates {
                     let byte_len = g.range.len();
                     let stretch = g.stretchability().0 + g.stretchability().1;
                     let shrink = g.shrinkability().0 + g.shrinkability().1;
-                    widths.push(byte_len, g.x_advance.at(shaped.size));
-                    stretchability.push(byte_len, stretch.at(shaped.size));
-                    shrinkability.push(byte_len, shrink.at(shaped.size));
+                    widths.push(byte_len, g.x_advance.at(g.size));
+                    stretchability.push(byte_len, stretch.at(g.size));
+                    shrinkability.push(byte_len, shrink.at(g.size));
                     justifiables.push(byte_len, g.is_justifiable() as usize);
                 }
             } else {

crates/typst-layout/src/inline/mod.rs

@@ -29,7 +29,7 @@ use typst_utils::{Numeric, SliceExt};
 use self::collect::{collect, Item, Segment, SpanMapper};
 use self::deco::decorate;
 use self::finalize::finalize;
-use self::line::{apply_baseline_shift, commit, line, Line};
+use self::line::{apply_shift, commit, line, Line};
 use self::linebreak::{linebreak, Breakpoint};
 use self::prepare::{prepare, Preparation};
 use self::shaping::{

crates/typst-layout/src/inline/prepare.rs

@@ -144,7 +144,7 @@ fn add_cjk_latin_spacing(items: &mut [(Range, Item)]) {
                 // The spacing is default to 1/4 em, and can be shrunk to 1/8 em.
                 glyph.x_advance += Em::new(0.25);
                 glyph.adjustability.shrinkability.1 += Em::new(0.125);
-                text.width += Em::new(0.25).at(text.size);
+                text.width += Em::new(0.25).at(glyph.size);
             }
 
             // Case 2: Latin followed by a CJ character
@@ -152,7 +152,7 @@ fn add_cjk_latin_spacing(items: &mut [(Range, Item)]) {
                 glyph.x_advance += Em::new(0.25);
                 glyph.x_offset += Em::new(0.25);
                 glyph.adjustability.shrinkability.0 += Em::new(0.125);
-                text.width += Em::new(0.25).at(text.size);
+                text.width += Em::new(0.25).at(glyph.size);
             }
 
             prev = Some(glyph);

crates/typst-layout/src/inline/shaping.rs

@@ -3,14 +3,15 @@ use std::fmt::{self, Debug, Formatter};
 use std::sync::Arc;
 
 use az::SaturatingAs;
-use rustybuzz::{BufferFlags, ShapePlan, UnicodeBuffer};
+use rustybuzz::{BufferFlags, Feature, ShapePlan, UnicodeBuffer};
+use ttf_parser::gsub::SubstitutionSubtable;
 use ttf_parser::Tag;
 use typst_library::engine::Engine;
 use typst_library::foundations::{Smart, StyleChain};
 use typst_library::layout::{Abs, Dir, Em, Frame, FrameItem, Point, Size};
 use typst_library::text::{
     families, features, is_default_ignorable, language, variant, Font, FontFamily,
-    FontVariant, Glyph, Lang, Region, TextEdgeBounds, TextElem, TextItem,
+    FontVariant, Glyph, Lang, Region, ShiftSettings, TextEdgeBounds, TextElem, TextItem,
 };
 use typst_library::World;
 use typst_utils::SliceExt;
@@ -41,8 +42,6 @@ pub struct ShapedText<'a> {
     pub styles: StyleChain<'a>,
     /// The font variant.
     pub variant: FontVariant,
-    /// The font size.
-    pub size: Abs,
     /// The width of the text's bounding box.
     pub width: Abs,
     /// The shaped glyphs.
@@ -62,6 +61,8 @@ pub struct ShapedGlyph {
     pub x_offset: Em,
     /// The vertical offset of the glyph.
     pub y_offset: Em,
+    /// The font size for the glyph.
+    pub size: Abs,
     /// The adjustability of the glyph.
     pub adjustability: Adjustability,
     /// The byte range of this glyph's cluster in the full inline layout. A
@@ -222,14 +223,17 @@ impl<'a> ShapedText<'a> {
         let mut frame = Frame::soft(size);
         frame.set_baseline(top);
 
+        let size = TextElem::size_in(self.styles);
         let shift = TextElem::baseline_in(self.styles);
         let decos = TextElem::deco_in(self.styles);
         let fill = TextElem::fill_in(self.styles);
         let stroke = TextElem::stroke_in(self.styles);
         let span_offset = TextElem::span_offset_in(self.styles);
 
-        for ((font, y_offset), group) in
-            self.glyphs.as_ref().group_by_key(|g| (g.font.clone(), g.y_offset))
+        for ((font, y_offset, glyph_size), group) in self
+            .glyphs
+            .as_ref()
+            .group_by_key(|g| (g.font.clone(), g.y_offset, g.size))
         {
             let mut range = group[0].range.clone();
             for glyph in group {
@@ -237,7 +241,7 @@ impl<'a> ShapedText<'a> {
                 range.end = range.end.max(glyph.range.end);
             }
 
-            let pos = Point::new(offset, top + shift - y_offset.at(self.size));
+            let pos = Point::new(offset, top + shift - y_offset.at(size));
             let glyphs: Vec<Glyph> = group
                 .iter()
                 .map(|shaped: &ShapedGlyph| {
@@ -257,11 +261,11 @@ impl<'a> ShapedText<'a> {
                         adjustability_right * justification_ratio;
                     if shaped.is_justifiable() {
                         justification_right +=
-                            Em::from_length(extra_justification, self.size)
+                            Em::from_abs(extra_justification, glyph_size)
                     }
 
-                    frame.size_mut().x += justification_left.at(self.size)
-                        + justification_right.at(self.size);
+                    frame.size_mut().x += justification_left.at(glyph_size)
+                        + justification_right.at(glyph_size);
 
                     // We may not be able to reach the offset completely if
                     // it exceeds u16, but better to have a roughly correct
@@ -304,7 +308,7 @@ impl<'a> ShapedText<'a> {
 
             let item = TextItem {
                 font,
-                size: self.size,
+                size: glyph_size,
                 lang: self.lang,
                 region: self.region,
                 fill: fill.clone(),
@@ -336,12 +340,13 @@ impl<'a> ShapedText<'a> {
         let mut top = Abs::zero();
         let mut bottom = Abs::zero();
 
+        let size = TextElem::size_in(self.styles);
         let top_edge = TextElem::top_edge_in(self.styles);
         let bottom_edge = TextElem::bottom_edge_in(self.styles);
 
         // Expand top and bottom by reading the font's vertical metrics.
         let mut expand = |font: &Font, bounds: TextEdgeBounds| {
-            let (t, b) = font.edges(top_edge, bottom_edge, self.size, bounds);
+            let (t, b) = font.edges(top_edge, bottom_edge, size, bounds);
             top.set_max(t);
             bottom.set_max(b);
         };
@@ -388,18 +393,16 @@ impl<'a> ShapedText<'a> {
     pub fn stretchability(&self) -> Abs {
         self.glyphs
             .iter()
-            .map(|g| g.stretchability().0 + g.stretchability().1)
-            .sum::<Em>()
-            .at(self.size)
+            .map(|g| (g.stretchability().0 + g.stretchability().1).at(g.size))
+            .sum()
     }
 
     /// The shrinkability of the text
     pub fn shrinkability(&self) -> Abs {
         self.glyphs
             .iter()
-            .map(|g| g.shrinkability().0 + g.shrinkability().1)
-            .sum::<Em>()
-            .at(self.size)
+            .map(|g| (g.shrinkability().0 + g.shrinkability().1).at(g.size))
+            .sum()
     }
 
     /// Reshape a range of the shaped text, reusing information from this
@@ -418,9 +421,8 @@ impl<'a> ShapedText<'a> {
                 lang: self.lang,
                 region: self.region,
                 styles: self.styles,
-                size: self.size,
                 variant: self.variant,
-                width: glyphs.iter().map(|g| g.x_advance).sum::<Em>().at(self.size),
+                width: glyphs_width(glyphs),
                 glyphs: Cow::Borrowed(glyphs),
             }
         } else {
@@ -484,13 +486,15 @@ impl<'a> ShapedText<'a> {
             // that subtracting either of the endpoints by self.base doesn't
             // underflow. See <https://github.com/typst/typst/issues/2283>.
             .unwrap_or_else(|| self.base..self.base);
-            self.width += x_advance.at(self.size);
+            let size = TextElem::size_in(self.styles);
+            self.width += x_advance.at(size);
             let glyph = ShapedGlyph {
                 font,
                 glyph_id: glyph_id.0,
                 x_advance,
                 x_offset: Em::zero(),
                 y_offset: Em::zero(),
+                size,
                 adjustability: Adjustability::default(),
                 range,
                 safe_to_break: true,
@@ -666,6 +670,7 @@ fn shape<'a>(
     region: Option<Region>,
 ) -> ShapedText<'a> {
     let size = TextElem::size_in(styles);
+    let shift_settings = TextElem::shift_settings_in(styles);
     let mut ctx = ShapingContext {
         engine,
         size,
@@ -676,6 +681,7 @@ fn shape<'a>(
         features: features(styles),
         fallback: TextElem::fallback_in(styles),
         dir,
+        shift_settings,
     };
 
     if !text.is_empty() {
@@ -698,12 +704,17 @@ fn shape<'a>(
         region,
         styles,
         variant: ctx.variant,
-        size,
-        width: ctx.glyphs.iter().map(|g| g.x_advance).sum::<Em>().at(size),
+        width: glyphs_width(&ctx.glyphs),
         glyphs: Cow::Owned(ctx.glyphs),
     }
 }
 
+/// Computes the width of a run of glyphs relative to the font size, accounting
+/// for their individual scaling factors and other font metrics.
+fn glyphs_width(glyphs: &[ShapedGlyph]) -> Abs {
+    glyphs.iter().map(|g| g.x_advance.at(g.size)).sum()
+}
+
 /// Holds shaping results and metadata common to all shaped segments.
 struct ShapingContext<'a, 'v> {
     engine: &'a Engine<'v>,
@@ -715,6 +726,7 @@ struct ShapingContext<'a, 'v> {
     features: Vec<rustybuzz::Feature>,
     fallback: bool,
     dir: Dir,
+    shift_settings: Option<ShiftSettings>,
 }
 
 /// Shape text with font fallback using the `families` iterator.
@@ -789,6 +801,18 @@ fn shape_segment<'a>(
     // text extraction.
     buffer.set_flags(BufferFlags::REMOVE_DEFAULT_IGNORABLES);
 
+    let (script_shift, script_compensation, scale, shift_feature) = ctx
+        .shift_settings
+        .map_or((Em::zero(), Em::zero(), Em::one(), None), |settings| {
+            determine_shift(text, &font, settings)
+        });
+
+    let has_shift_feature = shift_feature.is_some();
+    if let Some(feat) = shift_feature {
+        // Temporarily push the feature.
+        ctx.features.push(feat)
+    }
+
     // Prepare the shape plan. This plan depends on direction, script, language,
     // and features, but is independent from the text and can thus be memoized.
     let plan = create_shape_plan(
@@ -799,6 +823,10 @@ fn shape_segment<'a>(
         &ctx.features,
     );
 
+    if has_shift_feature {
+        ctx.features.pop();
+    }
+
     // Shape!
     let buffer = rustybuzz::shape_with_plan(font.rusty(), &plan, buffer);
     let infos = buffer.glyph_infos();
@@ -869,8 +897,9 @@ fn shape_segment<'a>(
                 glyph_id: info.glyph_id as u16,
                 // TODO: Don't ignore y_advance.
                 x_advance,
-                x_offset: font.to_em(pos[i].x_offset),
-                y_offset: font.to_em(pos[i].y_offset),
+                x_offset: font.to_em(pos[i].x_offset) + script_compensation,
+                y_offset: font.to_em(pos[i].y_offset) + script_shift,
+                size: scale.at(ctx.size),
                 adjustability: Adjustability::default(),
                 range: start..end,
                 safe_to_break: !info.unsafe_to_break(),
@@ -932,6 +961,64 @@ fn shape_segment<'a>(
     ctx.used.pop();
 }
 
+/// Returns a `(script_shift, script_compensation, scale, feature)` quadruplet
+/// describing how to produce scripts.
+///
+/// Those values determine how the rendered text should be transformed to
+/// display sub-/super-scripts. If the OpenType feature can be used, the
+/// rendered text should not be transformed in any way, and so those values are
+/// neutral (`(0, 0, 1, None)`). If scripts should be synthesized, those values
+/// determine how to transform the rendered text to display scripts as expected.
+fn determine_shift(
+    text: &str,
+    font: &Font,
+    settings: ShiftSettings,
+) -> (Em, Em, Em, Option<Feature>) {
+    settings
+        .typographic
+        .then(|| {
+            // If typographic scripts are enabled (i.e., we want to use the
+            // OpenType feature instead of synthesizing if possible), we add
+            // "subs"/"sups" to the feature list if supported by the font.
+            // In case of a problem, we just early exit
+            let gsub = font.rusty().tables().gsub?;
+            let subtable_index =
+                gsub.features.find(settings.kind.feature())?.lookup_indices.get(0)?;
+            let coverage = gsub
+                .lookups
+                .get(subtable_index)?
+                .subtables
+                .get::<SubstitutionSubtable>(0)?
+                .coverage();
+            text.chars()
+                .all(|c| {
+                    font.rusty().glyph_index(c).is_some_and(|i| coverage.contains(i))
+                })
+                .then(|| {
+                    // If we can use the OpenType feature, we can keep the text
+                    // as is.
+                    (
+                        Em::zero(),
+                        Em::zero(),
+                        Em::one(),
+                        Some(Feature::new(settings.kind.feature(), 1, ..)),
+                    )
+                })
+        })
+        // Reunite the cases where `typographic` is `false` or where using the
+        // OpenType feature would not work.
+        .flatten()
+        .unwrap_or_else(|| {
+            let script_metrics = settings.kind.read_metrics(font.metrics());
+            (
+                settings.shift.unwrap_or(script_metrics.vertical_offset),
+                script_metrics.horizontal_offset,
+                settings.size.unwrap_or(script_metrics.height),
+                None,
+            )
+        })
+}
+
 /// Create a shape plan.
 #[comemo::memoize]
 pub fn create_shape_plan(
@@ -963,6 +1050,7 @@ fn shape_tofus(ctx: &mut ShapingContext, base: usize, text: &str, font: Font) {
             x_advance,
             x_offset: Em::zero(),
             y_offset: Em::zero(),
+            size: ctx.size,
             adjustability: Adjustability::default(),
             range: start..end,
             safe_to_break: true,
@@ -985,9 +1073,8 @@ fn shape_tofus(ctx: &mut ShapingContext, base: usize, text: &str, font: Font) {
 
 /// Apply tracking and spacing to the shaped glyphs.
 fn track_and_space(ctx: &mut ShapingContext) {
-    let tracking = Em::from_length(TextElem::tracking_in(ctx.styles), ctx.size);
-    let spacing =
-        TextElem::spacing_in(ctx.styles).map(|abs| Em::from_length(abs, ctx.size));
+    let tracking = Em::from_abs(TextElem::tracking_in(ctx.styles), ctx.size);
+    let spacing = TextElem::spacing_in(ctx.styles).map(|abs| Em::from_abs(abs, ctx.size));
 
     let mut glyphs = ctx.glyphs.iter_mut().peekable();
     while let Some(glyph) = glyphs.next() {

crates/typst-layout/src/math/fragment.rs

@@ -215,7 +215,7 @@ impl MathFragment {
                     &glyph.item.font,
                     GlyphId(glyph.item.glyphs[glyph_index].id),
                     corner,
-                    Em::from_length(height, glyph.item.size),
+                    Em::from_abs(height, glyph.item.size),
                 )
                 .unwrap_or_default()
                 .at(glyph.item.size)
@@ -767,8 +767,8 @@ fn assemble(
             advance += ratio * (max_overlap - min_overlap);
         }
         let (x, y) = match axis {
-            Axis::X => (Em::from_length(advance, base.item.size), Em::zero()),
-            Axis::Y => (Em::zero(), Em::from_length(advance, base.item.size)),
+            Axis::X => (Em::from_abs(advance, base.item.size), Em::zero()),
+            Axis::Y => (Em::zero(), Em::from_abs(advance, base.item.size)),
         };
         glyphs.push(Glyph {
             id: part.glyph_id.0,

crates/typst-library/src/layout/em.rs

@@ -6,7 +6,7 @@ use ecow::EcoString;
 use typst_utils::{Numeric, Scalar};
 
 use crate::foundations::{cast, repr, Repr, Resolve, StyleChain, Value};
-use crate::layout::Abs;
+use crate::layout::{Abs, Length};
 use crate::text::TextElem;
 
 /// A length that is relative to the font size.
@@ -26,18 +26,18 @@ impl Em {
         Self(Scalar::ONE)
     }
 
-    /// Create a font-relative length.
+    /// Creates a font-relative length.
     pub const fn new(em: f64) -> Self {
         Self(Scalar::new(em))
     }
 
-    /// Create an em length from font units at the given units per em.
+    /// Creates an em length from font units at the given units per em.
     pub fn from_units(units: impl Into<f64>, units_per_em: f64) -> Self {
         Self(Scalar::new(units.into() / units_per_em))
     }
 
-    /// Create an em length from a length at the given font size.
-    pub fn from_length(length: Abs, font_size: Abs) -> Self {
+    /// Creates an em length from an absolute length at the given font size.
+    pub fn from_abs(length: Abs, font_size: Abs) -> Self {
         let result = length / font_size;
         if result.is_finite() {
             Self(Scalar::new(result))
@@ -46,6 +46,11 @@ impl Em {
         }
     }
 
+    /// Creates an em length from a length at the given font size.
+    pub fn from_length(length: Length, font_size: Abs) -> Em {
+        length.em + Self::from_abs(length.abs, font_size)
+    }
+
     /// The number of em units.
     pub const fn get(self) -> f64 {
         (self.0).get()
@@ -56,7 +61,7 @@ impl Em {
         Self::new(self.get().abs())
     }
 
-    /// Convert to an absolute length at the given font size.
+    /// Converts to an absolute length at the given font size.
     pub fn at(self, font_size: Abs) -> Abs {
         let resolved = font_size * self.get();
         if resolved.is_finite() {

crates/typst-library/src/model/bibliography.rs

@@ -877,7 +877,7 @@ impl<'a> Generator<'a> {
                         renderer.display_elem_child(elem, &mut None, false)?;
                     if let Some(location) = first_occurrences.get(item.key.as_str()) {
                         let dest = Destination::Location(*location);
-                        // TODO: accept user supplied alt text
+                        // TODO(accessibility): generate alt text
                         content = content.linked(dest, None);
                     }
                     StrResult::Ok(content)
@@ -1013,7 +1013,7 @@ impl ElemRenderer<'_> {
         if let Some(hayagriva::ElemMeta::Entry(i)) = elem.meta {
             if let Some(location) = (self.link)(i) {
                 let dest = Destination::Location(location);
-                // TODO: accept user supplied alt text
+                // TODO(accessibility): generate alt text
                 content = content.linked(dest, None);
             }
         }

crates/typst-library/src/model/footnote.rs

@@ -147,7 +147,7 @@ impl Show for Packed<FootnoteElem> {
         let sup = SuperElem::new(num).pack().spanned(span);
         let loc = loc.variant(1);
         // Add zero-width weak spacing to make the footnote "sticky".
-        // TODO: accept user supplied alt text
+        // TODO(accessibility): generate alt text
         Ok(HElem::hole().pack() + sup.linked(Destination::Location(loc), None))
     }
 }
@@ -297,7 +297,7 @@ impl Show for Packed<FootnoteEntry> {
         let sup = SuperElem::new(num)
             .pack()
             .spanned(span)
-            // TODO: accept user supplied alt text
+            // TODO(accessibility): generate alt text
             .linked(Destination::Location(loc), None)
             .located(loc.variant(1));
 

crates/typst-library/src/model/outline.rs

@@ -2,7 +2,7 @@ use std::num::NonZeroUsize;
 use std::str::FromStr;
 
 use comemo::{Track, Tracked};
-use ecow::eco_format;
+use ecow::{eco_format, EcoString};
 use smallvec::SmallVec;
 use typst_syntax::Span;
 use typst_utils::{Get, NonZeroExt};
@@ -23,7 +23,7 @@ use crate::layout::{
 };
 use crate::math::EquationElem;
 use crate::model::{Destination, HeadingElem, NumberingPattern, ParElem, Refable};
-use crate::text::{LocalName, SpaceElem, TextElem};
+use crate::text::{LocalName, SmartQuoteElem, SmartQuotes, SpaceElem, TextElem};
 
 /// A table of contents, figures, or other elements.
 ///
@@ -311,7 +311,7 @@ impl LocalName for Packed<OutlineElem> {
     const KEY: &'static str = "outline";
 }
 
-/// Only used to mark
+/// Only used to delimit the outline in tagged PDF.
 #[elem(Locatable, Show)]
 pub struct OutlineBody {
     #[required]
@@ -435,18 +435,11 @@ impl Show for Packed<OutlineEntry> {
         let context = Context::new(None, Some(styles));
         let context = context.track();
 
-        // TODO: prefix should be wrapped in a `Lbl` structure element
+        // TODO(accessibility): prefix should be wrapped in a `Lbl` structure element
         let prefix = self.prefix(engine, context, span)?;
         let body = self.body().at(span)?;
         let page = self.page(engine, context, span)?;
-        let alt = {
-            // TODO: accept user supplied alt text
-            let prefix = prefix.as_ref().map(|p| p.plain_text()).unwrap_or_default();
-            let body = body.plain_text();
-            let page_str = PageElem::local_name_in(styles);
-            let page_nr = page.plain_text();
-            eco_format!("{prefix} \"{body}\", {page_str} {page_nr}")
-        };
+        let alt = alt_text(styles, &prefix, &body, &page);
         let inner = self.inner(context, span, body, page)?;
         let block = if self.element.is::<EquationElem>() {
             let body = prefix.unwrap_or_default() + inner;
@@ -704,6 +697,27 @@ cast! {
     v: Content => v.unpack::<Self>().map_err(|_| "expected outline entry")?
 }
 
+fn alt_text(
+    styles: StyleChain,
+    prefix: &Option<Content>,
+    body: &Content,
+    page: &Content,
+) -> EcoString {
+    let prefix = prefix.as_ref().map(|p| p.plain_text()).unwrap_or_default();
+    let body = body.plain_text();
+    let page_str = PageElem::local_name_in(styles);
+    let page_nr = page.plain_text();
+    let quotes = SmartQuotes::get(
+        SmartQuoteElem::quotes_in(styles),
+        TextElem::lang_in(styles),
+        TextElem::region_in(styles),
+        SmartQuoteElem::alternative_in(styles),
+    );
+    let open = quotes.double_open;
+    let close = quotes.double_close;
+    eco_format!("{prefix} {open}{body}{close} {page_str} {page_nr}",)
+}
+
 /// Measures the width of a prefix.
 fn measure_prefix(
     engine: &mut Engine,

crates/typst-library/src/model/reference.rs

@@ -338,13 +338,18 @@ fn show_reference(
         Smart::Custom(Some(supplement)) => supplement.resolve(engine, styles, [elem])?,
     };
 
+    let alt = {
+        let supplement = supplement.plain_text();
+        let numbering = numbers.plain_text();
+        eco_format!("{supplement} {numbering}",)
+    };
+
     let mut content = numbers;
     if !supplement.is_empty() {
         content = supplement + TextElem::packed("\u{a0}") + content;
     }
 
-    // TODO: accept user supplied alt text
-    Ok(content.linked(Destination::Location(loc), None))
+    Ok(content.linked(Destination::Location(loc), Some(alt)))
 }
 
 /// Turn a reference into a citation.

crates/typst-library/src/text/font/mod.rs

@@ -228,6 +228,10 @@ pub struct FontMetrics {
     pub underline: LineMetrics,
     /// Recommended metrics for an overline.
     pub overline: LineMetrics,
+    /// Metrics for subscripts, if provided by the font.
+    pub subscript: Option<ScriptMetrics>,
+    /// Metrics for superscripts, if provided by the font.
+    pub superscript: Option<ScriptMetrics>,
 }
 
 impl FontMetrics {
@@ -240,6 +244,7 @@ impl FontMetrics {
         let cap_height = ttf.capital_height().filter(|&h| h > 0).map_or(ascender, to_em);
         let x_height = ttf.x_height().filter(|&h| h > 0).map_or(ascender, to_em);
         let descender = to_em(ttf.typographic_descender().unwrap_or(ttf.descender()));
+
         let strikeout = ttf.strikeout_metrics();
         let underline = ttf.underline_metrics();
 
@@ -262,6 +267,20 @@ impl FontMetrics {
             thickness: underline.thickness,
         };
 
+        let subscript = ttf.subscript_metrics().map(|metrics| ScriptMetrics {
+            width: to_em(metrics.x_size),
+            height: to_em(metrics.y_size),
+            horizontal_offset: to_em(metrics.x_offset),
+            vertical_offset: -to_em(metrics.y_offset),
+        });
+
+        let superscript = ttf.superscript_metrics().map(|metrics| ScriptMetrics {
+            width: to_em(metrics.x_size),
+            height: to_em(metrics.y_size),
+            horizontal_offset: to_em(metrics.x_offset),
+            vertical_offset: to_em(metrics.y_offset),
+        });
+
         Self {
             units_per_em,
             ascender,
@@ -271,6 +290,8 @@ impl FontMetrics {
             strikethrough,
             underline,
             overline,
+            superscript,
+            subscript,
         }
     }
 
@@ -296,6 +317,24 @@ pub struct LineMetrics {
     pub thickness: Em,
 }
 
+/// Metrics for subscripts or superscripts.
+#[derive(Debug, Copy, Clone)]
+pub struct ScriptMetrics {
+    /// The width of those scripts, relative to the outer font size.
+    pub width: Em,
+    /// The height of those scripts, relative to the outer font size.
+    pub height: Em,
+    /// The horizontal (to the right) offset of those scripts, relative to the
+    /// outer font size.
+    ///
+    /// This is used for italic correction.
+    pub horizontal_offset: Em,
+    /// The vertical (to the top) offset of those scripts, relative to the outer font size.
+    ///
+    /// For superscripts, this is positive. For subscripts, this is negative.
+    pub vertical_offset: Em,
+}
+
 /// Identifies a vertical metric of a font.
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Cast)]
 pub enum VerticalFontMetric {

crates/typst-library/src/text/mod.rs

@@ -755,6 +755,12 @@ pub struct TextElem {
     #[internal]
     #[ghost]
     pub smallcaps: Option<Smallcaps>,
+
+    /// The configuration for superscripts or subscripts, if one of them is
+    /// enabled.
+    #[internal]
+    #[ghost]
+    pub shift_settings: Option<ShiftSettings>,
 }
 
 impl TextElem {

crates/typst-library/src/text/shift.rs

@@ -1,15 +1,14 @@
-use ecow::EcoString;
-
 use crate::diag::SourceResult;
 use crate::engine::Engine;
 use crate::foundations::{
-    elem, Content, NativeElement, Packed, SequenceElem, Show, StyleChain, TargetElem,
+    elem, Content, NativeElement, Packed, Show, Smart, StyleChain, TargetElem,
 };
 use crate::html::{tag, HtmlElem};
 use crate::introspection::Locatable;
 use crate::layout::{Em, Length};
-use crate::text::{variant, SpaceElem, TextElem, TextSize};
-use crate::World;
+use crate::text::{FontMetrics, TextElem, TextSize};
+use ttf_parser::Tag;
+use typst_library::text::ScriptMetrics;
 
 /// Renders text in subscript.
 ///
@@ -21,11 +20,16 @@ use crate::World;
 /// ```
 #[elem(title = "Subscript", Locatable, Show)]
 pub struct SubElem {
-    /// Whether to prefer the dedicated subscript characters of the font.
+    /// Whether to create artificial subscripts by lowering and scaling down
+    /// regular glyphs.
     ///
-    /// If this is enabled, Typst first tries to transform the text to subscript
-    /// codepoints. If that fails, it falls back to rendering lowered and shrunk
-    /// normal letters.
+    /// Ideally, subscripts glyphs are provided by the font (using the `subs`
+    /// OpenType feature). Otherwise, Typst is able to synthesize subscripts.
+    ///
+    /// When this is set to `{false}`, synthesized glyphs will be used
+    /// regardless of whether the font provides dedicated subscript glyphs. When
+    /// `{true}`, synthesized glyphs may still be used in case the font does not
+    /// provide the necessary subscript glyphs.
     ///
     /// ```example
     /// N#sub(typographic: true)[1]
@@ -34,17 +38,27 @@ pub struct SubElem {
     #[default(true)]
     pub typographic: bool,
 
-    /// The baseline shift for synthetic subscripts. Does not apply if
-    /// `typographic` is true and the font has subscript codepoints for the
-    /// given `body`.
-    #[default(Em::new(0.2).into())]
-    pub baseline: Length,
+    /// The downward baseline shift for synthesized subscripts.
+    ///
+    /// This only applies to synthesized subscripts. In other words, this has no
+    /// effect if `typographic` is `{true}` and the font provides the necessary
+    /// subscript glyphs.
+    ///
+    /// If set to `{auto}`, the baseline is shifted according to the metrics
+    /// provided by the font, with a fallback to `{0.2em}` in case the font does
+    /// not define the necessary metrics.
+    pub baseline: Smart<Length>,
 
-    /// The font size for synthetic subscripts. Does not apply if
-    /// `typographic` is true and the font has subscript codepoints for the
-    /// given `body`.
-    #[default(TextSize(Em::new(0.6).into()))]
-    pub size: TextSize,
+    /// The font size for synthesized subscripts.
+    ///
+    /// This only applies to synthesized subscripts. In other words, this has no
+    /// effect if `typographic` is `{true}` and the font provides the necessary
+    /// subscript glyphs.
+    ///
+    /// If set to `{auto}`, the size is scaled according to the metrics provided
+    /// by the font, with a fallback to `{0.6em}` in case the font does not
+    /// define the necessary metrics.
+    pub size: Smart<TextSize>,
 
     /// The text to display in subscript.
     #[required]
@@ -53,7 +67,7 @@ pub struct SubElem {
 
 impl Show for Packed<SubElem> {
     #[typst_macros::time(name = "sub", span = self.span())]
-    fn show(&self, engine: &mut Engine, styles: StyleChain) -> SourceResult<Content> {
+    fn show(&self, _: &mut Engine, styles: StyleChain) -> SourceResult<Content> {
         let body = self.body.clone();
 
         if TargetElem::target_in(styles).is_html() {
@@ -63,17 +77,14 @@ impl Show for Packed<SubElem> {
                 .spanned(self.span()));
         }
 
-        if self.typographic(styles) {
-            if let Some(text) = convert_script(&body, true) {
-                if is_shapable(engine, &text, styles) {
-                    return Ok(TextElem::packed(text));
-                }
-            }
-        };
-
-        Ok(body
-            .styled(TextElem::set_baseline(self.baseline(styles)))
-            .styled(TextElem::set_size(self.size(styles))))
+        show_script(
+            styles,
+            body,
+            self.typographic(styles),
+            self.baseline(styles),
+            self.size(styles),
+            ScriptKind::Sub,
+        )
     }
 }
 
@@ -87,11 +98,16 @@ impl Show for Packed<SubElem> {
 /// ```
 #[elem(title = "Superscript", Locatable, Show)]
 pub struct SuperElem {
-    /// Whether to prefer the dedicated superscript characters of the font.
+    /// Whether to create artificial superscripts by raising and scaling down
+    /// regular glyphs.
     ///
-    /// If this is enabled, Typst first tries to transform the text to
-    /// superscript codepoints. If that fails, it falls back to rendering
-    /// raised and shrunk normal letters.
+    /// Ideally, superscripts glyphs are provided by the font (using the `sups`
+    /// OpenType feature). Otherwise, Typst is able to synthesize superscripts.
+    ///
+    /// When this is set to `{false}`, synthesized glyphs will be used
+    /// regardless of whether the font provides dedicated superscript glyphs.
+    /// When `{true}`, synthesized glyphs may still be used in case the font
+    /// does not provide the necessary superscript glyphs.
     ///
     /// ```example
     /// N#super(typographic: true)[1]
@@ -100,17 +116,31 @@ pub struct SuperElem {
     #[default(true)]
     pub typographic: bool,
 
-    /// The baseline shift for synthetic superscripts. Does not apply if
-    /// `typographic` is true and the font has superscript codepoints for the
-    /// given `body`.
-    #[default(Em::new(-0.5).into())]
-    pub baseline: Length,
+    /// The downward baseline shift for synthesized superscripts.
+    ///
+    /// This only applies to synthesized superscripts. In other words, this has
+    /// no effect if `typographic` is `{true}` and the font provides the
+    /// necessary superscript glyphs.
+    ///
+    /// If set to `{auto}`, the baseline is shifted according to the metrics
+    /// provided by the font, with a fallback to `{-0.5em}` in case the font
+    /// does not define the necessary metrics.
+    ///
+    /// Note that, since the baseline shift is applied downward, you will need
+    /// to provide a negative value for the content to appear as raised above
+    /// the normal baseline.
+    pub baseline: Smart<Length>,
 
-    /// The font size for synthetic superscripts. Does not apply if
-    /// `typographic` is true and the font has superscript codepoints for the
-    /// given `body`.
-    #[default(TextSize(Em::new(0.6).into()))]
-    pub size: TextSize,
+    /// The font size for synthesized superscripts.
+    ///
+    /// This only applies to synthesized superscripts. In other words, this has
+    /// no effect if `typographic` is `{true}` and the font provides the
+    /// necessary superscript glyphs.
+    ///
+    /// If set to `{auto}`, the size is scaled according to the metrics provided
+    /// by the font, with a fallback to `{0.6em}` in case the font does not
+    /// define the necessary metrics.
+    pub size: Smart<TextSize>,
 
     /// The text to display in superscript.
     #[required]
@@ -119,7 +149,7 @@ pub struct SuperElem {
 
 impl Show for Packed<SuperElem> {
     #[typst_macros::time(name = "super", span = self.span())]
-    fn show(&self, engine: &mut Engine, styles: StyleChain) -> SourceResult<Content> {
+    fn show(&self, _: &mut Engine, styles: StyleChain) -> SourceResult<Content> {
         let body = self.body.clone();
 
         if TargetElem::target_in(styles).is_html() {
@@ -129,104 +159,102 @@ impl Show for Packed<SuperElem> {
                 .spanned(self.span()));
         }
 
-        if self.typographic(styles) {
-            if let Some(text) = convert_script(&body, false) {
-                if is_shapable(engine, &text, styles) {
-                    return Ok(TextElem::packed(text));
+        show_script(
+            styles,
+            body,
+            self.typographic(styles),
+            self.baseline(styles),
+            self.size(styles),
+            ScriptKind::Super,
+        )
     }
 }
+
+fn show_script(
+    styles: StyleChain,
+    body: Content,
+    typographic: bool,
+    baseline: Smart<Length>,
+    size: Smart<TextSize>,
+    kind: ScriptKind,
+) -> SourceResult<Content> {
+    let font_size = TextElem::size_in(styles);
+    Ok(body.styled(TextElem::set_shift_settings(Some(ShiftSettings {
+        typographic,
+        shift: baseline.map(|l| -Em::from_length(l, font_size)),
+        size: size.map(|t| Em::from_length(t.0, font_size)),
+        kind,
+    }))))
+}
+
+/// Configuration values for sub- or superscript text.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub struct ShiftSettings {
+    /// Whether the OpenType feature should be used if possible.
+    pub typographic: bool,
+    /// The baseline shift of the script, relative to the outer text size.
+    ///
+    /// For superscripts, this is positive. For subscripts, this is negative. A
+    /// value of [`Smart::Auto`] indicates that the value should be obtained
+    /// from font metrics.
+    pub shift: Smart<Em>,
+    /// The size of the script, relative to the outer text size.
+    ///
+    /// A value of [`Smart::Auto`] indicates that the value should be obtained
+    /// from font metrics.
+    pub size: Smart<Em>,
+    /// The kind of script (either a subscript, or a superscript).
+    ///
+    /// This is used to know which OpenType table to use to resolve
+    /// [`Smart::Auto`] values.
+    pub kind: ScriptKind,
+}
+
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub enum ScriptKind {
+    Sub,
+    Super,
+}
+
+impl ScriptKind {
+    /// Returns the default metrics for this script kind.
+    ///
+    /// This can be used as a last resort if neither the user nor the font
+    /// provided those metrics.
+    pub fn default_metrics(self) -> &'static ScriptMetrics {
+        match self {
+            Self::Sub => &DEFAULT_SUBSCRIPT_METRICS,
+            Self::Super => &DEFAULT_SUPERSCRIPT_METRICS,
+        }
+    }
+
+    /// Reads the script metrics from the font table for to this script kind.
+    pub fn read_metrics(self, font_metrics: &FontMetrics) -> &ScriptMetrics {
+        match self {
+            Self::Sub => font_metrics.subscript.as_ref(),
+            Self::Super => font_metrics.superscript.as_ref(),
+        }
+        .unwrap_or(self.default_metrics())
+    }
+
+    /// The corresponding OpenType feature.
+    pub const fn feature(self) -> Tag {
+        match self {
+            Self::Sub => Tag::from_bytes(b"subs"),
+            Self::Super => Tag::from_bytes(b"sups"),
+        }
+    }
+}
+static DEFAULT_SUBSCRIPT_METRICS: ScriptMetrics = ScriptMetrics {
+    width: Em::new(0.6),
+    height: Em::new(0.6),
+    horizontal_offset: Em::zero(),
+    vertical_offset: Em::new(-0.2),
 };
 
-        Ok(body
-            .styled(TextElem::set_baseline(self.baseline(styles)))
-            .styled(TextElem::set_size(self.size(styles))))
-    }
-}
-
-/// Find and transform the text contained in `content` to the given script kind
-/// if and only if it only consists of `Text`, `Space`, and `Empty` leaves.
-fn convert_script(content: &Content, sub: bool) -> Option<EcoString> {
-    if content.is::<SpaceElem>() {
-        Some(' '.into())
-    } else if let Some(elem) = content.to_packed::<TextElem>() {
-        if sub {
-            elem.text.chars().map(to_subscript_codepoint).collect()
-        } else {
-            elem.text.chars().map(to_superscript_codepoint).collect()
-        }
-    } else if let Some(sequence) = content.to_packed::<SequenceElem>() {
-        sequence
-            .children
-            .iter()
-            .map(|item| convert_script(item, sub))
-            .collect()
-    } else {
-        None
-    }
-}
-
-/// Checks whether the first retrievable family contains all code points of the
-/// given string.
-fn is_shapable(engine: &Engine, text: &str, styles: StyleChain) -> bool {
-    let world = engine.world;
-    for family in TextElem::font_in(styles) {
-        if let Some(font) = world
-            .book()
-            .select(family.as_str(), variant(styles))
-            .and_then(|id| world.font(id))
-        {
-            let covers = family.covers();
-            return text.chars().all(|c| {
-                covers.is_none_or(|cov| cov.is_match(c.encode_utf8(&mut [0; 4])))
-                    && font.ttf().glyph_index(c).is_some()
-            });
-        }
-    }
-
-    false
-}
-
-/// Convert a character to its corresponding Unicode superscript.
-fn to_superscript_codepoint(c: char) -> Option<char> {
-    match c {
-        '1' => Some('¹'),
-        '2' => Some('²'),
-        '3' => Some('³'),
-        '0' | '4'..='9' => char::from_u32(c as u32 - '0' as u32 + '⁰' as u32),
-        '+' => Some('⁺'),
-        '−' => Some('⁻'),
-        '=' => Some('⁼'),
-        '(' => Some('⁽'),
-        ')' => Some('⁾'),
-        'n' => Some('ⁿ'),
-        'i' => Some('ⁱ'),
-        ' ' => Some(' '),
-        _ => None,
-    }
-}
-
-/// Convert a character to its corresponding Unicode subscript.
-fn to_subscript_codepoint(c: char) -> Option<char> {
-    match c {
-        '0'..='9' => char::from_u32(c as u32 - '0' as u32 + '₀' as u32),
-        '+' => Some('₊'),
-        '−' => Some('₋'),
-        '=' => Some('₌'),
-        '(' => Some('₍'),
-        ')' => Some('₎'),
-        'a' => Some('ₐ'),
-        'e' => Some('ₑ'),
-        'o' => Some('ₒ'),
-        'x' => Some('ₓ'),
-        'h' => Some('ₕ'),
-        'k' => Some('ₖ'),
-        'l' => Some('ₗ'),
-        'm' => Some('ₘ'),
-        'n' => Some('ₙ'),
-        'p' => Some('ₚ'),
-        's' => Some('ₛ'),
-        't' => Some('ₜ'),
-        ' ' => Some(' '),
-        _ => None,
-    }
-}
+static DEFAULT_SUPERSCRIPT_METRICS: ScriptMetrics = ScriptMetrics {
+    width: Em::new(0.6),
+    height: Em::new(0.6),
+    horizontal_offset: Em::zero(),
+    vertical_offset: Em::new(0.5),
+};

crates/typst-pdf/src/convert.rs

@@ -293,7 +293,7 @@ pub(crate) fn handle_frame(
                 handle_image(gc, fc, image, *size, surface, *span)?
             }
             FrameItem::Link(dest, size) => handle_link(fc, gc, dest, *size),
-            FrameItem::Tag(Tag::Start(elem)) => tags::handle_start(gc, elem),
+            FrameItem::Tag(Tag::Start(elem)) => tags::handle_start(gc, elem)?,
             FrameItem::Tag(Tag::End(loc, _)) => tags::handle_end(gc, *loc),
         }
 

crates/typst-pdf/src/link.rs

@@ -8,7 +8,7 @@ use typst_library::layout::{Abs, Point, Position, Size};
 use typst_library::model::Destination;
 
 use crate::convert::{FrameContext, GlobalContext};
-use crate::tags::{self, Placeholder, StackEntryKind, TagNode};
+use crate::tags::{self, Placeholder, TagNode};
 use crate::util::{AbsExt, PointExt};
 
 pub(crate) struct LinkAnnotation {
@@ -49,8 +49,7 @@ pub(crate) fn handle_link(
         }
     };
 
-    let entry = gc.tags.stack.last_mut().expect("a link parent");
-    let StackEntryKind::Link(link_id, ref link) = entry.kind else {
+    let Some((link_id, link)) = gc.tags.find_parent_link() else {
         unreachable!("expected a link parent")
     };
     let alt = link.alt.as_ref().map(EcoString::to_string);

crates/typst-pdf/src/tags.rs

@@ -1,795 +0,0 @@
-use std::cell::OnceCell;
-use std::num::{NonZeroU32, NonZeroUsize};
-
-use ecow::EcoString;
-use krilla::page::Page;
-use krilla::surface::Surface;
-use krilla::tagging::{
-    ArtifactType, ContentTag, Identifier, Node, SpanTag, TableCellHeaders, TableCellSpan,
-    TableDataCell, TableHeaderCell, Tag, TagBuilder, TagGroup, TagId, TagKind, TagTree,
-};
-use typst_library::foundations::{Content, LinkMarker, Packed, Smart, StyleChain};
-use typst_library::introspection::Location;
-use typst_library::layout::RepeatElem;
-use typst_library::model::{
-    Destination, FigureCaption, FigureElem, HeadingElem, Outlinable, OutlineBody,
-    OutlineEntry, TableCell, TableCellKind, TableElem, TableHeaderScope,
-};
-use typst_library::pdf::{ArtifactElem, ArtifactKind, PdfTagElem, PdfTagKind};
-use typst_library::visualize::ImageElem;
-
-use crate::convert::GlobalContext;
-use crate::link::LinkAnnotation;
-
-pub(crate) struct Tags {
-    /// The intermediary stack of nested tag groups.
-    pub(crate) stack: Vec<StackEntry>,
-    /// A list of placeholders corresponding to a [`TagNode::Placeholder`].
-    pub(crate) placeholders: Vec<OnceCell<Node>>,
-    pub(crate) in_artifact: Option<(Location, ArtifactKind)>,
-    /// Used to group multiple link annotations using quad points.
-    pub(crate) link_id: LinkId,
-    /// Used to generate IDs referenced in table `Headers` attributes.
-    /// The IDs must be document wide unique.
-    pub(crate) table_id: TableId,
-
-    /// The output.
-    pub(crate) tree: Vec<TagNode>,
-}
-
-#[derive(Clone, Copy, PartialEq, Eq, Hash)]
-pub(crate) struct TableId(u32);
-
-#[derive(Clone, Copy, PartialEq, Eq, Hash)]
-pub(crate) struct LinkId(u32);
-
-pub(crate) struct StackEntry {
-    pub(crate) loc: Location,
-    pub(crate) kind: StackEntryKind,
-    pub(crate) nodes: Vec<TagNode>,
-}
-
-pub(crate) enum StackEntryKind {
-    Standard(Tag),
-    Outline(OutlineCtx),
-    OutlineEntry(Packed<OutlineEntry>),
-    Table(TableCtx),
-    TableCell(Packed<TableCell>),
-    Link(LinkId, Packed<LinkMarker>),
-}
-
-impl StackEntryKind {
-    pub(crate) fn as_standard_mut(&mut self) -> Option<&mut Tag> {
-        if let Self::Standard(v) = self {
-            Some(v)
-        } else {
-            None
-        }
-    }
-}
-
-pub(crate) struct OutlineCtx {
-    stack: Vec<OutlineSection>,
-}
-
-pub(crate) struct OutlineSection {
-    entries: Vec<TagNode>,
-}
-
-impl OutlineSection {
-    const fn new() -> Self {
-        OutlineSection { entries: Vec::new() }
-    }
-
-    fn push(&mut self, entry: TagNode) {
-        self.entries.push(entry);
-    }
-
-    fn into_tag(self) -> TagNode {
-        TagNode::Group(TagKind::TOC.into(), self.entries)
-    }
-}
-
-impl OutlineCtx {
-    fn new() -> Self {
-        Self { stack: Vec::new() }
-    }
-
-    fn insert(
-        &mut self,
-        outline_nodes: &mut Vec<TagNode>,
-        entry: Packed<OutlineEntry>,
-        nodes: Vec<TagNode>,
-    ) {
-        let expected_len = entry.level.get() - 1;
-        if self.stack.len() < expected_len {
-            self.stack.resize_with(expected_len, || OutlineSection::new());
-        } else {
-            while self.stack.len() > expected_len {
-                self.finish_section(outline_nodes);
-            }
-        }
-
-        let section_entry = TagNode::Group(TagKind::TOCI.into(), nodes);
-        self.push(outline_nodes, section_entry);
-    }
-
-    fn finish_section(&mut self, outline_nodes: &mut Vec<TagNode>) {
-        let sub_section = self.stack.pop().unwrap().into_tag();
-        self.push(outline_nodes, sub_section);
-    }
-
-    fn push(&mut self, outline_nodes: &mut Vec<TagNode>, entry: TagNode) {
-        match self.stack.last_mut() {
-            Some(section) => section.push(entry),
-            None => outline_nodes.push(entry),
-        }
-    }
-
-    fn build_outline(mut self, mut outline_nodes: Vec<TagNode>) -> Vec<TagNode> {
-        while self.stack.len() > 0 {
-            self.finish_section(&mut outline_nodes);
-        }
-        outline_nodes
-    }
-}
-
-pub(crate) struct TableCtx {
-    id: TableId,
-    table: Packed<TableElem>,
-    rows: Vec<Vec<GridCell>>,
-}
-
-#[derive(Clone, Default)]
-enum GridCell {
-    Cell(TableCtxCell),
-    Spanned(usize, usize),
-    #[default]
-    Missing,
-}
-
-impl GridCell {
-    fn as_cell(&self) -> Option<&TableCtxCell> {
-        if let Self::Cell(v) = self {
-            Some(v)
-        } else {
-            None
-        }
-    }
-
-    fn as_cell_mut(&mut self) -> Option<&mut TableCtxCell> {
-        if let Self::Cell(v) = self {
-            Some(v)
-        } else {
-            None
-        }
-    }
-
-    fn into_cell(self) -> Option<TableCtxCell> {
-        if let Self::Cell(v) = self {
-            Some(v)
-        } else {
-            None
-        }
-    }
-}
-
-#[derive(Clone)]
-struct TableCtxCell {
-    x: u32,
-    y: u32,
-    rowspan: NonZeroUsize,
-    colspan: NonZeroUsize,
-    kind: Smart<TableCellKind>,
-    headers: TableCellHeaders,
-    nodes: Vec<TagNode>,
-}
-
-impl TableCtxCell {
-    fn unwrap_kind(&self) -> TableCellKind {
-        self.kind.unwrap_or_else(|| unreachable!())
-    }
-}
-
-impl TableCtx {
-    fn new(id: TableId, table: Packed<TableElem>) -> Self {
-        Self { id, table: table.clone(), rows: Vec::new() }
-    }
-
-    fn get(&self, x: usize, y: usize) -> Option<&TableCtxCell> {
-        let cell = self.rows.get(y)?.get(x)?;
-        self.resolve_cell(cell)
-    }
-
-    fn get_mut(&mut self, x: usize, y: usize) -> Option<&mut TableCtxCell> {
-        let cell = self.rows.get_mut(y)?.get_mut(x)?;
-        match cell {
-            GridCell::Cell(cell) => {
-                // HACK: Workaround for the second mutable borrow when resolving
-                // the spanned cell.
-                Some(unsafe { std::mem::transmute(cell) })
-            }
-            &mut GridCell::Spanned(x, y) => self.rows[y][x].as_cell_mut(),
-            GridCell::Missing => None,
-        }
-    }
-
-    fn contains(&self, cell: &Packed<TableCell>) -> bool {
-        let x = cell.x(StyleChain::default()).unwrap_or_else(|| unreachable!());
-        let y = cell.y(StyleChain::default()).unwrap_or_else(|| unreachable!());
-        self.get(x, y).is_some()
-    }
-
-    fn resolve_cell<'a>(&'a self, cell: &'a GridCell) -> Option<&'a TableCtxCell> {
-        match cell {
-            GridCell::Cell(cell) => Some(cell),
-            &GridCell::Spanned(x, y) => self.rows[y][x].as_cell(),
-            GridCell::Missing => None,
-        }
-    }
-
-    fn insert(&mut self, cell: Packed<TableCell>, nodes: Vec<TagNode>) {
-        let x = cell.x(StyleChain::default()).unwrap_or_else(|| unreachable!());
-        let y = cell.y(StyleChain::default()).unwrap_or_else(|| unreachable!());
-        let rowspan = cell.rowspan(StyleChain::default());
-        let colspan = cell.colspan(StyleChain::default());
-        let kind = cell.kind(StyleChain::default());
-
-        // Extend the table grid to fit this cell.
-        let required_height = y + rowspan.get();
-        let required_width = x + colspan.get();
-        if self.rows.len() < required_height {
-            self.rows
-                .resize(required_height, vec![GridCell::Missing; required_width]);
-        }
-        let row = &mut self.rows[y];
-        if row.len() < required_width {
-            row.resize_with(required_width, || GridCell::Missing);
-        }
-
-        // Store references to the cell for all spanned cells.
-        for i in y..y + rowspan.get() {
-            for j in x..x + colspan.get() {
-                self.rows[i][j] = GridCell::Spanned(x, y);
-            }
-        }
-
-        self.rows[y][x] = GridCell::Cell(TableCtxCell {
-            x: x as u32,
-            y: y as u32,
-            rowspan,
-            colspan,
-            kind,
-            headers: TableCellHeaders::NONE,
-            nodes,
-        });
-    }
-
-    fn build_table(mut self, mut nodes: Vec<TagNode>) -> Vec<TagNode> {
-        // Table layouting ensures that there are no overlapping cells, and that
-        // any gaps left by the user are filled with empty cells.
-        if self.rows.is_empty() {
-            return nodes;
-        }
-        let height = self.rows.len();
-        let width = self.rows[0].len();
-
-        // Only generate row groups such as `THead`, `TFoot`, and `TBody` if
-        // there are no rows with mixed cell kinds.
-        let mut gen_row_groups = true;
-        let row_kinds = (self.rows.iter())
-            .map(|row| {
-                row.iter()
-                    .filter_map(|cell| self.resolve_cell(cell))
-                    .map(|cell| cell.kind)
-                    .fold(Smart::Auto, |a, b| {
-                        if let Smart::Custom(TableCellKind::Header(_, scope)) = b {
-                            gen_row_groups &= scope == TableHeaderScope::Column;
-                        }
-                        if let (Smart::Custom(a), Smart::Custom(b)) = (a, b) {
-                            gen_row_groups &= a == b;
-                        }
-                        a.or(b)
-                    })
-                    .unwrap_or(TableCellKind::Data)
-            })
-            .collect::<Vec<_>>();
-
-        // Fixup all missing cell kinds.
-        for (row, row_kind) in self.rows.iter_mut().zip(row_kinds.iter().copied()) {
-            let default_kind =
-                if gen_row_groups { row_kind } else { TableCellKind::Data };
-            for cell in row.iter_mut() {
-                let Some(cell) = cell.as_cell_mut() else { continue };
-                cell.kind = cell.kind.or(Smart::Custom(default_kind));
-            }
-        }
-
-        // Explicitly set the headers attribute for cells.
-        for x in 0..width {
-            let mut column_header = None;
-            for y in 0..height {
-                self.resolve_cell_headers(
-                    (x, y),
-                    &mut column_header,
-                    TableHeaderScope::refers_to_column,
-                );
-            }
-        }
-        for y in 0..height {
-            let mut row_header = None;
-            for x in 0..width {
-                self.resolve_cell_headers(
-                    (x, y),
-                    &mut row_header,
-                    TableHeaderScope::refers_to_row,
-                );
-            }
-        }
-
-        let mut chunk_kind = row_kinds[0];
-        let mut row_chunk = Vec::new();
-        for (row, row_kind) in self.rows.into_iter().zip(row_kinds) {
-            let row_nodes = row
-                .into_iter()
-                .filter_map(|cell| {
-                    let cell = cell.into_cell()?;
-                    let span = TableCellSpan {
-                        rows: cell.rowspan.try_into().unwrap(),
-                        cols: cell.colspan.try_into().unwrap(),
-                    };
-                    let tag = match cell.unwrap_kind() {
-                        TableCellKind::Header(_, scope) => {
-                            let id = table_cell_id(self.id, cell.x, cell.y);
-                            let scope = table_header_scope(scope);
-                            TagKind::TH(
-                                TableHeaderCell::new(scope)
-                                    .with_span(span)
-                                    .with_headers(cell.headers),
-                            )
-                            .with_id(Some(id))
-                        }
-                        TableCellKind::Footer | TableCellKind::Data => TagKind::TD(
-                            TableDataCell::new()
-                                .with_span(span)
-                                .with_headers(cell.headers),
-                        )
-                        .into(),
-                    };
-
-                    Some(TagNode::Group(tag, cell.nodes))
-                })
-                .collect();
-
-            let row = TagNode::Group(TagKind::TR.into(), row_nodes);
-
-            // Push the `TR` tags directly.
-            if !gen_row_groups {
-                nodes.push(row);
-                continue;
-            }
-
-            // Generate row groups.
-            if !should_group_rows(chunk_kind, row_kind) {
-                let tag = match chunk_kind {
-                    TableCellKind::Header(..) => TagKind::THead,
-                    TableCellKind::Footer => TagKind::TFoot,
-                    TableCellKind::Data => TagKind::TBody,
-                };
-                nodes.push(TagNode::Group(tag.into(), std::mem::take(&mut row_chunk)));
-
-                chunk_kind = row_kind;
-            }
-            row_chunk.push(row);
-        }
-
-        if !row_chunk.is_empty() {
-            let tag = match chunk_kind {
-                TableCellKind::Header(..) => TagKind::THead,
-                TableCellKind::Footer => TagKind::TFoot,
-                TableCellKind::Data => TagKind::TBody,
-            };
-            nodes.push(TagNode::Group(tag.into(), row_chunk));
-        }
-
-        nodes
-    }
-
-    fn resolve_cell_headers<F>(
-        &mut self,
-        (x, y): (usize, usize),
-        current_header: &mut Option<(NonZeroU32, TagId)>,
-        refers_to_dir: F,
-    ) where
-        F: Fn(&TableHeaderScope) -> bool,
-    {
-        let table_id = self.id;
-        let Some(cell) = self.get_mut(x, y) else { return };
-
-        if let Some((prev_level, cell_id)) = current_header.clone() {
-            // The `Headers` attribute is also set for parent headers.
-            let mut is_parent_header = true;
-            if let TableCellKind::Header(level, scope) = cell.unwrap_kind() {
-                if refers_to_dir(&scope) {
-                    is_parent_header = prev_level < level;
-                }
-            }
-
-            if is_parent_header && !cell.headers.ids.contains(&cell_id) {
-                cell.headers.ids.push(cell_id.clone());
-            }
-        }
-
-        if let TableCellKind::Header(level, scope) = cell.unwrap_kind() {
-            if refers_to_dir(&scope) {
-                let tag_id = table_cell_id(table_id, x as u32, y as u32);
-                *current_header = Some((level, tag_id));
-            }
-        }
-    }
-}
-
-fn should_group_rows(a: TableCellKind, b: TableCellKind) -> bool {
-    match (a, b) {
-        (TableCellKind::Header(..), TableCellKind::Header(..)) => true,
-        (TableCellKind::Footer, TableCellKind::Footer) => true,
-        (TableCellKind::Data, TableCellKind::Data) => true,
-        (_, _) => false,
-    }
-}
-
-fn table_cell_id(table_id: TableId, x: u32, y: u32) -> TagId {
-    let mut bytes = [0; 12];
-    bytes[0..4].copy_from_slice(&table_id.0.to_ne_bytes());
-    bytes[4..8].copy_from_slice(&x.to_ne_bytes());
-    bytes[8..12].copy_from_slice(&y.to_ne_bytes());
-    TagId::from_bytes(&bytes)
-}
-
-#[derive(Clone)]
-pub(crate) enum TagNode {
-    Group(Tag, Vec<TagNode>),
-    Leaf(Identifier),
-    /// Allows inserting a placeholder into the tag tree.
-    /// Currently used for [`krilla::page::Page::add_tagged_annotation`].
-    Placeholder(Placeholder),
-}
-
-#[derive(Clone, Copy)]
-pub(crate) struct Placeholder(usize);
-
-impl Tags {
-    pub(crate) fn new() -> Self {
-        Self {
-            stack: Vec::new(),
-            placeholders: Vec::new(),
-            in_artifact: None,
-
-            tree: Vec::new(),
-            link_id: LinkId(0),
-            table_id: TableId(0),
-        }
-    }
-
-    pub(crate) fn reserve_placeholder(&mut self) -> Placeholder {
-        let idx = self.placeholders.len();
-        self.placeholders.push(OnceCell::new());
-        Placeholder(idx)
-    }
-
-    pub(crate) fn init_placeholder(&mut self, placeholder: Placeholder, node: Node) {
-        self.placeholders[placeholder.0]
-            .set(node)
-            .map_err(|_| ())
-            .expect("placeholder to be uninitialized");
-    }
-
-    pub(crate) fn take_placeholder(&mut self, placeholder: Placeholder) -> Node {
-        self.placeholders[placeholder.0]
-            .take()
-            .expect("initialized placeholder node")
-    }
-
-    /// Returns the current parent's list of children and the structure type ([Tag]).
-    /// In case of the document root the structure type will be `None`.
-    pub(crate) fn parent(&mut self) -> Option<&mut StackEntryKind> {
-        self.stack.last_mut().map(|e| &mut e.kind)
-    }
-
-    pub(crate) fn push(&mut self, node: TagNode) {
-        if let Some(entry) = self.stack.last_mut() {
-            entry.nodes.push(node);
-        } else {
-            self.tree.push(node);
-        }
-    }
-
-    pub(crate) fn build_tree(&mut self) -> TagTree {
-        let children = std::mem::take(&mut self.tree)
-            .into_iter()
-            .map(|node| self.resolve_node(node))
-            .collect::<Vec<_>>();
-        TagTree::from(children)
-    }
-
-    /// Resolves [`Placeholder`] nodes.
-    fn resolve_node(&mut self, node: TagNode) -> Node {
-        match node {
-            TagNode::Group(tag, nodes) => {
-                let children = nodes
-                    .into_iter()
-                    .map(|node| self.resolve_node(node))
-                    .collect::<Vec<_>>();
-                Node::Group(TagGroup::with_children(tag, children))
-            }
-            TagNode::Leaf(identifier) => Node::Leaf(identifier),
-            TagNode::Placeholder(placeholder) => self.take_placeholder(placeholder),
-        }
-    }
-
-    fn context_supports(&self, _tag: &StackEntryKind) -> bool {
-        // TODO: generate using: https://pdfa.org/resource/iso-ts-32005-hierarchical-inclusion-rules/
-        true
-    }
-
-    fn next_link_id(&mut self) -> LinkId {
-        self.link_id.0 += 1;
-        self.link_id
-    }
-
-    fn next_table_id(&mut self) -> TableId {
-        self.table_id.0 += 1;
-        self.table_id
-    }
-}
-
-/// Automatically calls [`Surface::end_tagged`] when dropped.
-pub(crate) struct TagHandle<'a, 'b> {
-    surface: &'b mut Surface<'a>,
-}
-
-impl Drop for TagHandle<'_, '_> {
-    fn drop(&mut self) {
-        self.surface.end_tagged();
-    }
-}
-
-impl<'a> TagHandle<'a, '_> {
-    pub(crate) fn surface<'c>(&'c mut self) -> &'c mut Surface<'a> {
-        &mut self.surface
-    }
-}
-
-/// Returns a [`TagHandle`] that automatically calls [`Surface::end_tagged`]
-/// when dropped.
-pub(crate) fn start_marked<'a, 'b>(
-    gc: &mut GlobalContext,
-    surface: &'b mut Surface<'a>,
-) -> TagHandle<'a, 'b> {
-    start_content(gc, surface, ContentTag::Other)
-}
-
-/// Returns a [`TagHandle`] that automatically calls [`Surface::end_tagged`]
-/// when dropped.
-pub(crate) fn start_span<'a, 'b>(
-    gc: &mut GlobalContext,
-    surface: &'b mut Surface<'a>,
-    span: SpanTag,
-) -> TagHandle<'a, 'b> {
-    start_content(gc, surface, ContentTag::Span(span))
-}
-
-fn start_content<'a, 'b>(
-    gc: &mut GlobalContext,
-    surface: &'b mut Surface<'a>,
-    content: ContentTag,
-) -> TagHandle<'a, 'b> {
-    let content = if let Some((_, kind)) = gc.tags.in_artifact {
-        let ty = artifact_type(kind);
-        ContentTag::Artifact(ty)
-    } else if let Some(StackEntryKind::Table(_)) = gc.tags.stack.last().map(|e| &e.kind) {
-        // Mark any direct child of a table as an aritfact. Any real content
-        // will be wrapped inside a `TableCell`.
-        ContentTag::Artifact(ArtifactType::Other)
-    } else {
-        content
-    };
-    let id = surface.start_tagged(content);
-    gc.tags.push(TagNode::Leaf(id));
-    TagHandle { surface }
-}
-
-/// Add all annotations that were found in the page frame.
-pub(crate) fn add_annotations(
-    gc: &mut GlobalContext,
-    page: &mut Page,
-    annotations: Vec<LinkAnnotation>,
-) {
-    for annotation in annotations.into_iter() {
-        let LinkAnnotation { id: _, placeholder, alt, rect, quad_points, target } =
-            annotation;
-        let annot = krilla::annotation::Annotation::new_link(
-            krilla::annotation::LinkAnnotation::new(rect, Some(quad_points), target),
-            alt,
-        );
-        let annot_id = page.add_tagged_annotation(annot);
-        gc.tags.init_placeholder(placeholder, Node::Leaf(annot_id));
-    }
-}
-
-pub(crate) fn handle_start(gc: &mut GlobalContext, elem: &Content) {
-    if gc.tags.in_artifact.is_some() {
-        // Don't nest artifacts
-        return;
-    }
-
-    let loc = elem.location().unwrap();
-
-    if let Some(artifact) = elem.to_packed::<ArtifactElem>() {
-        let kind = artifact.kind(StyleChain::default());
-        start_artifact(gc, loc, kind);
-        return;
-    } else if let Some(_) = elem.to_packed::<RepeatElem>() {
-        start_artifact(gc, loc, ArtifactKind::Other);
-        return;
-    }
-
-    let tag: Tag = if let Some(pdf_tag) = elem.to_packed::<PdfTagElem>() {
-        let kind = pdf_tag.kind(StyleChain::default());
-        match kind {
-            PdfTagKind::Part => TagKind::Part.into(),
-            _ => todo!(),
-        }
-    } else if let Some(heading) = elem.to_packed::<HeadingElem>() {
-        let level = heading.level().try_into().unwrap_or(NonZeroU32::MAX);
-        let name = heading.body.plain_text().to_string();
-        TagKind::Hn(level, Some(name)).into()
-    } else if let Some(_) = elem.to_packed::<OutlineBody>() {
-        push_stack(gc, loc, StackEntryKind::Outline(OutlineCtx::new()));
-        return;
-    } else if let Some(entry) = elem.to_packed::<OutlineEntry>() {
-        push_stack(gc, loc, StackEntryKind::OutlineEntry(entry.clone()));
-        return;
-    } else if let Some(_) = elem.to_packed::<FigureElem>() {
-        let alt = None; // TODO
-        TagKind::Figure.with_alt_text(alt)
-    } else if let Some(image) = elem.to_packed::<ImageElem>() {
-        let alt = image.alt(StyleChain::default()).map(|s| s.to_string());
-
-        let figure_tag = (gc.tags.parent())
-            .and_then(StackEntryKind::as_standard_mut)
-            .filter(|tag| tag.kind == TagKind::Figure);
-        if let Some(figure_tag) = figure_tag {
-            // Set alt text of outer figure tag, if not present.
-            if figure_tag.alt_text.is_none() {
-                figure_tag.alt_text = alt;
-            }
-            return;
-        } else {
-            TagKind::Figure.with_alt_text(alt)
-        }
-    } else if let Some(_) = elem.to_packed::<FigureCaption>() {
-        TagKind::Caption.into()
-    } else if let Some(table) = elem.to_packed::<TableElem>() {
-        let table_id = gc.tags.next_table_id();
-        let ctx = TableCtx::new(table_id, table.clone());
-        push_stack(gc, loc, StackEntryKind::Table(ctx));
-        return;
-    } else if let Some(cell) = elem.to_packed::<TableCell>() {
-        let parent = gc.tags.stack.last_mut().expect("table");
-        let StackEntryKind::Table(table_ctx) = &mut parent.kind else {
-            unreachable!("expected table")
-        };
-
-        // Only repeated table headers and footer cells are layed out multiple
-        // times. Mark duplicate headers as artifacts, since they have no
-        // semantic meaning in the tag tree, which doesn't use page breaks for
-        // it's semantic structure.
-        if table_ctx.contains(cell) {
-            // TODO: currently the first layouted cell is picked to be part of
-            // the tag tree, for repeating footers this will be the cell on the
-            // first page. Maybe it should be the cell on the last page, but that
-            // would require more changes in the layouting code, or a pre-pass
-            // on the frames to figure out if there are other footers following.
-            start_artifact(gc, loc, ArtifactKind::Other);
-        } else {
-            push_stack(gc, loc, StackEntryKind::TableCell(cell.clone()));
-        }
-        return;
-    } else if let Some(link) = elem.to_packed::<LinkMarker>() {
-        let link_id = gc.tags.next_link_id();
-        push_stack(gc, loc, StackEntryKind::Link(link_id, link.clone()));
-        return;
-    } else {
-        return;
-    };
-
-    push_stack(gc, loc, StackEntryKind::Standard(tag));
-}
-
-fn push_stack(gc: &mut GlobalContext, loc: Location, kind: StackEntryKind) {
-    if !gc.tags.context_supports(&kind) {
-        // TODO: error or warning?
-    }
-
-    gc.tags.stack.push(StackEntry { loc, kind, nodes: Vec::new() });
-}
-
-pub(crate) fn handle_end(gc: &mut GlobalContext, loc: Location) {
-    if let Some((l, _)) = gc.tags.in_artifact {
-        if l == loc {
-            gc.tags.in_artifact = None;
-        }
-        return;
-    }
-
-    let Some(entry) = gc.tags.stack.pop_if(|e| e.loc == loc) else {
-        return;
-    };
-
-    let node = match entry.kind {
-        StackEntryKind::Standard(tag) => TagNode::Group(tag, entry.nodes),
-        StackEntryKind::Outline(ctx) => {
-            let nodes = ctx.build_outline(entry.nodes);
-            TagNode::Group(TagKind::TOC.into(), nodes)
-        }
-        StackEntryKind::OutlineEntry(outline_entry) => {
-            let parent = gc.tags.stack.last_mut().expect("outline");
-            let StackEntryKind::Outline(outline_ctx) = &mut parent.kind else {
-                unreachable!("expected outline")
-            };
-
-            outline_ctx.insert(&mut parent.nodes, outline_entry, entry.nodes);
-
-            return;
-        }
-        StackEntryKind::Table(ctx) => {
-            let summary = ctx.table.summary(StyleChain::default()).map(EcoString::into);
-            let nodes = ctx.build_table(entry.nodes);
-            TagNode::Group(TagKind::Table(summary).into(), nodes)
-        }
-        StackEntryKind::TableCell(cell) => {
-            let parent = gc.tags.stack.last_mut().expect("table");
-            let StackEntryKind::Table(table_ctx) = &mut parent.kind else {
-                unreachable!("expected table")
-            };
-
-            table_ctx.insert(cell, entry.nodes);
-
-            return;
-        }
-        StackEntryKind::Link(_, link) => {
-            let alt = link.alt.as_ref().map(EcoString::to_string);
-            let tag = TagKind::Link.with_alt_text(alt);
-            let mut node = TagNode::Group(tag, entry.nodes);
-            // Wrap link in reference tag, if it's not a url.
-            if let Destination::Position(_) | Destination::Location(_) = link.dest {
-                node = TagNode::Group(TagKind::Reference.into(), vec![node]);
-            }
-            node
-        }
-    };
-
-    gc.tags.push(node);
-}
-
-fn start_artifact(gc: &mut GlobalContext, loc: Location, kind: ArtifactKind) {
-    gc.tags.in_artifact = Some((loc, kind));
-}
-
-fn table_header_scope(scope: TableHeaderScope) -> krilla::tagging::TableHeaderScope {
-    match scope {
-        TableHeaderScope::Both => krilla::tagging::TableHeaderScope::Both,
-        TableHeaderScope::Column => krilla::tagging::TableHeaderScope::Column,
-        TableHeaderScope::Row => krilla::tagging::TableHeaderScope::Row,
-    }
-}
-
-fn artifact_type(kind: ArtifactKind) -> ArtifactType {
-    match kind {
-        ArtifactKind::Header => ArtifactType::Header,
-        ArtifactKind::Footer => ArtifactType::Footer,
-        ArtifactKind::Page => ArtifactType::Page,
-        ArtifactKind::Other => ArtifactType::Other,
-    }
-}

crates/typst-pdf/src/tags/mod.rs

@@ -0,0 +1,467 @@
+use std::cell::OnceCell;
+use std::num::NonZeroU32;
+
+use ecow::EcoString;
+use krilla::configure::Validator;
+use krilla::page::Page;
+use krilla::surface::Surface;
+use krilla::tagging::{
+    ArtifactType, ContentTag, Identifier, Node, SpanTag, TableDataCell, Tag, TagBuilder,
+    TagGroup, TagKind, TagTree,
+};
+use typst_library::diag::SourceResult;
+use typst_library::foundations::{Content, LinkMarker, Packed, StyleChain};
+use typst_library::introspection::Location;
+use typst_library::layout::RepeatElem;
+use typst_library::model::{
+    Destination, FigureCaption, FigureElem, HeadingElem, Outlinable, OutlineBody,
+    OutlineEntry, ParElem, TableCell, TableElem,
+};
+use typst_library::pdf::{ArtifactElem, ArtifactKind, PdfTagElem, PdfTagKind};
+use typst_library::visualize::ImageElem;
+
+use crate::convert::GlobalContext;
+use crate::link::LinkAnnotation;
+use crate::tags::outline::OutlineCtx;
+use crate::tags::table::TableCtx;
+
+mod outline;
+mod table;
+
+pub(crate) fn handle_start(gc: &mut GlobalContext, elem: &Content) -> SourceResult<()> {
+    if gc.tags.in_artifact.is_some() {
+        // Don't nest artifacts
+        return Ok(());
+    }
+
+    let loc = elem.location().expect("elem to be locatable");
+
+    if let Some(artifact) = elem.to_packed::<ArtifactElem>() {
+        let kind = artifact.kind(StyleChain::default());
+        start_artifact(gc, loc, kind);
+        return Ok(());
+    } else if let Some(_) = elem.to_packed::<RepeatElem>() {
+        start_artifact(gc, loc, ArtifactKind::Other);
+        return Ok(());
+    }
+
+    let tag: Tag = if let Some(pdf_tag) = elem.to_packed::<PdfTagElem>() {
+        let kind = pdf_tag.kind(StyleChain::default());
+        match kind {
+            PdfTagKind::Part => TagKind::Part.into(),
+            _ => todo!(),
+        }
+    } else if let Some(heading) = elem.to_packed::<HeadingElem>() {
+        let level = heading.level().try_into().unwrap_or(NonZeroU32::MAX);
+        let name = heading.body.plain_text().to_string();
+        TagKind::Hn(level, Some(name)).into()
+    } else if let Some(_) = elem.to_packed::<OutlineBody>() {
+        push_stack(gc, loc, StackEntryKind::Outline(OutlineCtx::new()))?;
+        return Ok(());
+    } else if let Some(entry) = elem.to_packed::<OutlineEntry>() {
+        push_stack(gc, loc, StackEntryKind::OutlineEntry(entry.clone()))?;
+        return Ok(());
+    } else if let Some(_) = elem.to_packed::<FigureElem>() {
+        let alt = None; // TODO
+        TagKind::Figure.with_alt_text(alt)
+    } else if let Some(image) = elem.to_packed::<ImageElem>() {
+        let alt = image.alt(StyleChain::default()).map(|s| s.to_string());
+
+        let figure_tag = (gc.tags.parent())
+            .and_then(StackEntryKind::as_standard_mut)
+            .filter(|tag| tag.kind == TagKind::Figure);
+        if let Some(figure_tag) = figure_tag {
+            // Set alt text of outer figure tag, if not present.
+            if figure_tag.alt_text.is_none() {
+                figure_tag.alt_text = alt;
+            }
+            return Ok(());
+        } else {
+            TagKind::Figure.with_alt_text(alt)
+        }
+    } else if let Some(_) = elem.to_packed::<FigureCaption>() {
+        TagKind::Caption.into()
+    } else if let Some(table) = elem.to_packed::<TableElem>() {
+        let table_id = gc.tags.next_table_id();
+        let ctx = TableCtx::new(table_id, table.clone());
+        push_stack(gc, loc, StackEntryKind::Table(ctx))?;
+        return Ok(());
+    } else if let Some(cell) = elem.to_packed::<TableCell>() {
+        let table_ctx = gc.tags.parent_table();
+
+        // Only repeated table headers and footer cells are layed out multiple
+        // times. Mark duplicate headers as artifacts, since they have no
+        // semantic meaning in the tag tree, which doesn't use page breaks for
+        // it's semantic structure.
+        if table_ctx.is_some_and(|ctx| ctx.contains(cell)) {
+            // TODO: currently the first layouted cell is picked to be part of
+            // the tag tree, for repeating footers this will be the cell on the
+            // first page. Maybe it should be the cell on the last page, but that
+            // would require more changes in the layouting code, or a pre-pass
+            // on the frames to figure out if there are other footers following.
+            start_artifact(gc, loc, ArtifactKind::Other);
+        } else {
+            push_stack(gc, loc, StackEntryKind::TableCell(cell.clone()))?;
+        }
+        return Ok(());
+    } else if let Some(link) = elem.to_packed::<LinkMarker>() {
+        let link_id = gc.tags.next_link_id();
+        push_stack(gc, loc, StackEntryKind::Link(link_id, link.clone()))?;
+        return Ok(());
+    } else if let Some(_) = elem.to_packed::<ParElem>() {
+        TagKind::P.into()
+    } else {
+        return Ok(());
+    };
+
+    push_stack(gc, loc, StackEntryKind::Standard(tag))?;
+
+    Ok(())
+}
+
+fn push_stack(
+    gc: &mut GlobalContext,
+    loc: Location,
+    kind: StackEntryKind,
+) -> SourceResult<()> {
+    if !gc.tags.context_supports(&kind) {
+        if gc.options.standards.config.validator() == Validator::UA1 {
+            // TODO: error
+        } else {
+            // TODO: warning
+        }
+    }
+
+    gc.tags.stack.push(StackEntry { loc, kind, nodes: Vec::new() });
+
+    Ok(())
+}
+
+pub(crate) fn handle_end(gc: &mut GlobalContext, loc: Location) {
+    if let Some((l, _)) = gc.tags.in_artifact {
+        if l == loc {
+            gc.tags.in_artifact = None;
+        }
+        return;
+    }
+
+    let Some(entry) = gc.tags.stack.pop_if(|e| e.loc == loc) else {
+        return;
+    };
+
+    let node = match entry.kind {
+        StackEntryKind::Standard(tag) => TagNode::Group(tag, entry.nodes),
+        StackEntryKind::Outline(ctx) => {
+            let nodes = ctx.build_outline(entry.nodes);
+            TagNode::Group(TagKind::TOC.into(), nodes)
+        }
+        StackEntryKind::OutlineEntry(outline_entry) => {
+            let parent = gc.tags.stack.last_mut().and_then(|parent| {
+                let ctx = parent.kind.as_outline_mut()?;
+                Some((&mut parent.nodes, ctx))
+            });
+            let Some((parent_nodes, outline_ctx)) = parent else {
+                // PDF/UA compliance of the structure hierarchy is checked
+                // elsewhere. While this doesn't make a lot of sense, just
+                // avoid crashing here.
+                let tag = TagKind::TOCI.into();
+                gc.tags.push(TagNode::Group(tag, entry.nodes));
+                return;
+            };
+
+            outline_ctx.insert(parent_nodes, outline_entry, entry.nodes);
+            return;
+        }
+        StackEntryKind::Table(ctx) => {
+            let summary = ctx.table.summary(StyleChain::default()).map(EcoString::into);
+            let nodes = ctx.build_table(entry.nodes);
+            TagNode::Group(TagKind::Table(summary).into(), nodes)
+        }
+        StackEntryKind::TableCell(cell) => {
+            let Some(table_ctx) = gc.tags.parent_table() else {
+                // PDF/UA compliance of the structure hierarchy is checked
+                // elsewhere. While this doesn't make a lot of sense, just
+                // avoid crashing here.
+                let tag = TagKind::TD(TableDataCell::new()).into();
+                gc.tags.push(TagNode::Group(tag, entry.nodes));
+                return;
+            };
+
+            table_ctx.insert(cell, entry.nodes);
+            return;
+        }
+        StackEntryKind::Link(_, link) => {
+            let alt = link.alt.as_ref().map(EcoString::to_string);
+            let tag = TagKind::Link.with_alt_text(alt);
+            let mut node = TagNode::Group(tag, entry.nodes);
+            // Wrap link in reference tag, if it's not a url.
+            if let Destination::Position(_) | Destination::Location(_) = link.dest {
+                node = TagNode::Group(TagKind::Reference.into(), vec![node]);
+            }
+            node
+        }
+    };
+
+    gc.tags.push(node);
+}
+
+/// Add all annotations that were found in the page frame.
+pub(crate) fn add_annotations(
+    gc: &mut GlobalContext,
+    page: &mut Page,
+    annotations: Vec<LinkAnnotation>,
+) {
+    for annotation in annotations.into_iter() {
+        let LinkAnnotation { id: _, placeholder, alt, rect, quad_points, target } =
+            annotation;
+        let annot = krilla::annotation::Annotation::new_link(
+            krilla::annotation::LinkAnnotation::new(rect, Some(quad_points), target),
+            alt,
+        );
+        let annot_id = page.add_tagged_annotation(annot);
+        gc.tags.init_placeholder(placeholder, Node::Leaf(annot_id));
+    }
+}
+
+pub(crate) struct Tags {
+    /// The intermediary stack of nested tag groups.
+    pub(crate) stack: Vec<StackEntry>,
+    /// A list of placeholders corresponding to a [`TagNode::Placeholder`].
+    pub(crate) placeholders: Vec<OnceCell<Node>>,
+    pub(crate) in_artifact: Option<(Location, ArtifactKind)>,
+    /// Used to group multiple link annotations using quad points.
+    pub(crate) link_id: LinkId,
+    /// Used to generate IDs referenced in table `Headers` attributes.
+    /// The IDs must be document wide unique.
+    pub(crate) table_id: TableId,
+
+    /// The output.
+    pub(crate) tree: Vec<TagNode>,
+}
+
+impl Tags {
+    pub(crate) fn new() -> Self {
+        Self {
+            stack: Vec::new(),
+            placeholders: Vec::new(),
+            in_artifact: None,
+
+            tree: Vec::new(),
+            link_id: LinkId(0),
+            table_id: TableId(0),
+        }
+    }
+
+    pub(crate) fn reserve_placeholder(&mut self) -> Placeholder {
+        let idx = self.placeholders.len();
+        self.placeholders.push(OnceCell::new());
+        Placeholder(idx)
+    }
+
+    pub(crate) fn init_placeholder(&mut self, placeholder: Placeholder, node: Node) {
+        self.placeholders[placeholder.0]
+            .set(node)
+            .map_err(|_| ())
+            .expect("placeholder to be uninitialized");
+    }
+
+    pub(crate) fn take_placeholder(&mut self, placeholder: Placeholder) -> Node {
+        self.placeholders[placeholder.0]
+            .take()
+            .expect("initialized placeholder node")
+    }
+
+    pub(crate) fn parent(&mut self) -> Option<&mut StackEntryKind> {
+        self.stack.last_mut().map(|e| &mut e.kind)
+    }
+
+    pub(crate) fn parent_table(&mut self) -> Option<&mut TableCtx> {
+        self.parent()?.as_table_mut()
+    }
+
+    pub(crate) fn find_parent_link(&self) -> Option<(LinkId, &Packed<LinkMarker>)> {
+        self.stack.iter().rev().find_map(|entry| entry.kind.as_link())
+    }
+
+    pub(crate) fn push(&mut self, node: TagNode) {
+        if let Some(entry) = self.stack.last_mut() {
+            entry.nodes.push(node);
+        } else {
+            self.tree.push(node);
+        }
+    }
+
+    pub(crate) fn build_tree(&mut self) -> TagTree {
+        let children = std::mem::take(&mut self.tree)
+            .into_iter()
+            .map(|node| self.resolve_node(node))
+            .collect::<Vec<_>>();
+        TagTree::from(children)
+    }
+
+    /// Resolves [`Placeholder`] nodes.
+    fn resolve_node(&mut self, node: TagNode) -> Node {
+        match node {
+            TagNode::Group(tag, nodes) => {
+                let children = nodes
+                    .into_iter()
+                    .map(|node| self.resolve_node(node))
+                    .collect::<Vec<_>>();
+                Node::Group(TagGroup::with_children(tag, children))
+            }
+            TagNode::Leaf(identifier) => Node::Leaf(identifier),
+            TagNode::Placeholder(placeholder) => self.take_placeholder(placeholder),
+        }
+    }
+
+    fn context_supports(&self, _tag: &StackEntryKind) -> bool {
+        // TODO: generate using: https://pdfa.org/resource/iso-ts-32005-hierarchical-inclusion-rules/
+        true
+    }
+
+    fn next_link_id(&mut self) -> LinkId {
+        self.link_id.0 += 1;
+        self.link_id
+    }
+
+    fn next_table_id(&mut self) -> TableId {
+        self.table_id.0 += 1;
+        self.table_id
+    }
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) struct TableId(u32);
+
+#[derive(Clone, Copy, PartialEq, Eq, Hash)]
+pub(crate) struct LinkId(u32);
+
+pub(crate) struct StackEntry {
+    pub(crate) loc: Location,
+    pub(crate) kind: StackEntryKind,
+    pub(crate) nodes: Vec<TagNode>,
+}
+
+pub(crate) enum StackEntryKind {
+    Standard(Tag),
+    Outline(OutlineCtx),
+    OutlineEntry(Packed<OutlineEntry>),
+    Table(TableCtx),
+    TableCell(Packed<TableCell>),
+    Link(LinkId, Packed<LinkMarker>),
+}
+
+impl StackEntryKind {
+    pub(crate) fn as_standard_mut(&mut self) -> Option<&mut Tag> {
+        if let Self::Standard(v) = self {
+            Some(v)
+        } else {
+            None
+        }
+    }
+
+    pub(crate) fn as_outline_mut(&mut self) -> Option<&mut OutlineCtx> {
+        if let Self::Outline(v) = self {
+            Some(v)
+        } else {
+            None
+        }
+    }
+
+    pub(crate) fn as_table_mut(&mut self) -> Option<&mut TableCtx> {
+        if let Self::Table(v) = self {
+            Some(v)
+        } else {
+            None
+        }
+    }
+
+    pub(crate) fn as_link(&self) -> Option<(LinkId, &Packed<LinkMarker>)> {
+        if let Self::Link(id, link) = self {
+            Some((*id, link))
+        } else {
+            None
+        }
+    }
+}
+
+#[derive(Clone)]
+pub(crate) enum TagNode {
+    Group(Tag, Vec<TagNode>),
+    Leaf(Identifier),
+    /// Allows inserting a placeholder into the tag tree.
+    /// Currently used for [`krilla::page::Page::add_tagged_annotation`].
+    Placeholder(Placeholder),
+}
+
+#[derive(Clone, Copy)]
+pub(crate) struct Placeholder(usize);
+
+/// Automatically calls [`Surface::end_tagged`] when dropped.
+pub(crate) struct TagHandle<'a, 'b> {
+    surface: &'b mut Surface<'a>,
+}
+
+impl Drop for TagHandle<'_, '_> {
+    fn drop(&mut self) {
+        self.surface.end_tagged();
+    }
+}
+
+impl<'a> TagHandle<'a, '_> {
+    pub(crate) fn surface<'c>(&'c mut self) -> &'c mut Surface<'a> {
+        self.surface
+    }
+}
+
+/// Returns a [`TagHandle`] that automatically calls [`Surface::end_tagged`]
+/// when dropped.
+pub(crate) fn start_marked<'a, 'b>(
+    gc: &mut GlobalContext,
+    surface: &'b mut Surface<'a>,
+) -> TagHandle<'a, 'b> {
+    start_content(gc, surface, ContentTag::Other)
+}
+
+/// Returns a [`TagHandle`] that automatically calls [`Surface::end_tagged`]
+/// when dropped.
+pub(crate) fn start_span<'a, 'b>(
+    gc: &mut GlobalContext,
+    surface: &'b mut Surface<'a>,
+    span: SpanTag,
+) -> TagHandle<'a, 'b> {
+    start_content(gc, surface, ContentTag::Span(span))
+}
+
+fn start_content<'a, 'b>(
+    gc: &mut GlobalContext,
+    surface: &'b mut Surface<'a>,
+    content: ContentTag,
+) -> TagHandle<'a, 'b> {
+    let content = if let Some((_, kind)) = gc.tags.in_artifact {
+        let ty = artifact_type(kind);
+        ContentTag::Artifact(ty)
+    } else if let Some(StackEntryKind::Table(_)) = gc.tags.stack.last().map(|e| &e.kind) {
+        // Mark any direct child of a table as an aritfact. Any real content
+        // will be wrapped inside a `TableCell`.
+        ContentTag::Artifact(ArtifactType::Other)
+    } else {
+        content
+    };
+    let id = surface.start_tagged(content);
+    gc.tags.push(TagNode::Leaf(id));
+    TagHandle { surface }
+}
+
+fn start_artifact(gc: &mut GlobalContext, loc: Location, kind: ArtifactKind) {
+    gc.tags.in_artifact = Some((loc, kind));
+}
+
+fn artifact_type(kind: ArtifactKind) -> ArtifactType {
+    match kind {
+        ArtifactKind::Header => ArtifactType::Header,
+        ArtifactKind::Footer => ArtifactType::Footer,
+        ArtifactKind::Page => ArtifactType::Page,
+        ArtifactKind::Other => ArtifactType::Other,
+    }
+}

crates/typst-pdf/src/tags/outline.rs

@@ -0,0 +1,74 @@
+use krilla::tagging::TagKind;
+use typst_library::foundations::Packed;
+use typst_library::model::OutlineEntry;
+
+use crate::tags::TagNode;
+
+pub(crate) struct OutlineCtx {
+    stack: Vec<OutlineSection>,
+}
+
+impl OutlineCtx {
+    pub(crate) fn new() -> Self {
+        Self { stack: Vec::new() }
+    }
+
+    pub(crate) fn insert(
+        &mut self,
+        outline_nodes: &mut Vec<TagNode>,
+        entry: Packed<OutlineEntry>,
+        nodes: Vec<TagNode>,
+    ) {
+        let expected_len = entry.level.get() - 1;
+        if self.stack.len() < expected_len {
+            self.stack.resize_with(expected_len, OutlineSection::new);
+        } else {
+            while self.stack.len() > expected_len {
+                self.finish_section(outline_nodes);
+            }
+        }
+
+        let section_entry = TagNode::Group(TagKind::TOCI.into(), nodes);
+        self.push(outline_nodes, section_entry);
+    }
+
+    fn finish_section(&mut self, outline_nodes: &mut Vec<TagNode>) {
+        let sub_section = self.stack.pop().unwrap().into_tag();
+        self.push(outline_nodes, sub_section);
+    }
+
+    fn push(&mut self, outline_nodes: &mut Vec<TagNode>, entry: TagNode) {
+        match self.stack.last_mut() {
+            Some(section) => section.push(entry),
+            None => outline_nodes.push(entry),
+        }
+    }
+
+    pub(crate) fn build_outline(
+        mut self,
+        mut outline_nodes: Vec<TagNode>,
+    ) -> Vec<TagNode> {
+        while !self.stack.is_empty() {
+            self.finish_section(&mut outline_nodes);
+        }
+        outline_nodes
+    }
+}
+
+pub(crate) struct OutlineSection {
+    entries: Vec<TagNode>,
+}
+
+impl OutlineSection {
+    const fn new() -> Self {
+        OutlineSection { entries: Vec::new() }
+    }
+
+    fn push(&mut self, entry: TagNode) {
+        self.entries.push(entry);
+    }
+
+    fn into_tag(self) -> TagNode {
+        TagNode::Group(TagKind::TOC.into(), self.entries)
+    }
+}

crates/typst-pdf/src/tags/table.rs

@@ -0,0 +1,330 @@
+use std::num::{NonZeroU32, NonZeroUsize};
+
+use krilla::tagging::{
+    TableCellHeaders, TableCellSpan, TableDataCell, TableHeaderCell, TagBuilder, TagId,
+    TagKind,
+};
+use typst_library::foundations::{Packed, Smart, StyleChain};
+use typst_library::model::{TableCell, TableCellKind, TableElem, TableHeaderScope};
+
+use crate::tags::{TableId, TagNode};
+
+pub(crate) struct TableCtx {
+    pub(crate) id: TableId,
+    pub(crate) table: Packed<TableElem>,
+    rows: Vec<Vec<GridCell>>,
+}
+
+impl TableCtx {
+    pub(crate) fn new(id: TableId, table: Packed<TableElem>) -> Self {
+        Self { id, table: table.clone(), rows: Vec::new() }
+    }
+
+    fn get(&self, x: usize, y: usize) -> Option<&TableCtxCell> {
+        let cell = self.rows.get(y)?.get(x)?;
+        self.resolve_cell(cell)
+    }
+
+    fn get_mut(&mut self, x: usize, y: usize) -> Option<&mut TableCtxCell> {
+        let cell = self.rows.get_mut(y)?.get_mut(x)?;
+        match cell {
+            GridCell::Cell(cell) => {
+                // HACK: Workaround for the second mutable borrow when resolving
+                // the spanned cell.
+                Some(unsafe { std::mem::transmute(cell) })
+            }
+            &mut GridCell::Spanned(x, y) => self.rows[y][x].as_cell_mut(),
+            GridCell::Missing => None,
+        }
+    }
+
+    pub(crate) fn contains(&self, cell: &Packed<TableCell>) -> bool {
+        let x = cell.x(StyleChain::default()).unwrap_or_else(|| unreachable!());
+        let y = cell.y(StyleChain::default()).unwrap_or_else(|| unreachable!());
+        self.get(x, y).is_some()
+    }
+
+    fn resolve_cell<'a>(&'a self, cell: &'a GridCell) -> Option<&'a TableCtxCell> {
+        match cell {
+            GridCell::Cell(cell) => Some(cell),
+            &GridCell::Spanned(x, y) => self.rows[y][x].as_cell(),
+            GridCell::Missing => None,
+        }
+    }
+
+    pub(crate) fn insert(&mut self, cell: Packed<TableCell>, nodes: Vec<TagNode>) {
+        let x = cell.x(StyleChain::default()).unwrap_or_else(|| unreachable!());
+        let y = cell.y(StyleChain::default()).unwrap_or_else(|| unreachable!());
+        let rowspan = cell.rowspan(StyleChain::default());
+        let colspan = cell.colspan(StyleChain::default());
+        let kind = cell.kind(StyleChain::default());
+
+        // Extend the table grid to fit this cell.
+        let required_height = y + rowspan.get();
+        let required_width = x + colspan.get();
+        if self.rows.len() < required_height {
+            self.rows
+                .resize(required_height, vec![GridCell::Missing; required_width]);
+        }
+        let row = &mut self.rows[y];
+        if row.len() < required_width {
+            row.resize_with(required_width, || GridCell::Missing);
+        }
+
+        // Store references to the cell for all spanned cells.
+        for i in y..y + rowspan.get() {
+            for j in x..x + colspan.get() {
+                self.rows[i][j] = GridCell::Spanned(x, y);
+            }
+        }
+
+        self.rows[y][x] = GridCell::Cell(TableCtxCell {
+            x: x as u32,
+            y: y as u32,
+            rowspan,
+            colspan,
+            kind,
+            headers: TableCellHeaders::NONE,
+            nodes,
+        });
+    }
+
+    pub(crate) fn build_table(mut self, mut nodes: Vec<TagNode>) -> Vec<TagNode> {
+        // Table layouting ensures that there are no overlapping cells, and that
+        // any gaps left by the user are filled with empty cells.
+        if self.rows.is_empty() {
+            return nodes;
+        }
+        let height = self.rows.len();
+        let width = self.rows[0].len();
+
+        // Only generate row groups such as `THead`, `TFoot`, and `TBody` if
+        // there are no rows with mixed cell kinds.
+        let mut gen_row_groups = true;
+        let row_kinds = (self.rows.iter())
+            .map(|row| {
+                row.iter()
+                    .filter_map(|cell| self.resolve_cell(cell))
+                    .map(|cell| cell.kind)
+                    .fold(Smart::Auto, |a, b| {
+                        if let Smart::Custom(TableCellKind::Header(_, scope)) = b {
+                            gen_row_groups &= scope == TableHeaderScope::Column;
+                        }
+                        if let (Smart::Custom(a), Smart::Custom(b)) = (a, b) {
+                            gen_row_groups &= a == b;
+                        }
+                        a.or(b)
+                    })
+                    .unwrap_or(TableCellKind::Data)
+            })
+            .collect::<Vec<_>>();
+
+        // Fixup all missing cell kinds.
+        for (row, row_kind) in self.rows.iter_mut().zip(row_kinds.iter().copied()) {
+            let default_kind =
+                if gen_row_groups { row_kind } else { TableCellKind::Data };
+            for cell in row.iter_mut() {
+                let Some(cell) = cell.as_cell_mut() else { continue };
+                cell.kind = cell.kind.or(Smart::Custom(default_kind));
+            }
+        }
+
+        // Explicitly set the headers attribute for cells.
+        for x in 0..width {
+            let mut column_header = None;
+            for y in 0..height {
+                self.resolve_cell_headers(
+                    (x, y),
+                    &mut column_header,
+                    TableHeaderScope::refers_to_column,
+                );
+            }
+        }
+        for y in 0..height {
+            let mut row_header = None;
+            for x in 0..width {
+                self.resolve_cell_headers(
+                    (x, y),
+                    &mut row_header,
+                    TableHeaderScope::refers_to_row,
+                );
+            }
+        }
+
+        let mut chunk_kind = row_kinds[0];
+        let mut row_chunk = Vec::new();
+        for (row, row_kind) in self.rows.into_iter().zip(row_kinds) {
+            let row_nodes = row
+                .into_iter()
+                .filter_map(|cell| {
+                    let cell = cell.into_cell()?;
+                    let span = TableCellSpan {
+                        rows: cell.rowspan.try_into().unwrap_or(NonZeroU32::MAX),
+                        cols: cell.colspan.try_into().unwrap_or(NonZeroU32::MAX),
+                    };
+                    let tag = match cell.unwrap_kind() {
+                        TableCellKind::Header(_, scope) => {
+                            let id = table_cell_id(self.id, cell.x, cell.y);
+                            let scope = table_header_scope(scope);
+                            TagKind::TH(
+                                TableHeaderCell::new(scope)
+                                    .with_span(span)
+                                    .with_headers(cell.headers),
+                            )
+                            .with_id(Some(id))
+                        }
+                        TableCellKind::Footer | TableCellKind::Data => TagKind::TD(
+                            TableDataCell::new()
+                                .with_span(span)
+                                .with_headers(cell.headers),
+                        )
+                        .into(),
+                    };
+
+                    Some(TagNode::Group(tag, cell.nodes))
+                })
+                .collect();
+
+            let row = TagNode::Group(TagKind::TR.into(), row_nodes);
+
+            // Push the `TR` tags directly.
+            if !gen_row_groups {
+                nodes.push(row);
+                continue;
+            }
+
+            // Generate row groups.
+            if !should_group_rows(chunk_kind, row_kind) {
+                let tag = match chunk_kind {
+                    TableCellKind::Header(..) => TagKind::THead,
+                    TableCellKind::Footer => TagKind::TFoot,
+                    TableCellKind::Data => TagKind::TBody,
+                };
+                nodes.push(TagNode::Group(tag.into(), std::mem::take(&mut row_chunk)));
+
+                chunk_kind = row_kind;
+            }
+            row_chunk.push(row);
+        }
+
+        if !row_chunk.is_empty() {
+            let tag = match chunk_kind {
+                TableCellKind::Header(..) => TagKind::THead,
+                TableCellKind::Footer => TagKind::TFoot,
+                TableCellKind::Data => TagKind::TBody,
+            };
+            nodes.push(TagNode::Group(tag.into(), row_chunk));
+        }
+
+        nodes
+    }
+
+    fn resolve_cell_headers<F>(
+        &mut self,
+        (x, y): (usize, usize),
+        current_header: &mut Option<(NonZeroU32, TagId)>,
+        refers_to_dir: F,
+    ) where
+        F: Fn(&TableHeaderScope) -> bool,
+    {
+        let table_id = self.id;
+        let Some(cell) = self.get_mut(x, y) else { return };
+
+        if let Some((prev_level, cell_id)) = current_header.clone() {
+            // The `Headers` attribute is also set for parent headers.
+            let mut is_parent_header = true;
+            if let TableCellKind::Header(level, scope) = cell.unwrap_kind() {
+                if refers_to_dir(&scope) {
+                    is_parent_header = prev_level < level;
+                }
+            }
+
+            if is_parent_header && !cell.headers.ids.contains(&cell_id) {
+                cell.headers.ids.push(cell_id.clone());
+            }
+        }
+
+        if let TableCellKind::Header(level, scope) = cell.unwrap_kind() {
+            if refers_to_dir(&scope) {
+                let tag_id = table_cell_id(table_id, x as u32, y as u32);
+                *current_header = Some((level, tag_id));
+            }
+        }
+    }
+}
+
+#[derive(Clone, Default)]
+enum GridCell {
+    Cell(TableCtxCell),
+    Spanned(usize, usize),
+    #[default]
+    Missing,
+}
+
+impl GridCell {
+    fn as_cell(&self) -> Option<&TableCtxCell> {
+        if let Self::Cell(v) = self {
+            Some(v)
+        } else {
+            None
+        }
+    }
+
+    fn as_cell_mut(&mut self) -> Option<&mut TableCtxCell> {
+        if let Self::Cell(v) = self {
+            Some(v)
+        } else {
+            None
+        }
+    }
+
+    fn into_cell(self) -> Option<TableCtxCell> {
+        if let Self::Cell(v) = self {
+            Some(v)
+        } else {
+            None
+        }
+    }
+}
+
+#[derive(Clone)]
+struct TableCtxCell {
+    x: u32,
+    y: u32,
+    rowspan: NonZeroUsize,
+    colspan: NonZeroUsize,
+    kind: Smart<TableCellKind>,
+    headers: TableCellHeaders,
+    nodes: Vec<TagNode>,
+}
+
+impl TableCtxCell {
+    fn unwrap_kind(&self) -> TableCellKind {
+        self.kind.unwrap_or_else(|| unreachable!())
+    }
+}
+
+fn should_group_rows(a: TableCellKind, b: TableCellKind) -> bool {
+    match (a, b) {
+        (TableCellKind::Header(..), TableCellKind::Header(..)) => true,
+        (TableCellKind::Footer, TableCellKind::Footer) => true,
+        (TableCellKind::Data, TableCellKind::Data) => true,
+        (_, _) => false,
+    }
+}
+
+fn table_cell_id(table_id: TableId, x: u32, y: u32) -> TagId {
+    let mut bytes = [0; 12];
+    bytes[0..4].copy_from_slice(&table_id.0.to_ne_bytes());
+    bytes[4..8].copy_from_slice(&x.to_ne_bytes());
+    bytes[8..12].copy_from_slice(&y.to_ne_bytes());
+    TagId::from_slice(&bytes)
+}
+
+fn table_header_scope(scope: TableHeaderScope) -> krilla::tagging::TableHeaderScope {
+    match scope {
+        TableHeaderScope::Both => krilla::tagging::TableHeaderScope::Both,
+        TableHeaderScope::Column => krilla::tagging::TableHeaderScope::Column,
+        TableHeaderScope::Row => krilla::tagging::TableHeaderScope::Row,
+    }
+}

crates/typst-pdf/src/text.rs

@@ -3,7 +3,6 @@ use std::sync::Arc;
 
 use bytemuck::TransparentWrapper;
 use krilla::surface::{Location, Surface};
-use krilla::tagging::SpanTag;
 use krilla::text::GlyphId;
 use typst_library::diag::{bail, SourceResult};
 use typst_library::layout::Size;
@@ -24,8 +23,7 @@ pub(crate) fn handle_text(
 ) -> SourceResult<()> {
     *gc.languages.entry(t.lang).or_insert(0) += t.glyphs.len();
 
-    let mut handle =
-        tags::start_span(gc, surface, SpanTag::empty().with_actual_text(Some(&t.text)));
+    let mut handle = tags::start_marked(gc, surface);
     let surface = handle.surface();
 
     let font = convert_font(gc, t.font.clone())?;

crates/typst-utils/src/lib.rs

@@ -395,6 +395,10 @@ pub fn default_math_class(c: char) -> Option<MathClass> {
         // https://github.com/typst/typst/issues/5764
         '⟇' => Some(MathClass::Binary),
 
+        // Arabic comma.
+        // https://github.com/latex3/unicode-math/pull/633#issuecomment-2028936135
+        '،' => Some(MathClass::Punctuation),
+
         c => unicode_math_class::class(c),
     }
 }

tests/suite/text/shift.typ

@@ -1,22 +1,89 @@
 // Test sub- and superscript shifts.
 
 --- sub-super ---
+#let sq = box(square(size: 4pt))
 #table(
   columns: 3,
-  [Typo.], [Fallb.], [Synth],
-  [x#super[1]], [x#super[5n]], [x#super[2 #box(square(size: 6pt))]],
-  [x#sub[1]], [x#sub[5n]], [x#sub[2 #box(square(size: 6pt))]],
+  [Typo.], [Fallb.], [Synth.],
+  [x#super[1#sq]], [x#super[5: #sq]], [x#super(typographic: false)[2 #sq]],
+  [x#sub[1#sq]], [x#sub[5: #sq]], [x#sub(typographic: false)[2 #sq]],
 )
 
+--- sub-super-typographic ---
+#set text(size: 20pt)
+// Libertinus Serif supports "subs" and "sups" for `typo` and `sq`, but not for
+// `synth`.
+#let synth = [1,2,3]
+#let typo = [123]
+#let sq = [1#box(square(size: 4pt))2]
+x#super(synth) x#super(typo) x#super(sq) \
+x#sub(synth) x#sub(typo) x#sub(sq)
+
+--- sub-super-italic-compensation ---
+#set text(size: 20pt, style: "italic")
+// Libertinus Serif supports "subs" and "sups" for `typo`, but not for `synth`.
+#let synth = [1,2,3]
+#let typo = [123]
+#let sq = [1#box(square(size: 4pt))2]
+x#super(synth) x#super(typo) x#super(sq) \
+x#sub(synth) x#sub(typo) x#sub(sq)
+
 --- sub-super-non-typographic ---
 #set super(typographic: false, baseline: -0.25em, size: 0.7em)
 n#super[1], n#sub[2], ... n#super[N]
 
 --- super-underline ---
 #set underline(stroke: 0.5pt, offset: 0.15em)
-#underline[The claim#super[\[4\]]] has been disputed. \
-The claim#super[#underline[\[4\]]] has been disputed. \
-It really has been#super(box(text(baseline: 0pt, underline[\[4\]]))) \
+#set super(typographic: false)
+#underline[A#super[4]] B \
+A#super[#underline[4]] B \
+A #underline(super[4]) B \
+#set super(typographic: true)
+#underline[A#super[4]] B \
+A#super[#underline[4]] B \
+A #underline(super[4]) B
+
+--- super-highlight ---
+#set super(typographic: false)
+#highlight[A#super[4]] B \
+A#super[#highlight[4]] B \
+A#super(highlight[4]) \
+#set super(typographic: true)
+#highlight[A#super[4]] B \
+A#super[#highlight[4]] B \
+A#super(highlight[4])
+
+--- super-1em ---
+#set text(size: 10pt)
+#super(context test(1em.to-absolute(), 10pt))
+
+--- long-scripts ---
+|longscript| \
+|#super(typographic: true)[longscript]| \
+|#super(typographic: false)[longscript]| \
+|#sub(typographic: true)[longscript]| \
+|#sub(typographic: false)[longscript]|
+
+--- script-metrics-bundeled-fonts ---
+// Tests whether the script metrics are used properly by synthesizing
+// superscripts and subscripts for all bundled fonts.
+
+#set super(typographic: false)
+#set sub(typographic: false)
+
+#let test(font, weights, styles) = {
+  for weight in weights {
+    for style in styles {
+      text(font: font, weight: weight, style: style)[Xx#super[Xx]#sub[Xx]]
+      linebreak()
+    }
+  }
+}
+
+#test("DejaVu Sans Mono", ("regular", "bold"), ("normal", "oblique"))
+#test("Libertinus Serif", ("regular", "semibold", "bold"), ("normal", "italic"))
+#test("New Computer Modern", ("regular", "bold"), ("normal", "italic"))
+#test("New Computer Modern Math", (400, 450, "bold"), ("normal",))
 
 --- basic-sup-sub html ---
 1#super[st], 2#super[nd], 3#super[rd].