Skip to main content

rustium_pdf/
page.rs

1//! Page primitives: interpreting content streams into glyphs, paths and images.
2//!
3//! The interpreter walks a page's operators maintaining the graphics and text state the PDF
4//! specification defines, and emits flat primitives in **user space** — PDF's y-up coordinate
5//! system with the origin at the media box's lower-left corner. [`Page::page_matrix`] converts
6//! to the y-down device space a rasteriser or a layout consumer wants, applying `/Rotate` and
7//! the crop box in one step.
8
9use std::collections::{HashMap, HashSet};
10use std::sync::Arc;
11
12use crate::content::ContentParser;
13use crate::document::{page_content, Document, PageNode};
14use crate::error::{Error, Result};
15use crate::font::glyph::PathCmd;
16use crate::font::{CodeItem, Font, FontFlags};
17use crate::geom::{Matrix, Point, Rect};
18use crate::object::{text_string, Dict, ObjRef, Object};
19
20/// Nesting limit for form XObjects and Type3 glyph procedures.
21const MAX_DEPTH: usize = 12;
22/// A horizontal gap this many ems wide, on an unchanged baseline, reads as a word break.
23const SPACE_GAP_EM: f32 = 0.12;
24/// Baselines within this fraction of an em count as the same line for gap detection.
25const BASELINE_EPSILON_EM: f32 = 0.10;
26
27/// One glyph placed on the page.
28#[derive(Debug, Clone)]
29pub struct Glyph {
30    /// The text this glyph contributes. Usually one character; ligatures expand to several.
31    ///
32    /// Inside a marked-content sequence that carries `/ActualText`, the document has said what
33    /// the sequence reads as, and that replaces what its glyphs would say one by one: the first
34    /// glyph of the sequence holds the whole replacement and the rest hold nothing. Every glyph
35    /// keeps its own geometry either way.
36    pub text: String,
37    /// The baseline origin, in user space.
38    pub origin: Point,
39    /// The glyph's bounding box in user space: tight around the outline when the font program
40    /// is available, and a nominal em box derived from the advance when it is not.
41    pub bbox: Rect,
42    /// The advance from this glyph's origin to the next, in user space units.
43    pub advance: f32,
44    /// The effective on-page font size: `/Tf` size scaled by the text and current matrices.
45    pub font_size: f32,
46    /// The resource name the font was reached by (`/F1`).
47    pub font_name: String,
48    /// The font's `/BaseFont`.
49    pub base_font: String,
50    /// Typeface properties of the font this glyph came from.
51    pub flags: FontFlags,
52    /// Baseline rotation in radians, counter-clockwise from the positive x-axis.
53    pub rotation: f32,
54    /// True when this glyph was synthesized from a positioning gap rather than read from a
55    /// string, so that a word break the page draws as a gap is still a space in the output.
56    pub is_generated_space: bool,
57    /// The text rendering mode in force (`/Tr`). Mode 3 and 7 are invisible.
58    pub render_mode: i32,
59    /// Fill colour as linear RGB in 0..=1.
60    pub color: [f32; 3],
61    /// Constant fill alpha from the graphics state (`/ca`), in 0..=1.
62    pub alpha: f32,
63    /// Paint order across every primitive on the page. Sorting glyphs, paths and images by
64    /// this reproduces the order the content stream drew them in, which is what a renderer
65    /// needs and what the separate per-type vectors would otherwise lose.
66    pub order: u32,
67
68    /// The font and code this glyph came from, kept so [`Glyph::outline`] can resolve the
69    /// shape on demand. Storing the outline itself would mean tens of thousands of copies of
70    /// paths the font already caches once each.
71    font: Option<Arc<Font>>,
72    code: CodeItem,
73    /// Maps glyph-space outline coordinates to user space.
74    glyph_matrix: Matrix,
75}
76
77impl Glyph {
78    /// Whether the glyph paints anything. Invisible text is what scanned pages put under their
79    /// page image, so extraction keeps it and rendering skips it.
80    pub fn is_visible(&self) -> bool {
81        self.render_mode != 3 && self.render_mode != 7
82    }
83
84    /// The glyph's outline in glyph space, resolved through the font's cache.
85    ///
86    /// `None` for a generated space, a Type3 glyph (whose marks the interpreter already emitted
87    /// as paths) or a font whose program is absent or uninterpretable.
88    pub fn outline(&self) -> Option<Arc<crate::font::glyph::Outline>> {
89        if self.is_generated_space {
90            return None;
91        }
92        self.font.as_ref()?.outline(&self.code)
93    }
94
95    /// Maps this glyph's outline coordinates into user space.
96    pub fn outline_matrix(&self) -> Matrix {
97        self.glyph_matrix
98    }
99
100    /// The character code this glyph was selected by, as it appeared in the content stream.
101    ///
102    /// Useful when [`Glyph::text`] is empty: the code plus the font is what identifies which
103    /// mapping is missing.
104    pub fn code(&self) -> u32 {
105        self.code.code
106    }
107
108    /// The glyph selector: the code itself for a simple font, the CID for a composite one.
109    pub fn cid(&self) -> u32 {
110        self.code.cid
111    }
112}
113
114/// A filled and/or stroked path.
115#[derive(Debug, Clone)]
116pub struct PathItem {
117    /// Path commands in user space.
118    pub cmds: Vec<PathCmd>,
119    pub bbox: Rect,
120    pub fill: Option<[f32; 3]>,
121    pub stroke: Option<[f32; 3]>,
122    /// Stroke width in user space units.
123    pub line_width: f32,
124    /// True when the fill uses the even-odd rule rather than nonzero winding.
125    pub even_odd: bool,
126    /// Constant alphas from the graphics state (`/ca` and `/CA`), in 0..=1.
127    pub fill_alpha: f32,
128    pub stroke_alpha: f32,
129    /// Paint order; see [`Glyph::order`].
130    pub order: u32,
131}
132
133/// The pixel payload of an image, as far as the byte-level filters could take it.
134#[derive(Debug, Clone)]
135pub enum ImageData {
136    /// Fully decoded samples, row-major, `bits_per_component` per component.
137    Raw {
138        bits_per_component: u8,
139        components: u8,
140        data: Vec<u8>,
141    },
142    /// A codec payload the byte filters do not decode (`DCTDecode`, `JPXDecode`, the fax and
143    /// JBIG2 filters); `data` is that codec's own bitstream.
144    Encoded { filter: String, data: Vec<u8> },
145}
146
147/// An image drawn onto the page.
148#[derive(Debug, Clone)]
149pub struct ImageItem {
150    /// The XObject resource name, or `"inline"` for a `BI ... EI` image.
151    pub name: String,
152    /// Maps the image's unit square onto the page, in user space. The image's first row is at
153    /// the top of the unit square, so this matrix already includes the y flip.
154    pub ctm: Matrix,
155    pub bbox: Rect,
156    pub width: u32,
157    pub height: u32,
158    /// True for a stencil mask (`/ImageMask`), which paints the fill colour through 1-bit data.
159    pub is_mask: bool,
160    /// Bits per component and component count, known without touching the pixels.
161    pub bits_per_component: u8,
162    pub components: u8,
163    /// The colour a stencil mask paints through, and the constant alpha in force.
164    pub fill: [f32; 3],
165    pub alpha: f32,
166    /// Paint order; see [`Glyph::order`].
167    pub order: u32,
168    source: ImageSource,
169}
170
171/// Where an image's pixels come from.
172///
173/// Image XObjects are referenced rather than carried: a page of photographs holds tens of
174/// megabytes of samples, and a layout pass that only needs each image's box should not pay for
175/// them. Inline images are already bounded by the content stream, so they are kept as decoded.
176#[derive(Debug, Clone)]
177enum ImageSource {
178    Object(ObjRef),
179    Inline(Arc<ImageData>),
180}
181
182impl ImageItem {
183    /// Decodes this image's pixels, reading them from the document if they were not retained.
184    pub fn decode(&self, doc: &Document) -> Result<ImageData> {
185        match &self.source {
186            ImageSource::Inline(data) => Ok((**data).clone()),
187            ImageSource::Object(r) => {
188                let obj = doc.resolve(&Object::Ref(*r));
189                let stream = obj.as_stream().ok_or_else(|| {
190                    Error::Parse(format!("image object {} is not a stream", r.num))
191                })?;
192                let decoded = doc.file.decode_stream(stream)?;
193                Ok(match decoded.image_filter {
194                    Some(filter) => ImageData::Encoded {
195                        filter,
196                        data: decoded.data,
197                    },
198                    None => ImageData::Raw {
199                        bits_per_component: self.bits_per_component,
200                        components: self.components,
201                        data: decoded.data,
202                    },
203                })
204            }
205        }
206    }
207}
208
209/// A page's primitives, with the geometry needed to place them.
210pub struct Page {
211    pub index: usize,
212    pub media_box: Rect,
213    pub crop_box: Rect,
214    /// Clockwise display rotation in degrees: 0, 90, 180 or 270.
215    pub rotation: i32,
216    pub glyphs: Vec<Glyph>,
217    pub paths: Vec<PathItem>,
218    pub images: Vec<ImageItem>,
219}
220
221impl Page {
222    pub(crate) fn build(doc: &Document, node: &PageNode, index: usize) -> Result<Page> {
223        let content = page_content(doc, &node.dict);
224        let mut interp = Interpreter::new(doc);
225        interp.run(&content, &node.resources, State::new(node.crop_box), 0);
226
227        Ok(Page {
228            index,
229            media_box: node.media_box,
230            crop_box: node.crop_box,
231            rotation: node.rotation,
232            glyphs: interp.glyphs,
233            paths: interp.paths,
234            images: interp.images,
235        })
236    }
237
238    /// The page's displayed width in points, after rotation.
239    pub fn width(&self) -> f32 {
240        if self.rotation % 180 == 0 {
241            self.crop_box.width()
242        } else {
243            self.crop_box.height()
244        }
245    }
246
247    /// The page's displayed height in points, after rotation.
248    pub fn height(&self) -> f32 {
249        if self.rotation % 180 == 0 {
250            self.crop_box.height()
251        } else {
252            self.crop_box.width()
253        }
254    }
255
256    /// Maps user space to y-down device space at `scale` pixels per point, with the origin at
257    /// the top-left of the displayed page and `/Rotate` applied.
258    pub fn page_matrix(&self, scale: f32) -> Matrix {
259        // Shift the crop box to the origin, flip y, then rotate about the resulting page.
260        let to_origin = Matrix::translate(-self.crop_box.x0, -self.crop_box.y0);
261        let w = self.crop_box.width();
262        let h = self.crop_box.height();
263        let flip = Matrix::new(1.0, 0.0, 0.0, -1.0, 0.0, h);
264        let rotate = match self.rotation.rem_euclid(360) {
265            90 => Matrix::new(0.0, 1.0, -1.0, 0.0, h, 0.0),
266            180 => Matrix::new(-1.0, 0.0, 0.0, -1.0, w, h),
267            270 => Matrix::new(0.0, -1.0, 1.0, 0.0, 0.0, w),
268            _ => Matrix::IDENTITY,
269        };
270        to_origin
271            .concat(&flip)
272            .concat(&rotate)
273            .concat(&Matrix::scale(scale, scale))
274    }
275
276    /// Whether this page looks like a scan: a page-sized image and no text worth speaking of.
277    ///
278    /// Reading a scan needs OCR, which is out of scope — but a caller that cannot tell a scan
279    /// from a failed extraction reports an empty page as success, and a user who uploaded a
280    /// photocopied paper is told nothing at all. Detecting the case costs a comparison against
281    /// geometry already computed, and lets the caller say why it produced nothing.
282    ///
283    /// A page carrying an invisible OCR text layer is *not* reported as scanned: its text is
284    /// real and extraction works, which is the whole point of that layer.
285    pub fn is_likely_scanned(&self) -> bool {
286        const MIN_COVERAGE: f32 = 0.5;
287        const MAX_GLYPHS_PER_PAGE: usize = 32;
288
289        if self
290            .glyphs
291            .iter()
292            .filter(|g| !g.text.trim().is_empty())
293            .count()
294            > MAX_GLYPHS_PER_PAGE
295        {
296            return false;
297        }
298        let page = self.crop_box;
299        let area = page.width() * page.height();
300        if area <= 0.0 {
301            return false;
302        }
303        // One image covering most of the page, rather than the total over many, so that a
304        // figure-heavy page with little text is not mistaken for a scan.
305        self.images.iter().any(|img| {
306            let visible = img.bbox.intersect(&page);
307            !visible.is_empty() && (visible.width() * visible.height()) / area >= MIN_COVERAGE
308        })
309    }
310
311    /// The page's text in content-stream order, with soft hyphens removed.
312    ///
313    /// Content order is the order operators appear, which is not always reading order; callers
314    /// that need reading order sort [`Page::glyphs`] by geometry themselves.
315    pub fn text(&self) -> String {
316        let mut out = String::new();
317        let mut prev: Option<&Glyph> = None;
318        // A glyph with no text — unmapped, or silenced by `/ActualText` — contributes nothing,
319        // a line break included: one at the head of a line would otherwise break it twice, once
320        // for itself and once for the first glyph that does say something.
321        for g in self.glyphs.iter().filter(|g| !g.text.is_empty()) {
322            // A content stream carries no line breaks: a new line is just a glyph placed at a
323            // different baseline. Concatenating blindly fuses the last word of one line onto
324            // the first of the next — "of" + "the" becomes "ofthe" — which silently destroys
325            // the commonest words in the document.
326            if let Some(p) = prev {
327                if starts_new_line(p, g) {
328                    out.push('\n');
329                }
330            }
331            out.push_str(&g.text);
332            prev = Some(g);
333        }
334        out
335    }
336}
337
338/// Whether `g` begins a new line relative to the glyph before it.
339///
340/// Judged geometrically rather than from the operators, because `Td`, `TD`, `T*`, `Tm` and a
341/// fresh `BT` can all start a line, and plenty of producers use `Tm` for every single line.
342fn starts_new_line(prev: &Glyph, g: &Glyph) -> bool {
343    let size = prev.font_size.max(g.font_size);
344    if size <= 0.0 {
345        return false;
346    }
347    // Rotated runs are compared along their own baseline direction, so a rotated column does
348    // not read as one break per glyph.
349    if (prev.rotation - g.rotation).abs() > 0.01 {
350        return true;
351    }
352    let (dx, dy) = (g.origin.x - prev.origin.x, g.origin.y - prev.origin.y);
353    let (cos, sin) = (prev.rotation.cos(), prev.rotation.sin());
354    let along = dx * cos + dy * sin;
355    let across = -dx * sin + dy * cos;
356
357    // A baseline shift of a third of an em is a new line; so is any backward jump larger than
358    // one em, which is how a wrapped line returns to the left margin.
359    across.abs() > size * 0.55 || along < -size
360}
361
362// ---- interpreter ----------------------------------------------------------------------------
363
364/// The graphics state, saved and restored by `q`/`Q`.
365#[derive(Clone)]
366struct State {
367    ctm: Matrix,
368    clip: Rect,
369    fill: [f32; 3],
370    stroke: [f32; 3],
371    line_width: f32,
372    /// Number of components in the current fill colour space, to interpret `sc`/`scn`.
373    fill_components: usize,
374    stroke_components: usize,
375    /// Constant alphas from `/ca` and `/CA`.
376    fill_alpha: f32,
377    stroke_alpha: f32,
378    // Text state persists across BT/ET, so it lives here rather than in the text object.
379    font: Option<Arc<Font>>,
380    font_name: String,
381    font_size: f32,
382    char_spacing: f32,
383    word_spacing: f32,
384    /// `/Tz` as a plain factor, not a percentage.
385    horizontal_scale: f32,
386    leading: f32,
387    rise: f32,
388    render_mode: i32,
389}
390
391impl State {
392    fn new(clip: Rect) -> State {
393        State {
394            ctm: Matrix::IDENTITY,
395            clip,
396            fill: [0.0; 3],
397            stroke: [0.0; 3],
398            line_width: 1.0,
399            fill_components: 1,
400            stroke_components: 1,
401            fill_alpha: 1.0,
402            stroke_alpha: 1.0,
403            font: None,
404            font_name: String::new(),
405            font_size: 0.0,
406            char_spacing: 0.0,
407            word_spacing: 0.0,
408            horizontal_scale: 1.0,
409            leading: 0.0,
410            rise: 0.0,
411            render_mode: 0,
412        }
413    }
414}
415
416/// Where the previous glyph ended, for synthesizing word breaks.
417#[derive(Clone, Copy)]
418struct PenTrail {
419    end: Point,
420    baseline_y: f32,
421    size: f32,
422}
423
424struct Interpreter<'a> {
425    doc: &'a Document,
426    glyphs: Vec<Glyph>,
427    paths: Vec<PathItem>,
428    images: Vec<ImageItem>,
429    /// Fonts keyed by object number, so a font shared by many pages parses once per page build.
430    font_cache: HashMap<u32, Arc<Font>>,
431    /// Form XObjects currently being executed, to stop a self-referential form.
432    active_forms: HashSet<u32>,
433    trail: Option<PenTrail>,
434    /// Whether the text most recently emitted ended in whitespace, so a gap after it does not
435    /// earn a second space. Glyphs silenced by an `/ActualText` span leave it alone.
436    last_was_space: bool,
437    /// One entry per open marked-content sequence (`BMC`/`BDC`), true for the one that opened
438    /// `span`. Kept on the interpreter rather than in `run` because a form XObject invoked
439    /// inside a sequence is part of it.
440    marked: Vec<bool>,
441    /// The `/ActualText` replacement in force, if any.
442    span: Option<ActualText>,
443    /// Monotonic paint-order counter, shared by every primitive type.
444    order: u32,
445}
446
447/// An open marked-content sequence whose `/ActualText` replaces the text of the glyphs in it.
448///
449/// Producers use it where a glyph cannot speak for itself — Chromium's PDF backend ships
450/// ligatures and some digits with no `/ToUnicode` entry and only this to say what they are —
451/// and where what is drawn differs from what is meant, such as a hyphen at a line break.
452struct ActualText {
453    /// The replacement, until the first glyph of the sequence takes it; empty from then on.
454    /// Empty from the start when the document declares that the glyphs carry no text.
455    pending: String,
456}
457
458/// The state of the current text object, reset by `BT`.
459struct TextState {
460    matrix: Matrix,
461    line_matrix: Matrix,
462}
463
464impl<'a> Interpreter<'a> {
465    fn new(doc: &'a Document) -> Self {
466        Interpreter {
467            doc,
468            glyphs: Vec::new(),
469            paths: Vec::new(),
470            images: Vec::new(),
471            font_cache: HashMap::new(),
472            active_forms: HashSet::new(),
473            trail: None,
474            last_was_space: false,
475            marked: Vec::new(),
476            span: None,
477            order: 0,
478        }
479    }
480
481    /// Opens a marked-content sequence. `properties` is the `BDC` operand — an inline
482    /// dictionary or a name into the `/Properties` resources — and absent for `BMC`.
483    fn begin_marked(&mut self, properties: Option<&Object>, resources: &Dict) {
484        // Sequences nest, and the outermost `/ActualText` speaks for everything inside it, so
485        // one that opens while another is in force changes nothing.
486        let replacement = match properties {
487            Some(props) if self.span.is_none() => {
488                let dict = match props {
489                    Object::Name(name) => self
490                        .doc
491                        .dict_get(resources, "Properties")
492                        .and_then(|p| p.as_dict().and_then(|d| self.doc.dict_get(d, name))),
493                    other => Some(self.doc.resolve(other)),
494                };
495                dict.and_then(|d| self.doc.dict_get(d.as_dict()?, "ActualText"))
496                    .and_then(|o| o.as_string().map(text_string))
497            }
498            _ => None,
499        };
500        self.marked.push(replacement.is_some());
501        if let Some(text) = replacement {
502            // Soft hyphens are no more content here than in a glyph's own mapping.
503            //
504            // A line break in the replacement becomes a space. Chromium tags space glyphs with
505            // an `/ActualText` of a line feed wherever the HTML it printed had a block or
506            // `<br>` boundary, and those fall in the middle of a visual line as often as at its
507            // end — "yi ding ( name@host )" carries four. Lines here are a matter of geometry,
508            // as everywhere else in this module; what the tag reliably says is that the glyph
509            // is whitespace.
510            //
511            // Every other kind of whitespace becomes a space for the same reason. Springer's
512            // typesetter tags ordinary space glyphs with a tab after a list label
513            // ("1.<tab>Lahiry") and with a no-break space wherever a line must not break
514            // ("et<nbsp>al."). Both say how the line was laid out, not what it reads, and a
515            // consumer splitting on spaces would otherwise see the label fused to its entry.
516            // Its other layout marks go the same way. Control characters (it tags the gap in a
517            // two-column list with U+0007 and the one before an equation number with U+0008)
518            // are spaces too. Marks with no width — a zero-width space where a URL may break,
519            // a word joiner, a left-to-right or right-to-left mark — are dropped like the soft
520            // hyphen they resemble. A non-breaking hyphen reads as a hyphen.
521            let pending = text
522                .chars()
523                .filter(|&c| {
524                    !matches!(
525                        c,
526                        '\u{00AD}' | '\u{200B}' | '\u{200E}' | '\u{200F}' | '\u{2060}' | '\u{FEFF}'
527                    )
528                })
529                .map(|c| match c {
530                    '\u{2011}' => '-',
531                    c if c.is_whitespace() || c.is_control() => ' ',
532                    c => c,
533                })
534                .collect();
535            self.span = Some(ActualText { pending });
536        }
537    }
538
539    /// Closes the innermost marked-content sequence opened at or above `floor`, the depth the
540    /// current content stream started at: a stream cannot close a sequence its caller opened.
541    fn end_marked(&mut self, floor: usize) {
542        if self.marked.len() > floor && self.marked.pop() == Some(true) {
543            // A replacement no glyph claimed has no geometry to attach to, and is dropped.
544            self.span = None;
545        }
546    }
547
548    fn run(&mut self, content: &[u8], resources: &Dict, initial: State, depth: usize) {
549        if depth > MAX_DEPTH {
550            return;
551        }
552        let marked_floor = self.marked.len();
553        let mut stack: Vec<State> = Vec::new();
554        let mut gs = initial;
555        let mut text = TextState {
556            matrix: Matrix::IDENTITY,
557            line_matrix: Matrix::IDENTITY,
558        };
559        // The path under construction, in user space, plus the point a `h` closes back to.
560        let mut path: Vec<PathCmd> = Vec::new();
561        let mut subpath_start = Point::default();
562        let mut current = Point::default();
563        let mut pending_clip: Option<bool> = None;
564
565        for op in ContentParser::new(content) {
566            let n = |i: usize| op.operands.get(i).and_then(|o| o.as_f32());
567            match op.operator.as_str() {
568                // ---- graphics state ----
569                "q" => stack.push(gs.clone()),
570                "Q" => {
571                    if let Some(prev) = stack.pop() {
572                        gs = prev;
573                    }
574                }
575                "cm" => {
576                    if let (Some(a), Some(b), Some(c), Some(d), Some(e), Some(f)) =
577                        (n(0), n(1), n(2), n(3), n(4), n(5))
578                    {
579                        gs.ctm = Matrix::new(a, b, c, d, e, f).concat(&gs.ctm);
580                    }
581                }
582                "w" => {
583                    if let Some(v) = n(0) {
584                        gs.line_width = v;
585                    }
586                }
587                "gs" => {
588                    if let Some(name) = op.operands.first().and_then(|o| o.as_name()) {
589                        self.apply_ext_gstate(resources, name, &mut gs);
590                    }
591                }
592
593                // ---- colour ----
594                "g" | "G" => self.set_color(&mut gs, op.operator == "g", &op.operands, 1),
595                "rg" | "RG" => self.set_color(&mut gs, op.operator == "rg", &op.operands, 3),
596                "k" | "K" => self.set_color(&mut gs, op.operator == "k", &op.operands, 4),
597                "cs" | "CS" => {
598                    let comps = self.colorspace_components(resources, &op.operands);
599                    if op.operator == "cs" {
600                        gs.fill_components = comps;
601                        gs.fill = [0.0; 3];
602                    } else {
603                        gs.stroke_components = comps;
604                        gs.stroke = [0.0; 3];
605                    }
606                }
607                "sc" | "scn" | "SC" | "SCN" => {
608                    let is_fill = op.operator.starts_with('s');
609                    // A pattern operand carries a name and no usable colour; leave the previous
610                    // one in place rather than painting black.
611                    let numeric = op.operands.iter().filter_map(|o| o.as_f32()).count();
612                    if numeric > 0 {
613                        // The space declared by `cs`/`CS` says how to read the operands. A
614                        // producer that disagrees with its own declaration is trusted on the
615                        // operands it actually wrote, since that is what it meant to paint.
616                        let declared = if is_fill {
617                            gs.fill_components
618                        } else {
619                            gs.stroke_components
620                        };
621                        let components = if (1..=numeric).contains(&declared) {
622                            declared
623                        } else {
624                            numeric
625                        };
626                        self.set_color(&mut gs, is_fill, &op.operands, components);
627                    }
628                }
629
630                // ---- path construction ----
631                "m" => {
632                    if let (Some(x), Some(y)) = (n(0), n(1)) {
633                        current = gs.ctm.apply(Point::new(x, y));
634                        subpath_start = current;
635                        path.push(PathCmd::MoveTo(current));
636                    }
637                }
638                "l" => {
639                    if let (Some(x), Some(y)) = (n(0), n(1)) {
640                        current = gs.ctm.apply(Point::new(x, y));
641                        path.push(PathCmd::LineTo(current));
642                    }
643                }
644                "c" => {
645                    if let (Some(a), Some(b), Some(c), Some(d), Some(e), Some(f)) =
646                        (n(0), n(1), n(2), n(3), n(4), n(5))
647                    {
648                        let c1 = gs.ctm.apply(Point::new(a, b));
649                        let c2 = gs.ctm.apply(Point::new(c, d));
650                        current = gs.ctm.apply(Point::new(e, f));
651                        path.push(PathCmd::CurveTo(c1, c2, current));
652                    }
653                }
654                "v" => {
655                    // The first control point is the current point.
656                    if let (Some(c), Some(d), Some(e), Some(f)) = (n(0), n(1), n(2), n(3)) {
657                        let c2 = gs.ctm.apply(Point::new(c, d));
658                        let end = gs.ctm.apply(Point::new(e, f));
659                        path.push(PathCmd::CurveTo(current, c2, end));
660                        current = end;
661                    }
662                }
663                "y" => {
664                    // The second control point is the endpoint.
665                    if let (Some(a), Some(b), Some(e), Some(f)) = (n(0), n(1), n(2), n(3)) {
666                        let c1 = gs.ctm.apply(Point::new(a, b));
667                        let end = gs.ctm.apply(Point::new(e, f));
668                        path.push(PathCmd::CurveTo(c1, end, end));
669                        current = end;
670                    }
671                }
672                "h" => {
673                    path.push(PathCmd::Close);
674                    current = subpath_start;
675                }
676                "re" => {
677                    if let (Some(x), Some(y), Some(w), Some(h)) = (n(0), n(1), n(2), n(3)) {
678                        let p0 = gs.ctm.apply(Point::new(x, y));
679                        let p1 = gs.ctm.apply(Point::new(x + w, y));
680                        let p2 = gs.ctm.apply(Point::new(x + w, y + h));
681                        let p3 = gs.ctm.apply(Point::new(x, y + h));
682                        path.extend([
683                            PathCmd::MoveTo(p0),
684                            PathCmd::LineTo(p1),
685                            PathCmd::LineTo(p2),
686                            PathCmd::LineTo(p3),
687                            PathCmd::Close,
688                        ]);
689                        subpath_start = p0;
690                        current = p0;
691                    }
692                }
693
694                // ---- path painting ----
695                "n" | "f" | "F" | "f*" | "S" | "s" | "B" | "B*" | "b" | "b*" => {
696                    let o = op.operator.as_str();
697                    if matches!(o, "s" | "b" | "b*") {
698                        path.push(PathCmd::Close);
699                    }
700                    let even_odd = o.ends_with('*');
701                    let fills = matches!(o, "f" | "F" | "f*" | "B" | "B*" | "b" | "b*");
702                    let strokes = matches!(o, "S" | "s" | "B" | "B*" | "b" | "b*");
703                    // `W` names the path just painted, so the clip region must be measured
704                    // before the path is moved into the emitted item.
705                    let region = pending_clip.take().map(|_| bounds(&path));
706                    if !path.is_empty() && (fills || strokes) {
707                        let bbox = bounds(&path);
708                        let order = self.next_order();
709                        self.paths.push(PathItem {
710                            cmds: std::mem::take(&mut path),
711                            bbox,
712                            fill: fills.then_some(gs.fill),
713                            stroke: strokes.then_some(gs.stroke),
714                            // Line width is a user-space quantity scaled by the CTM.
715                            line_width: gs.line_width * gs.ctm.x_scale().max(gs.ctm.y_scale()),
716                            even_odd,
717                            fill_alpha: gs.fill_alpha,
718                            stroke_alpha: gs.stroke_alpha,
719                            order,
720                        });
721                    }
722                    // `W` takes effect only once the path is painted or discarded. The clip is
723                    // tracked as a bounding rectangle, which over-covers a non-rectangular
724                    // region — callers use it to reject content, never to include it.
725                    if let Some(region) = region {
726                        if !region.is_empty() {
727                            gs.clip = gs.clip.intersect(&region);
728                        }
729                    }
730                    path.clear();
731                }
732                "W" => pending_clip = Some(false),
733                "W*" => pending_clip = Some(true),
734
735                // ---- text objects ----
736                "BT" => {
737                    text.matrix = Matrix::IDENTITY;
738                    text.line_matrix = Matrix::IDENTITY;
739                    // The pen trail deliberately survives BT/ET. A text object boundary says
740                    // nothing about the page: producers routinely wrap every table cell, and
741                    // sometimes every word, in its own BT. Clearing here loses the gap between
742                    // them and fuses adjacent cells into one token. Geometry decides instead —
743                    // a different baseline is a line break, a wide gap on one is a space.
744                }
745                "ET" => {}
746                "Tc" => gs.char_spacing = n(0).unwrap_or(0.0),
747                "Tw" => gs.word_spacing = n(0).unwrap_or(0.0),
748                "Tz" => gs.horizontal_scale = n(0).unwrap_or(100.0) / 100.0,
749                "TL" => gs.leading = n(0).unwrap_or(0.0),
750                "Ts" => gs.rise = n(0).unwrap_or(0.0),
751                "Tr" => {
752                    gs.render_mode =
753                        op.operands.first().and_then(|o| o.as_int()).unwrap_or(0) as i32
754                }
755                "Tf" => {
756                    gs.font_size = n(1).unwrap_or(0.0);
757                    if let Some(name) = op.operands.first().and_then(|o| o.as_name()) {
758                        gs.font_name = name.to_string();
759                        gs.font = self.font_for(resources, name);
760                    }
761                }
762                "Td" => {
763                    if let (Some(tx), Some(ty)) = (n(0), n(1)) {
764                        text.line_matrix = Matrix::translate(tx, ty).concat(&text.line_matrix);
765                        text.matrix = text.line_matrix;
766                    }
767                }
768                "TD" => {
769                    if let (Some(tx), Some(ty)) = (n(0), n(1)) {
770                        gs.leading = -ty;
771                        text.line_matrix = Matrix::translate(tx, ty).concat(&text.line_matrix);
772                        text.matrix = text.line_matrix;
773                    }
774                }
775                "Tm" => {
776                    if let (Some(a), Some(b), Some(c), Some(d), Some(e), Some(f)) =
777                        (n(0), n(1), n(2), n(3), n(4), n(5))
778                    {
779                        text.line_matrix = Matrix::new(a, b, c, d, e, f);
780                        text.matrix = text.line_matrix;
781                    }
782                }
783                "T*" => next_line(&mut text, gs.leading),
784                "Tj" => {
785                    if let Some(Object::String(s)) = op.operands.first() {
786                        let s = s.clone();
787                        self.show(&s, &gs, &mut text, resources, depth);
788                    }
789                }
790                "'" => {
791                    next_line(&mut text, gs.leading);
792                    if let Some(Object::String(s)) = op.operands.first() {
793                        let s = s.clone();
794                        self.show(&s, &gs, &mut text, resources, depth);
795                    }
796                }
797                "\"" => {
798                    // `aw ac string "`: sets word and char spacing, then shows on a new line.
799                    gs.word_spacing = n(0).unwrap_or(gs.word_spacing);
800                    gs.char_spacing = n(1).unwrap_or(gs.char_spacing);
801                    next_line(&mut text, gs.leading);
802                    if let Some(Object::String(s)) = op.operands.get(2) {
803                        let s = s.clone();
804                        self.show(&s, &gs, &mut text, resources, depth);
805                    }
806                }
807                "TJ" => {
808                    let Some(Object::Array(items)) = op.operands.first().cloned() else {
809                        continue;
810                    };
811                    for item in items {
812                        match item {
813                            Object::String(s) => self.show(&s, &gs, &mut text, resources, depth),
814                            other => {
815                                if let Some(adj) = other.as_f32() {
816                                    // A positive number moves left, hence the negation.
817                                    let tx = -adj / 1000.0 * gs.font_size * gs.horizontal_scale;
818                                    text.matrix = Matrix::translate(tx, 0.0).concat(&text.matrix);
819                                }
820                            }
821                        }
822                    }
823                }
824
825                // ---- XObjects and inline images ----
826                "Do" => {
827                    if let Some(name) = op.operands.first().and_then(|o| o.as_name()) {
828                        let name = name.to_string();
829                        self.do_xobject(&name, resources, &gs, depth);
830                    }
831                }
832                "BI" => {
833                    if let (Some(dict), Some(data)) = (
834                        op.operands.first().and_then(|o| o.as_dict()),
835                        op.inline_data.as_ref(),
836                    ) {
837                        let dict = dict.clone();
838                        let data = data.clone();
839                        self.record_inline_image(&dict, &data, &gs, resources);
840                    }
841                }
842
843                // ---- marked content ----
844                "BMC" => self.begin_marked(None, resources),
845                "BDC" => {
846                    self.begin_marked(Some(op.operands.get(1).unwrap_or(&Object::Null)), resources)
847                }
848                "EMC" => self.end_marked(marked_floor),
849                _ => {}
850            }
851        }
852        // Sequences must balance within a stream; one left open by a damaged stream ends here
853        // rather than swallowing the text of everything drawn afterwards.
854        while self.marked.len() > marked_floor {
855            self.end_marked(marked_floor);
856        }
857    }
858
859    // ---- text ---------------------------------------------------------------------------
860
861    /// Shows one string, emitting a glyph per character code and advancing the text matrix.
862    fn show(
863        &mut self,
864        bytes: &[u8],
865        gs: &State,
866        text: &mut TextState,
867        resources: &Dict,
868        depth: usize,
869    ) {
870        let Some(font) = gs.font.clone() else {
871            return;
872        };
873        for item in font.decode(bytes) {
874            // The text rendering matrix places glyph space on the page:
875            // [size*Th, 0, 0, size, 0, rise] x Tm x CTM
876            let param = Matrix::new(
877                gs.font_size * gs.horizontal_scale,
878                0.0,
879                0.0,
880                gs.font_size,
881                0.0,
882                gs.rise,
883            );
884            let trm = param.concat(&text.matrix).concat(&gs.ctm);
885
886            let advance_text = (item.width / 1000.0 * gs.font_size
887                + gs.char_spacing
888                + if item.is_word_space {
889                    gs.word_spacing
890                } else {
891                    0.0
892                })
893                * gs.horizontal_scale;
894
895            // The advance is a text-space vector, so it reaches user space through Tm and the
896            // CTM — but not through `param`, which would apply the font size a second time.
897            let text_to_user = text.matrix.concat(&gs.ctm);
898            self.emit_glyph(&font, &item, &trm, &text_to_user, gs, advance_text);
899
900            if font.is_type3 {
901                self.draw_type3_glyph(&font, &item, &trm, gs, resources, depth);
902            }
903            text.matrix = Matrix::translate(advance_text, 0.0).concat(&text.matrix);
904        }
905    }
906
907    #[allow(clippy::too_many_arguments)]
908    fn emit_glyph(
909        &mut self,
910        font: &Font,
911        item: &CodeItem,
912        trm: &Matrix,
913        text_to_user: &Matrix,
914        gs: &State,
915        advance_text: f32,
916    ) {
917        // Soft hyphens mark optional break points and are not content; producers emit them at
918        // line ends where they would otherwise appear as stray hyphens in extracted text.
919        let own: String = item
920            .unicode
921            .as_deref()
922            .unwrap_or("")
923            .chars()
924            .filter(|&c| c != '\u{00AD}')
925            .collect();
926        // Inside an `/ActualText` span the document's replacement outranks the glyph's own
927        // mapping: the first glyph takes all of it and the rest go silent. A silent glyph is
928        // skipped by the gap logic below exactly as an unmapped one is, so the replacement is
929        // spaced as a unit — from its first glyph's origin and from its last glyph's end —
930        // and never broken up by gaps between the glyphs it replaces.
931        let in_span = self.span.is_some();
932        let text = match self.span.as_mut() {
933            Some(span) => std::mem::take(&mut span.pending),
934            None => own,
935        };
936
937        let origin = trm.apply(Point::default());
938        // The rendering matrix already folds in `/Tf` size, `Tm` and the CTM, so its vertical
939        // scale is the size the glyph actually appears at.
940        let effective_size = trm.y_scale();
941        // Transforming the advance as a vector keeps rotated and skewed text correct, and is
942        // exactly the displacement the interpreter applies to the text matrix after this glyph.
943        let (advance_dx, advance_dy) = text_to_user.apply_vector(advance_text, 0.0);
944        let advance_user = advance_dx.hypot(advance_dy);
945
946        // A gap on an unchanged baseline is a word break the string itself does not contain.
947        if !text.is_empty() {
948            if let Some(prev) = self.trail {
949                let same_line =
950                    (origin.y - prev.baseline_y).abs() <= BASELINE_EPSILON_EM * prev.size;
951                let gap = origin.x - prev.end.x;
952                if same_line
953                    && prev.size > 0.0
954                    && gap > SPACE_GAP_EM * prev.size
955                    && !self.last_was_space
956                    && !text.starts_with(char::is_whitespace)
957                {
958                    let order = self.next_order();
959                    self.glyphs.push(Glyph {
960                        text: " ".into(),
961                        origin: prev.end,
962                        bbox: Rect::from_corners(
963                            prev.end.x,
964                            prev.baseline_y,
965                            origin.x,
966                            prev.baseline_y + prev.size,
967                        ),
968                        advance: gap,
969                        font_size: prev.size,
970                        font_name: gs.font_name.clone(),
971                        base_font: font.base_font.clone(),
972                        flags: font.flags,
973                        rotation: trm.rotation(),
974                        is_generated_space: true,
975                        render_mode: gs.render_mode,
976                        color: gs.fill,
977                        alpha: gs.fill_alpha,
978                        order,
979                        font: None,
980                        code: item.clone(),
981                        glyph_matrix: *trm,
982                    });
983                }
984            }
985        }
986
987        if in_span {
988            // A silenced glyph says nothing about how the text before it ended.
989            if !text.is_empty() {
990                self.last_was_space = text.ends_with(char::is_whitespace);
991            }
992        } else {
993            // An unmapped glyph counts as a space here, as it always has: no gap after it
994            // generates one.
995            self.last_was_space = text.chars().all(char::is_whitespace);
996        }
997
998        let (bbox, glyph_matrix) = self.glyph_bbox(font, item, trm);
999        let order = self.next_order();
1000        self.glyphs.push(Glyph {
1001            text,
1002            origin,
1003            bbox,
1004            advance: advance_user,
1005            font_size: effective_size,
1006            font_name: gs.font_name.clone(),
1007            base_font: font.base_font.clone(),
1008            flags: font.flags,
1009            rotation: trm.rotation(),
1010            is_generated_space: false,
1011            render_mode: gs.render_mode,
1012            color: gs.fill,
1013            alpha: gs.fill_alpha,
1014            order,
1015            font: gs.font.clone(),
1016            code: item.clone(),
1017            glyph_matrix,
1018        });
1019
1020        self.trail = Some(PenTrail {
1021            end: Point::new(origin.x + advance_dx, origin.y + advance_dy),
1022            baseline_y: origin.y,
1023            size: effective_size,
1024        });
1025    }
1026
1027    /// A glyph's box: tight around the outline when the font program yields one, otherwise a
1028    /// nominal em box from the advance, which is what a metrics-only font can support.
1029    ///
1030    /// A substituted outline is deliberately not trusted horizontally. Its letters are another
1031    /// typeface's, so their ink widths are not this font's — and horizontally the document has
1032    /// already given the exact answer in the advance. Taking the substitute's widths made the
1033    /// gap between two glyphs depend on which fonts happen to be installed, which is what turned
1034    /// a letterspaced `REFERENCES` into `REFEREN CES`. Vertically the substitute is kept: cap
1035    /// height, x-height and descender depth carry across text faces well enough to be worth far
1036    /// more than one nominal height applied to every glyph alike.
1037    fn glyph_bbox(&self, font: &Font, item: &CodeItem, trm: &Matrix) -> (Rect, Matrix) {
1038        // Type3 glyph space is arbitrary, so the font matrix rather than /1000 applies.
1039        let to_text = if font.is_type3 {
1040            font.font_matrix
1041        } else {
1042            Matrix::scale(0.001, 0.001)
1043        };
1044        let m = to_text.concat(trm);
1045        let advance = item.width.max(1.0);
1046        if let Some(outline) = font.outline(item) {
1047            if let Some(b) = outline.bbox() {
1048                let b = if outline.is_substitute {
1049                    Rect {
1050                        x0: 0.0,
1051                        x1: advance,
1052                        ..b
1053                    }
1054                } else {
1055                    b
1056                };
1057                return (m.apply_rect(&b), m);
1058            }
1059        }
1060        // Nominal box: baseline to ascender, descender below, spanning the advance.
1061        let nominal = Rect::from_corners(0.0, -200.0, advance, 800.0);
1062        (m.apply_rect(&nominal), m)
1063    }
1064
1065    /// Runs a Type3 glyph's procedure so the marks it makes become page primitives.
1066    fn draw_type3_glyph(
1067        &mut self,
1068        font: &Font,
1069        item: &CodeItem,
1070        trm: &Matrix,
1071        gs: &State,
1072        resources: &Dict,
1073        depth: usize,
1074    ) {
1075        if depth >= MAX_DEPTH {
1076            return;
1077        }
1078        let Some(proc_obj) = font.type3_proc(self.doc, item.code) else {
1079            return;
1080        };
1081        let Some(stream) = proc_obj.as_stream() else {
1082            return;
1083        };
1084        let Ok(decoded) = self.doc.file.decode_stream(stream) else {
1085            return;
1086        };
1087        let mut inner = gs.clone();
1088        // Inside the procedure, glyph space maps to the page through the font matrix.
1089        inner.ctm = font.font_matrix.concat(trm);
1090        inner.font = None;
1091        self.run(&decoded.data, resources, inner, depth + 1);
1092    }
1093
1094    // ---- resources ----------------------------------------------------------------------
1095
1096    fn font_for(&mut self, resources: &Dict, name: &str) -> Option<Arc<Font>> {
1097        let fonts = self.doc.dict_get(resources, "Font")?;
1098        let entry = fonts.as_dict()?.get(name)?.clone();
1099        if let Object::Ref(r) = &entry {
1100            if let Some(hit) = self.font_cache.get(&r.num) {
1101                return Some(hit.clone());
1102            }
1103        }
1104        let dict = self.doc.resolve(&entry).as_dict()?.clone();
1105        let font = Arc::new(Font::load(self.doc, &dict));
1106        if let Object::Ref(r) = &entry {
1107            self.font_cache.insert(r.num, font.clone());
1108        }
1109        Some(font)
1110    }
1111
1112    /// `/ExtGState` carries a handful of parameters that change geometry or visibility.
1113    fn apply_ext_gstate(&self, resources: &Dict, name: &str, gs: &mut State) {
1114        let Some(ext) = self
1115            .doc
1116            .dict_get(resources, "ExtGState")
1117            .and_then(|o| o.as_dict().and_then(|d| d.get(name).cloned()))
1118        else {
1119            return;
1120        };
1121        let Some(dict) = self.doc.resolve(&ext).as_dict().cloned() else {
1122            return;
1123        };
1124        if let Some(lw) = self.doc.dict_get(&dict, "LW").and_then(|o| o.as_f32()) {
1125            gs.line_width = lw;
1126        }
1127        // Constant alpha. Watermarks and highlight boxes are drawn with these, so a consumer
1128        // that ignores them cannot tell a faint overlay from solid page content.
1129        if let Some(ca) = self.doc.dict_get(&dict, "ca").and_then(|o| o.as_f32()) {
1130            gs.fill_alpha = ca.clamp(0.0, 1.0);
1131        }
1132        if let Some(ca) = self.doc.dict_get(&dict, "CA").and_then(|o| o.as_f32()) {
1133            gs.stroke_alpha = ca.clamp(0.0, 1.0);
1134        }
1135        // `/Font` in an ExtGState is `[fontRef size]`.
1136        if let Some(Object::Array(items)) = self.doc.dict_get(&dict, "Font") {
1137            if let Some(size) = items.get(1).and_then(|o| o.as_f32()) {
1138                gs.font_size = size;
1139            }
1140        }
1141    }
1142
1143    /// How many components a named colour space has, so `scn` operands can be read.
1144    fn colorspace_components(&self, resources: &Dict, operands: &[Object]) -> usize {
1145        let Some(name) = operands.first().and_then(|o| o.as_name()) else {
1146            return 1;
1147        };
1148        match name {
1149            "DeviceGray" | "CalGray" | "G" => return 1,
1150            "DeviceRGB" | "CalRGB" | "Lab" | "RGB" => return 3,
1151            "DeviceCMYK" | "CMYK" => return 4,
1152            "Pattern" => return 0,
1153            _ => {}
1154        }
1155        // A named space resolves through the resource dictionary.
1156        let Some(space) = self
1157            .doc
1158            .dict_get(resources, "ColorSpace")
1159            .and_then(|o| o.as_dict().and_then(|d| d.get(name).cloned()))
1160            .map(|o| self.doc.resolve(&o))
1161        else {
1162            return 1;
1163        };
1164        self.components_of(&space, 0)
1165    }
1166
1167    fn components_of(&self, space: &Object, depth: usize) -> usize {
1168        if depth > 4 {
1169            return 1;
1170        }
1171        match space {
1172            Object::Name(n) => match n.as_str() {
1173                "DeviceRGB" | "CalRGB" | "Lab" => 3,
1174                "DeviceCMYK" => 4,
1175                _ => 1,
1176            },
1177            Object::Array(items) => {
1178                let head = items.first().and_then(|o| o.as_name()).unwrap_or("");
1179                match head {
1180                    // Indexed and separation spaces take a single index or tint value.
1181                    "Indexed" | "I" | "Separation" => 1,
1182                    "DeviceN" => items
1183                        .get(1)
1184                        .map(|o| self.doc.resolve(o))
1185                        .and_then(|o| o.as_array().map(<[Object]>::len))
1186                        .unwrap_or(1),
1187                    "ICCBased" => items
1188                        .get(1)
1189                        .map(|o| self.doc.resolve(o))
1190                        .and_then(|o| o.as_dict().and_then(|d| d.get("N").cloned()))
1191                        .and_then(|o| o.as_int())
1192                        .unwrap_or(3)
1193                        .clamp(1, 4) as usize,
1194                    "CalRGB" | "Lab" => 3,
1195                    "CalGray" => 1,
1196                    "Pattern" => 0,
1197                    _ => self
1198                        .components_of(&items.first().cloned().unwrap_or(Object::Null), depth + 1),
1199                }
1200            }
1201            _ => 1,
1202        }
1203    }
1204
1205    fn set_color(&self, gs: &mut State, is_fill: bool, operands: &[Object], components: usize) {
1206        let v: Vec<f32> = operands.iter().filter_map(|o| o.as_f32()).collect();
1207        let rgb = match components.min(v.len()) {
1208            1 => {
1209                let g = v[0].clamp(0.0, 1.0);
1210                [g, g, g]
1211            }
1212            3 => [
1213                v[0].clamp(0.0, 1.0),
1214                v[1].clamp(0.0, 1.0),
1215                v[2].clamp(0.0, 1.0),
1216            ],
1217            4 => {
1218                // The standard naive CMYK conversion; a colour-managed one needs the ICC profile.
1219                let k = v[3].clamp(0.0, 1.0);
1220                [
1221                    (1.0 - v[0].clamp(0.0, 1.0)) * (1.0 - k),
1222                    (1.0 - v[1].clamp(0.0, 1.0)) * (1.0 - k),
1223                    (1.0 - v[2].clamp(0.0, 1.0)) * (1.0 - k),
1224                ]
1225            }
1226            _ => return,
1227        };
1228        if is_fill {
1229            gs.fill = rgb;
1230            gs.fill_components = components;
1231        } else {
1232            gs.stroke = rgb;
1233            gs.stroke_components = components;
1234        }
1235    }
1236
1237    // ---- XObjects -----------------------------------------------------------------------
1238
1239    fn do_xobject(&mut self, name: &str, resources: &Dict, gs: &State, depth: usize) {
1240        let Some(xobjects) = self.doc.dict_get(resources, "XObject") else {
1241            return;
1242        };
1243        let Some(entry) = xobjects.as_dict().and_then(|d| d.get(name).cloned()) else {
1244            return;
1245        };
1246        let obj_num = entry.as_ref_id().map(|r| r.num);
1247        let resolved = self.doc.resolve(&entry);
1248        let Some(stream) = resolved.as_stream() else {
1249            return;
1250        };
1251        let subtype = stream.dict.get("Subtype").and_then(|o| o.as_name());
1252
1253        match subtype {
1254            Some("Image") => self.record_image(name, stream, entry.as_ref_id(), gs),
1255            Some("Form") => {
1256                // A form that draws itself would recurse forever.
1257                if let Some(num) = obj_num {
1258                    if !self.active_forms.insert(num) {
1259                        return;
1260                    }
1261                }
1262                let Ok(decoded) = self.doc.file.decode_stream(stream) else {
1263                    if let Some(num) = obj_num {
1264                        self.active_forms.remove(&num);
1265                    }
1266                    return;
1267                };
1268                let mut inner = gs.clone();
1269                if let Some(m) = stream
1270                    .dict
1271                    .get("Matrix")
1272                    .map(|o| self.doc.resolve(o))
1273                    .as_ref()
1274                    .and_then(|o| o.as_array())
1275                {
1276                    let v: Vec<f32> = m.iter().filter_map(|o| o.as_f32()).collect();
1277                    if v.len() >= 6 {
1278                        inner.ctm = Matrix::new(v[0], v[1], v[2], v[3], v[4], v[5]).concat(&gs.ctm);
1279                    }
1280                }
1281                if let Some(bbox) = stream
1282                    .dict
1283                    .get("BBox")
1284                    .map(|o| self.doc.resolve(o))
1285                    .as_ref()
1286                    .and_then(|o| o.as_array())
1287                {
1288                    let v: Vec<f32> = bbox.iter().filter_map(|o| o.as_f32()).collect();
1289                    if v.len() >= 4 {
1290                        let r = inner
1291                            .ctm
1292                            .apply_rect(&Rect::from_corners(v[0], v[1], v[2], v[3]));
1293                        if !r.is_empty() {
1294                            inner.clip = inner.clip.intersect(&r);
1295                        }
1296                    }
1297                }
1298                // A form without its own /Resources inherits the page's.
1299                let inner_resources = self
1300                    .doc
1301                    .dict_get(&stream.dict, "Resources")
1302                    .and_then(|o| o.as_dict().cloned())
1303                    .unwrap_or_else(|| resources.clone());
1304                let data = decoded.data;
1305                self.run(&data, &inner_resources, inner, depth + 1);
1306                if let Some(num) = obj_num {
1307                    self.active_forms.remove(&num);
1308                }
1309            }
1310            _ => {}
1311        }
1312    }
1313
1314    fn record_image(
1315        &mut self,
1316        name: &str,
1317        stream: &crate::object::Stream,
1318        obj_ref: Option<ObjRef>,
1319        gs: &State,
1320    ) {
1321        let dict = &stream.dict;
1322        let width = self
1323            .doc
1324            .dict_get(dict, "Width")
1325            .and_then(|o| o.as_int())
1326            .unwrap_or(0)
1327            .max(0) as u32;
1328        let height = self
1329            .doc
1330            .dict_get(dict, "Height")
1331            .and_then(|o| o.as_int())
1332            .unwrap_or(0)
1333            .max(0) as u32;
1334        if width == 0 || height == 0 {
1335            return;
1336        }
1337        let is_mask = self
1338            .doc
1339            .dict_get(dict, "ImageMask")
1340            .and_then(|o| o.as_bool())
1341            .unwrap_or(false);
1342        let bpc = self
1343            .doc
1344            .dict_get(dict, "BitsPerComponent")
1345            .and_then(|o| o.as_int())
1346            .unwrap_or(if is_mask { 1 } else { 8 })
1347            .clamp(1, 16) as u8;
1348        let components = if is_mask {
1349            1
1350        } else {
1351            let space = self
1352                .doc
1353                .dict_get(dict, "ColorSpace")
1354                .unwrap_or(Object::Null);
1355            self.components_of(&space, 0).max(1) as u8
1356        };
1357
1358        // The pixels stay in the file until someone asks for them. When the image is not
1359        // reachable by reference the samples have to be carried, but a direct image XObject is
1360        // rare enough that the cost does not matter.
1361        let source = match obj_ref {
1362            Some(r) => ImageSource::Object(r),
1363            None => {
1364                let Ok(decoded) = self.doc.file.decode_stream(stream) else {
1365                    return;
1366                };
1367                ImageSource::Inline(Arc::new(match decoded.image_filter {
1368                    Some(filter) => ImageData::Encoded {
1369                        filter,
1370                        data: decoded.data,
1371                    },
1372                    None => ImageData::Raw {
1373                        bits_per_component: bpc,
1374                        components,
1375                        data: decoded.data,
1376                    },
1377                }))
1378            }
1379        };
1380        self.push_image(name, gs, width, height, is_mask, bpc, components, source);
1381    }
1382
1383    fn record_inline_image(&mut self, dict: &Dict, raw: &[u8], gs: &State, resources: &Dict) {
1384        let width = self
1385            .doc
1386            .dict_get(dict, "Width")
1387            .and_then(|o| o.as_int())
1388            .unwrap_or(0)
1389            .max(0) as u32;
1390        let height = self
1391            .doc
1392            .dict_get(dict, "Height")
1393            .and_then(|o| o.as_int())
1394            .unwrap_or(0)
1395            .max(0) as u32;
1396        if width == 0 || height == 0 {
1397            return;
1398        }
1399        let is_mask = self
1400            .doc
1401            .dict_get(dict, "ImageMask")
1402            .and_then(|o| o.as_bool())
1403            .unwrap_or(false);
1404        let bpc = self
1405            .doc
1406            .dict_get(dict, "BitsPerComponent")
1407            .and_then(|o| o.as_int())
1408            .unwrap_or(if is_mask { 1 } else { 8 })
1409            .clamp(1, 16) as u8;
1410        // An inline image's colour space may name an entry in the page's /ColorSpace resources.
1411        let components = if is_mask {
1412            1
1413        } else {
1414            match self.doc.dict_get(dict, "ColorSpace") {
1415                Some(Object::Name(n)) => {
1416                    self.colorspace_components(resources, &[Object::Name(n)]) as u8
1417                }
1418                Some(other) => self.components_of(&other, 0) as u8,
1419                None => 1,
1420            }
1421            .max(1)
1422        };
1423
1424        let resolve = |o: &Object| self.doc.resolve(o);
1425        let data = match crate::filters::decode(dict, raw, &resolve) {
1426            Ok(d) => match d.image_filter {
1427                Some(filter) => ImageData::Encoded {
1428                    filter,
1429                    data: d.data,
1430                },
1431                None => ImageData::Raw {
1432                    bits_per_component: bpc,
1433                    components,
1434                    data: d.data,
1435                },
1436            },
1437            Err(_) => return,
1438        };
1439        let source = ImageSource::Inline(Arc::new(data));
1440        self.push_image(
1441            "inline", gs, width, height, is_mask, bpc, components, source,
1442        );
1443    }
1444
1445    #[allow(clippy::too_many_arguments)]
1446    fn push_image(
1447        &mut self,
1448        name: &str,
1449        gs: &State,
1450        width: u32,
1451        height: u32,
1452        is_mask: bool,
1453        bits_per_component: u8,
1454        components: u8,
1455        source: ImageSource,
1456    ) {
1457        // Image space has its first row at the top of the unit square, so flip y into the CTM.
1458        let ctm = Matrix::new(1.0, 0.0, 0.0, -1.0, 0.0, 1.0).concat(&gs.ctm);
1459        let bbox = gs.ctm.apply_rect(&Rect::from_corners(0.0, 0.0, 1.0, 1.0));
1460        let order = self.next_order();
1461        self.images.push(ImageItem {
1462            name: name.to_string(),
1463            ctm,
1464            bbox,
1465            width,
1466            height,
1467            is_mask,
1468            bits_per_component,
1469            components,
1470            fill: gs.fill,
1471            alpha: gs.fill_alpha,
1472            order,
1473            source,
1474        });
1475    }
1476
1477    /// Allocates the next paint-order stamp.
1478    fn next_order(&mut self) -> u32 {
1479        let n = self.order;
1480        self.order = self.order.saturating_add(1);
1481        n
1482    }
1483}
1484
1485fn next_line(text: &mut TextState, leading: f32) {
1486    text.line_matrix = Matrix::translate(0.0, -leading).concat(&text.line_matrix);
1487    text.matrix = text.line_matrix;
1488}
1489
1490/// The bounding box of a path, control points included.
1491fn bounds(cmds: &[PathCmd]) -> Rect {
1492    let mut out: Option<Rect> = None;
1493    let mut add = |p: Point| {
1494        out = Some(match out {
1495            None => Rect {
1496                x0: p.x,
1497                y0: p.y,
1498                x1: p.x,
1499                y1: p.y,
1500            },
1501            Some(r) => Rect {
1502                x0: r.x0.min(p.x),
1503                y0: r.y0.min(p.y),
1504                x1: r.x1.max(p.x),
1505                y1: r.y1.max(p.y),
1506            },
1507        });
1508    };
1509    for cmd in cmds {
1510        match *cmd {
1511            PathCmd::MoveTo(p) | PathCmd::LineTo(p) => add(p),
1512            PathCmd::CurveTo(a, b, c) => {
1513                add(a);
1514                add(b);
1515                add(c);
1516            }
1517            PathCmd::Close => {}
1518        }
1519    }
1520    out.unwrap_or(Rect::EMPTY)
1521}
1522
1523#[cfg(test)]
1524pub(crate) mod tests {
1525    use super::*;
1526    use crate::parser::tests::tiny_pdf;
1527
1528    /// Builds a one-page document whose content stream is `content`, using Helvetica as /F1.
1529    pub(crate) fn doc_with(content: &str) -> Document {
1530        let base = String::from_utf8(tiny_pdf()).unwrap();
1531        let old = "BT /F1 12 Tf 72 720 Td (Hi) Tj ET";
1532        // The /Length is wrong after substitution, which the endstream scan recovers from — the
1533        // same path a real producer's off-by-one length takes.
1534        Document::from_bytes(base.replace(old, content).into_bytes(), None).unwrap()
1535    }
1536
1537    #[test]
1538    fn extracts_text_with_positions() {
1539        let doc = doc_with("BT /F1 12 Tf 72 720 Td (Hi) Tj ET");
1540        let page = doc.page(0).unwrap();
1541        assert_eq!(page.text(), "Hi");
1542        assert_eq!(page.glyphs.len(), 2);
1543
1544        let h = &page.glyphs[0];
1545        assert_eq!(h.text, "H");
1546        assert_eq!(h.base_font, "Helvetica");
1547        assert!((h.origin.x - 72.0).abs() < 0.01);
1548        assert!((h.origin.y - 720.0).abs() < 0.01);
1549        assert!((h.font_size - 12.0).abs() < 0.01);
1550        // Helvetica's H advances 722/1000 em.
1551        assert!((h.advance - 722.0 / 1000.0 * 12.0).abs() < 0.01);
1552        // The next glyph starts exactly one advance along.
1553        assert!((page.glyphs[1].origin.x - (72.0 + 8.664)).abs() < 0.01);
1554    }
1555
1556    fn text_of(content: &str) -> String {
1557        doc_with(content).page(0).unwrap().text()
1558    }
1559
1560    #[test]
1561    fn actual_text_replaces_what_its_glyphs_say_and_keeps_where_they_are() {
1562        let plain = doc_with("BT /F1 12 Tf 72 720 Td (a) Tj (xy) Tj (b) Tj ET");
1563        let tagged = doc_with(
1564            "BT /F1 12 Tf 72 720 Td (a) Tj /Span <</ActualText (fi)>> BDC (xy) Tj EMC (b) Tj ET",
1565        );
1566        let (plain, tagged) = (plain.page(0).unwrap(), tagged.page(0).unwrap());
1567        assert_eq!(plain.text(), "axyb");
1568        assert_eq!(tagged.text(), "afib");
1569
1570        // The first glyph of the span carries the replacement and the rest carry nothing.
1571        let texts: Vec<&str> = tagged.glyphs.iter().map(|g| g.text.as_str()).collect();
1572        assert_eq!(texts, ["a", "fi", "", "b"]);
1573
1574        // Geometry and identity are untouched: same glyphs, in the same places.
1575        assert_eq!(plain.glyphs.len(), tagged.glyphs.len());
1576        for (p, t) in plain.glyphs.iter().zip(&tagged.glyphs) {
1577            assert_eq!((p.origin, p.bbox, p.advance), (t.origin, t.bbox, t.advance));
1578            assert_eq!(p.code(), t.code());
1579        }
1580    }
1581
1582    #[test]
1583    fn actual_text_spans_several_show_operators_as_one_unit() {
1584        // Three operators, a line-internal move and a word-sized TJ gap, all inside one span:
1585        // the replacement is the whole of what they say, with no space invented within it.
1586        let doc = doc_with(
1587            "BT /F1 12 Tf 72 720 Td (A) Tj /Span <</ActualText (68)>> BDC \
1588             (x) Tj 20 0 Td (y) Tj [(z) -500 (w)] TJ EMC (B) Tj ET",
1589        );
1590        let page = doc.page(0).unwrap();
1591        assert_eq!(page.text(), "A68B");
1592        assert_eq!(page.glyphs.len(), 6);
1593        assert!(page.glyphs.iter().all(|g| !g.is_generated_space));
1594    }
1595
1596    #[test]
1597    fn the_outermost_actual_text_wins() {
1598        // The inner span neither adds its text nor ends the outer one early.
1599        assert_eq!(
1600            text_of(
1601                "BT /F1 12 Tf 72 720 Td /Span <</ActualText (out)>> BDC (a) Tj \
1602                 /Span <</ActualText (in)>> BDC (b) Tj EMC (c) Tj EMC (d) Tj ET"
1603            ),
1604            "outd"
1605        );
1606        // Enclosing sequences without ActualText — structure tags, a bare BMC — are transparent,
1607        // and their EMC does not disturb text after the span.
1608        assert_eq!(
1609            text_of(
1610                "/P <</MCID 0>> BDC /Artifact BMC BT /F1 12 Tf 72 720 Td (a) Tj \
1611                 /Span <</ActualText (X)>> BDC (b) Tj EMC (c) Tj ET EMC EMC \
1612                 BT 1 0 0 1 100 720 Tm (d) Tj ET"
1613            ),
1614            "aXc d"
1615        );
1616    }
1617
1618    #[test]
1619    fn an_empty_actual_text_silences_its_glyphs() {
1620        for empty in ["()", "<FEFF>", "<>"] {
1621            let doc = doc_with(&format!(
1622                "BT /F1 12 Tf 72 720 Td (a) Tj /Span <</ActualText {empty}>> BDC (-) Tj EMC \
1623                 (b) Tj ET"
1624            ));
1625            let page = doc.page(0).unwrap();
1626            assert_eq!(page.text(), "ab", "ActualText {empty}");
1627            // The hyphen is still on the page, it just reads as nothing.
1628            assert_eq!(page.glyphs.len(), 3);
1629            assert_eq!(page.glyphs[1].text, "");
1630            assert_eq!(page.glyphs[1].code(), u32::from(b'-'));
1631        }
1632    }
1633
1634    #[test]
1635    fn actual_text_is_decoded_as_a_text_string() {
1636        let span = |value: &str| {
1637            text_of(&format!(
1638                "BT /F1 12 Tf 72 720 Td /Span <</ActualText {value}>> BDC (x) Tj EMC ET"
1639            ))
1640        };
1641        // UTF-16BE behind a byte-order mark, as Chromium writes it.
1642        assert_eq!(span("<FEFF00660069>"), "fi");
1643        assert_eq!(span("<FEFF03B1D835DC00>"), "\u{3b1}\u{1D400}");
1644        // No mark: PDFDocEncoding, where 0x93 is the fi ligature and not Latin-1's control code.
1645        assert_eq!(span("(fi)"), "fi");
1646        assert_eq!(span("(\\223 \\351)"), "\u{FB01} \u{e9}");
1647        assert_eq!(span("<93>"), "\u{FB01}");
1648    }
1649
1650    #[test]
1651    fn a_gap_beside_a_span_is_one_space() {
1652        // Word gaps on both sides of a span whose glyph says something else entirely.
1653        assert_eq!(
1654            text_of(
1655                "BT /F1 12 Tf 72 720 Td [(A) -500] TJ /Span <</ActualText (6)>> BDC (x) Tj EMC \
1656                 [-500 (B)] TJ ET"
1657            ),
1658            "A 6 B"
1659        );
1660        // The same gaps where the replacement brings its own spaces: none is added.
1661        assert_eq!(
1662            text_of(
1663                "BT /F1 12 Tf 72 720 Td [(A) -500] TJ /Span <</ActualText ( 6 )>> BDC (x) Tj \
1664                 EMC [-500 (B)] TJ ET"
1665            ),
1666            "A 6 B"
1667        );
1668        // No gap, no space.
1669        assert_eq!(
1670            text_of(
1671                "BT /F1 12 Tf 72 720 Td (A) Tj /Span <</ActualText (6)>> BDC (x) Tj EMC (B) Tj ET"
1672            ),
1673            "A6B"
1674        );
1675        // A gap after a span of several glyphs is measured from the last of them, and the
1676        // silent ones do not hide that the replacement ended without a space.
1677        assert_eq!(
1678            text_of(
1679                "BT /F1 12 Tf 72 720 Td (A) Tj /Span <</ActualText (fi)>> BDC (xy) Tj EMC \
1680                 [-500 (B)] TJ ET"
1681            ),
1682            "Afi B"
1683        );
1684        // Silenced glyphs between two words leave the one space the gaps amount to.
1685        assert_eq!(
1686            text_of(
1687                "BT /F1 12 Tf 72 720 Td [(A) -500] TJ /Span <</ActualText ()>> BDC (x) Tj EMC \
1688                 [-500 (B)] TJ ET"
1689            ),
1690            "A B"
1691        );
1692    }
1693
1694    /// Chromium tags space glyphs with a line feed at HTML block boundaries, which are not
1695    /// reliably where the visual line ends. The tag reads as the space it sits on, and line
1696    /// breaks stay a matter of geometry.
1697    #[test]
1698    fn an_actual_text_line_feed_is_a_space_not_a_line_break() {
1699        // Mid-line: no break is invented.
1700        assert_eq!(
1701            text_of(
1702                "BT /F1 12 Tf 72 720 Td (one) Tj /Span <</ActualText <FEFF000A>>> BDC ( ) Tj EMC \
1703                 (two) Tj ET"
1704            ),
1705            "one two"
1706        );
1707        // At a real line end: the geometric break is the only one.
1708        assert_eq!(
1709            text_of(
1710                "BT /F1 12 Tf 72 720 Td (one) Tj /Span <</ActualText <FEFF000A>>> BDC ( ) Tj EMC \
1711                 1 0 0 1 72 700 Tm (two) Tj ET"
1712            ),
1713            "one \ntwo"
1714        );
1715    }
1716
1717    #[test]
1718    fn actual_text_is_found_through_the_properties_resource() {
1719        let base = String::from_utf8(tiny_pdf()).unwrap();
1720        let pdf = base
1721            .replace(
1722                "/Resources << /Font",
1723                "/Resources << /Properties << /MC0 << /ActualText (fl) >> >> /Font",
1724            )
1725            .replace(
1726                "BT /F1 12 Tf 72 720 Td (Hi) Tj ET",
1727                "BT /F1 12 Tf 72 720 Td /Span /MC0 BDC (x) Tj EMC /Span /Nope BDC (y) Tj EMC ET",
1728            );
1729        let doc = Document::from_bytes(pdf.into_bytes(), None).unwrap();
1730        // A name the resources do not define is a sequence with no properties at all.
1731        assert_eq!(doc.page(0).unwrap().text(), "fly");
1732    }
1733
1734    #[test]
1735    fn unbalanced_marked_content_does_not_leak_or_panic() {
1736        // Never closed: the span covers the rest of the stream, and nothing breaks.
1737        assert_eq!(
1738            text_of("BT /F1 12 Tf 72 720 Td (a) Tj /Span <</ActualText (X)>> BDC (bc) Tj ET"),
1739            "aX"
1740        );
1741        // Closed too often, and opened with operands that are not what the operator takes.
1742        assert_eq!(
1743            text_of(
1744                "EMC EMC BT /F1 12 Tf 72 720 Td BDC (a) Tj EMC /Span 7 BDC (b) Tj EMC \
1745                 /Span <</ActualText 7>> BDC (c) Tj EMC EMC ET"
1746            ),
1747            "abc"
1748        );
1749    }
1750
1751    #[test]
1752    fn page_geometry_matches_media_box() {
1753        let doc = doc_with("BT /F1 12 Tf 72 720 Td (Hi) Tj ET");
1754        let page = doc.page(0).unwrap();
1755        assert_eq!((page.width(), page.height()), (612.0, 792.0));
1756        // User-space y-up maps to device y-down: the baseline at y=720 lands 72pt from the top.
1757        let m = page.page_matrix(1.0);
1758        let p = m.apply(Point::new(72.0, 720.0));
1759        assert!((p.x - 72.0).abs() < 0.01 && (p.y - 72.0).abs() < 0.01);
1760    }
1761
1762    #[test]
1763    fn tj_offsets_shift_the_pen_and_generate_spaces() {
1764        // -500 thousandths at 12pt is a 6pt gap, far over the word-break threshold.
1765        let doc = doc_with("BT /F1 12 Tf 72 720 Td [(A) -500 (B)] TJ ET");
1766        let page = doc.page(0).unwrap();
1767        assert_eq!(page.text(), "A B");
1768        assert!(page.glyphs[1].is_generated_space);
1769
1770        // A small adjustment is kerning, not a word break.
1771        let doc = doc_with("BT /F1 12 Tf 72 720 Td [(A) -20 (B)] TJ ET");
1772        assert_eq!(doc.page(0).unwrap().text(), "AB");
1773    }
1774
1775    /// Justified text squeezes its word spaces, and they still have to register as spaces.
1776    ///
1777    /// A real line of ICLR body text was found setting them at 0.19 em — under the 0.20 em the
1778    /// threshold started at, so *every* word gap on that line was missed and the line extracted
1779    /// as one run-on word. The threshold has to sit below what justification compresses a space
1780    /// to, and above what kerning ever opens up.
1781    #[test]
1782    fn a_compressed_word_space_is_still_a_word_space() {
1783        let doc = doc_with("BT /F1 12 Tf 72 720 Td [(A) -190 (B)] TJ ET");
1784        assert_eq!(
1785            doc.page(0).unwrap().text(),
1786            "A B",
1787            "0.19 em is a squeezed space"
1788        );
1789
1790        // Well below any space, and comfortably above ordinary kerning: still one word.
1791        let doc = doc_with("BT /F1 12 Tf 72 720 Td [(A) -80 (B)] TJ ET");
1792        assert_eq!(doc.page(0).unwrap().text(), "AB", "0.08 em is not a space");
1793    }
1794
1795    /// A glyph drawn from a substitute face must report the document's advance, not the
1796    /// substitute's ink width.
1797    ///
1798    /// Helvetica is one of the standard 14 and embeds nothing, so its outlines come from
1799    /// whatever system face is installed. Letting that face's ink decide the box made the gap
1800    /// between two glyphs depend on which fonts the machine happened to have, and a letterspaced
1801    /// heading then picked up a word break that is not in the document (`REFEREN CES`).
1802    #[test]
1803    fn a_substituted_glyph_reports_the_documents_advance() {
1804        let doc = doc_with("BT /F1 12 Tf 72 720 Td (Hi) Tj ET");
1805        let page = doc.page(0).unwrap();
1806
1807        for glyph in &page.glyphs {
1808            let width = glyph.bbox.x1 - glyph.bbox.x0;
1809            assert!(
1810                (width - glyph.advance).abs() < 0.01,
1811                "{:?}: box {width} should span the advance {}",
1812                glyph.text,
1813                glyph.advance
1814            );
1815        }
1816
1817        // Consecutive boxes therefore abut exactly, leaving no gap to mistake for a space.
1818        let gap = page.glyphs[1].bbox.x0 - page.glyphs[0].bbox.x1;
1819        assert!(
1820            gap.abs() < 0.01,
1821            "adjacent letters must not show an ink gap"
1822        );
1823    }
1824
1825    #[test]
1826    fn text_state_operators_apply() {
1827        // Tz halves the advance; the second glyph must land half as far along.
1828        let doc = doc_with("BT /F1 12 Tf 50 Tz 72 720 Td (Hi) Tj ET");
1829        let page = doc.page(0).unwrap();
1830        assert!((page.glyphs[1].origin.x - (72.0 + 8.664 / 2.0)).abs() < 0.01);
1831
1832        // TL + T* moves down one leading.
1833        let doc = doc_with("BT /F1 12 Tf 14 TL 72 720 Td (A) Tj T* (B) Tj ET");
1834        let page = doc.page(0).unwrap();
1835        let b = page.glyphs.iter().find(|g| g.text == "B").unwrap();
1836        assert!((b.origin.y - 706.0).abs() < 0.01);
1837    }
1838
1839    #[test]
1840    fn a_scaled_text_matrix_does_not_manufacture_spaces() {
1841        // `Tm` carries its own scale, so the pen advance must travel through Tm as well as the
1842        // CTM. Scaling by the CTM alone under-counts it, and the shortfall reads as a gap wide
1843        // enough to be a word break — a space between every single character.
1844        let doc = doc_with("BT /F1 12 Tf 2 0 0 2 72 720 Tm (Hi) Tj ET");
1845        let page = doc.page(0).unwrap();
1846        assert_eq!(page.text(), "Hi");
1847        assert!(!page.glyphs.iter().any(|g| g.is_generated_space));
1848        // Helvetica's H advances 722/1000 em, doubled by the text matrix.
1849        assert!((page.glyphs[1].origin.x - (72.0 + 0.722 * 12.0 * 2.0)).abs() < 0.05);
1850    }
1851
1852    #[test]
1853    fn an_oversized_advance_does_not_swallow_word_breaks() {
1854        // The mirror of the case above: over-counting the advance pushes the pen past the next
1855        // glyph, every gap computes as negative, and no word break is ever emitted.
1856        let doc = doc_with("BT /F1 12 Tf 0.5 0 0 0.5 72 720 Tm (a) Tj 40 0 Td (b) Tj ET");
1857        let page = doc.page(0).unwrap();
1858        assert!(
1859            page.glyphs.iter().any(|g| g.is_generated_space),
1860            "a 20pt gap at 6pt effective size is a word break: {:?}",
1861            page.text()
1862        );
1863    }
1864
1865    #[test]
1866    fn text_breaks_lines_instead_of_fusing_words() {
1867        // Content streams have no newlines; a new line is a glyph at another baseline. Without
1868        // a break the last word of one line fuses onto the first of the next.
1869        let doc = doc_with("BT /F1 12 Tf 72 720 Td (of) Tj 0 -14 Td (the) Tj ET");
1870        assert_eq!(doc.page(0).unwrap().text(), "of\nthe");
1871    }
1872
1873    #[test]
1874    fn a_wrapped_line_returning_to_the_margin_breaks() {
1875        // Some producers set an explicit `Tm` per line rather than using `Td`/`T*`.
1876        let doc =
1877            doc_with("BT /F1 12 Tf 1 0 0 1 300 720 Tm (end) Tj 1 0 0 1 72 720 Tm (start) Tj ET");
1878        assert_eq!(doc.page(0).unwrap().text(), "end\nstart");
1879    }
1880
1881    #[test]
1882    fn a_page_sized_image_with_no_text_reads_as_scanned() {
1883        let doc =
1884            doc_with("q 612 0 0 792 0 0 cm BI /W 4 /H 4 /BPC 8 /CS /G ID 0123456789abcdef EI Q");
1885        assert!(doc.page(0).unwrap().is_likely_scanned());
1886    }
1887
1888    #[test]
1889    fn text_over_an_image_is_not_scanned() {
1890        // A full-page figure with a caption, and an OCR text layer, must both extract normally.
1891        let body = (0..40)
1892            .map(|i| {
1893                format!(
1894                    "BT /F1 9 Tf 72 {} Td (line of real text) Tj ET",
1895                    700 - i * 12
1896                )
1897            })
1898            .collect::<Vec<_>>()
1899            .join(" ");
1900        let doc = doc_with(&format!(
1901            "q 612 0 0 792 0 0 cm BI /W 4 /H 4 /BPC 8 /CS /G ID 0123456789abcdef EI Q {body}"
1902        ));
1903        assert!(!doc.page(0).unwrap().is_likely_scanned());
1904    }
1905
1906    #[test]
1907    fn an_ordinary_text_page_is_not_scanned() {
1908        let doc = doc_with("BT /F1 12 Tf 72 720 Td (Hi) Tj ET");
1909        assert!(!doc.page(0).unwrap().is_likely_scanned());
1910    }
1911
1912    #[test]
1913    fn cells_in_separate_text_objects_stay_separate_words() {
1914        // Producers routinely wrap each table cell in its own BT/ET. The gap between them is
1915        // the only thing separating the cells, so it has to survive the object boundary —
1916        // otherwise a row fuses into one token.
1917        let doc =
1918            doc_with("BT /F1 10 Tf 72 700 Td (alpha) Tj ET BT /F1 10 Tf 300 700 Td (beta) Tj ET");
1919        let text = doc.page(0).unwrap().text();
1920        assert!(
1921            text.contains("alpha") && text.contains("beta") && !text.contains("alphabeta"),
1922            "cells fused: {text:?}"
1923        );
1924    }
1925
1926    #[test]
1927    fn a_superscript_stays_on_its_line() {
1928        // A footnote marker or exponent sits above the baseline but continues the line. Treating
1929        // that shift as a line break splits `x2` into `x` and `2`, which is how sub- and
1930        // superscripts get separated from what they modify all through a mathematics paper.
1931        let doc = doc_with("BT /F1 10 Tf 72 700 Td (x) Tj 4 Ts /F1 7 Tf (2) Tj ET");
1932        assert_eq!(doc.page(0).unwrap().text(), "x2");
1933    }
1934
1935    #[test]
1936    fn ordinary_spacing_within_a_line_is_not_a_break() {
1937        let doc = doc_with("BT /F1 12 Tf 72 720 Td (a) Tj (b) Tj ET");
1938        assert_eq!(doc.page(0).unwrap().text(), "ab");
1939    }
1940
1941    #[test]
1942    fn invisible_text_is_kept_but_flagged() {
1943        let doc = doc_with("BT /F1 12 Tf 3 Tr 72 720 Td (Hi) Tj ET");
1944        let page = doc.page(0).unwrap();
1945        assert_eq!(page.text(), "Hi");
1946        assert!(!page.glyphs[0].is_visible());
1947    }
1948
1949    #[test]
1950    fn paths_are_recorded_in_user_space() {
1951        let doc = doc_with("0 0 1 rg 10 20 100 50 re f");
1952        let page = doc.page(0).unwrap();
1953        assert_eq!(page.paths.len(), 1);
1954        let p = &page.paths[0];
1955        assert_eq!(p.bbox, Rect::from_corners(10.0, 20.0, 110.0, 70.0));
1956        assert_eq!(p.fill, Some([0.0, 0.0, 1.0]));
1957        assert_eq!(p.stroke, None);
1958    }
1959
1960    #[test]
1961    fn cm_transforms_geometry_and_q_restores_it() {
1962        let doc = doc_with("q 2 0 0 2 5 5 cm 0 0 10 10 re f Q 0 0 10 10 re S");
1963        let page = doc.page(0).unwrap();
1964        assert_eq!(page.paths.len(), 2);
1965        // Scaled by 2 and shifted by 5.
1966        assert_eq!(page.paths[0].bbox, Rect::from_corners(5.0, 5.0, 25.0, 25.0));
1967        // After Q the CTM is back to identity.
1968        assert_eq!(page.paths[1].bbox, Rect::from_corners(0.0, 0.0, 10.0, 10.0));
1969        assert!(page.paths[1].fill.is_none() && page.paths[1].stroke.is_some());
1970    }
1971
1972    #[test]
1973    fn cmyk_and_gray_colors_convert() {
1974        let doc = doc_with("0.5 g 0 0 1 1 re f 0 1 1 0 k 0 0 1 1 re f");
1975        let page = doc.page(0).unwrap();
1976        assert_eq!(page.paths[0].fill, Some([0.5, 0.5, 0.5]));
1977        // Cyan=0, magenta=1, yellow=1, black=0 is red.
1978        assert_eq!(page.paths[1].fill, Some([1.0, 0.0, 0.0]));
1979    }
1980
1981    #[test]
1982    fn inline_images_are_recorded() {
1983        let doc =
1984            doc_with("q 100 0 0 50 10 10 cm BI /W 2 /H 2 /BPC 8 /CS /G ID \x01\x02\x03\x04 EI Q");
1985        let page = doc.page(0).unwrap();
1986        assert_eq!(page.images.len(), 1);
1987        let img = &page.images[0];
1988        assert_eq!((img.width, img.height), (2, 2));
1989        assert_eq!(img.bbox, Rect::from_corners(10.0, 10.0, 110.0, 60.0));
1990        assert_eq!((img.components, img.bits_per_component), (1, 8));
1991        // Pixels are fetched on demand rather than carried on the item.
1992        match img.decode(&doc).unwrap() {
1993            ImageData::Raw { data, .. } => assert_eq!(data.len(), 4),
1994            other => panic!("expected raw samples, got {other:?}"),
1995        }
1996    }
1997
1998    #[test]
1999    fn malformed_content_does_not_panic() {
2000        for junk in [
2001            "BT (unterminated",
2002            "q q q q 1 0 0 1 cm",
2003            "BT /Missing 12 Tf (x) Tj ET",
2004            "[(A) (B)] TJ",
2005            ") ] >> garbage f",
2006            "BT /F1 0 Tf 72 720 Td (Hi) Tj ET",
2007        ] {
2008            let page = doc_with(junk).page(0).unwrap();
2009            let _ = page.text();
2010        }
2011    }
2012}
2013
2014#[cfg(test)]
2015mod thread_safety {
2016    /// The crate's premise is that a document is usable from several threads at once. Assert it
2017    /// at compile time so a stray `Rc` or `Cell` cannot silently take it away.
2018    const _: fn() = || {
2019        fn assert_send_sync<T: Send + Sync>() {}
2020        assert_send_sync::<crate::Document>();
2021        assert_send_sync::<crate::Font>();
2022        assert_send_sync::<crate::Page>();
2023    };
2024}
2025
2026#[cfg(test)]
2027mod colorspace_tests {
2028    use super::tests::doc_with;
2029
2030    #[test]
2031    fn scn_reads_operands_through_the_declared_space() {
2032        // An ICCBased 3-component space makes `scn` an RGB triple.
2033        let doc = doc_with("/DeviceRGB cs 1 0 0 scn 0 0 1 1 re f");
2034        assert_eq!(doc.page(0).unwrap().paths[0].fill, Some([1.0, 0.0, 0.0]));
2035
2036        // A Separation space takes one tint, read as gray.
2037        let doc = doc_with("/DeviceGray cs 0.25 scn 0 0 1 1 re f");
2038        assert_eq!(doc.page(0).unwrap().paths[0].fill, Some([0.25, 0.25, 0.25]));
2039    }
2040
2041    #[test]
2042    fn pattern_name_operand_leaves_the_color_alone() {
2043        // `/P0 scn` names a pattern and carries no numeric operands. There is no colour to
2044        // read, so the current one must survive rather than collapsing to black.
2045        let doc = doc_with("1 0 0 rg /P0 scn 0 0 1 1 re f");
2046        assert_eq!(doc.page(0).unwrap().paths[0].fill, Some([1.0, 0.0, 0.0]));
2047    }
2048
2049    #[test]
2050    fn cs_resets_to_the_spaces_initial_color() {
2051        // Selecting a colour space resets the current colour to that space's initial value,
2052        // which for the device spaces is black.
2053        let doc = doc_with("1 0 0 rg /DeviceRGB cs 0 0 1 1 re f");
2054        assert_eq!(doc.page(0).unwrap().paths[0].fill, Some([0.0, 0.0, 0.0]));
2055    }
2056}