qpdf_ruby 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5e34005af4a00f153fe6597426be27d03e047c9fce46af4e669c22138e0b726
-  data.tar.gz: 95fb970cb38489fd18b2d8aee4e0f48e843f9b14f45a4806ea7b5b1e6f79045c
+  metadata.gz: 1031f5b376f46ea2e57b4a06692f10fe62f081bf010eff784e7e179c3dca83d1
+  data.tar.gz: aa3e9a16d357779d6b51c7d66c8736641a140a180844cd3f6c5bcbb22988ce32
 SHA512:
-  metadata.gz: 6f1e65790f45ab85cb633883c4f7d8597d8271e15aedf6ef670e58491f0658a0bf53370a232abdda370088bc13594445e292d7e73fda1b34e9fa460a15ae0eef
-  data.tar.gz: be16ec8f1fde0eb5c022a39b29588429319d6aa553fdc368ee90f6a409659a0d7d0a30eba212683e4f5640eb961c127bef46d2f7f4dded9879ab58195c0df67e
+  metadata.gz: baaebb9aa86b819c652f7e2b9f8b593df9419c75d4cf9279e1301b6d0302b43c4aa1c629f2f8e65582ca07dd659889c9397d9286179b627442f29605e6356673
+  data.tar.gz: 6f31a3e8543f7bc23561ef74ad445e9a32e136fcbb0d57721d6058cc158441d4069af1d1ef50480494617d2e367a445316beb3100bfb25e1089dfb8d9eff23cc

data/CHANGELOG.md

@@ -6,11 +6,74 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-[unreleased]: https://github.com///compare/v0.1.1..HEAD
+[unreleased]: https://github.com/dieter-medium/qpdf_ruby/compare/v0.3.0..HEAD
 
-<!-- generated by git-cliff -->
+<!-- generated by git-cliff end -->
 
-##  [0.1.1] - 2025-06-30
+## [0.3.0] - 2026-10-08
+
+Records who made a file: `set_document_info` writes the creator and producer to the information
+dictionary and to XMP, and keeps the two in agreement.
+
+### 🚀 Added
+
+- `set_document_info(creator:, producer:)`: the information dictionary's `/Creator` and
+  `/Producer`, and XMP `xmp:CreatorTool` and `pdf:Producer`, replacing any other value there so the
+  two always agree; `xmp_error` says why a packet that is not well-formed was left alone.
+- `document_info`: the information dictionary's string entries, for inspection.
+
+### 🐛 Fixed
+
+- A `title:` with a NUL, a control character or bytes that are not UTF-8 raises `ArgumentError`
+  instead of writing invalid XMP (`add_pdfua_identification`, `apply_pdfua_fixes`).
+- An XMP property counts only on the document's own `rdf:Description`: a `dc:title` or
+  `pdfuaid:part` nested inside another property no longer suppresses the identification.
+
+## [0.2.0] - 2026-10-02
+
+Makes the tagged PDFs Chromium prints (`Page.printToPDF` with `generateTaggedPDF`) PDF/UA-1
+conformant: `apply_pdfua_fixes` plus `ensure_bbox` take Chromium's output to a file veraPDF accepts
+as PDF/UA-1 and PAC 2024 passes without errors.
+
+### 🚀 Added
+
+- `apply_pdfua_fixes(link_texts:, title:)` runs every step below and returns a report.
+- `artifact_tagged_decorations`: CSS backgrounds and borders Chromium tags as content of a
+  grouping element (a `Table`'s cell backgrounds, an `<article>`'s card) become artifacts.
+- `mark_untagged_content_as_artifacts` and `untagged_content`: untagged paths, text, XObjects,
+  shadings and inline images are wrapped in `/Artifact` (7.1-3), never inside tagged content.
+- `describe_links`: Link annotations get `/Contents` (7.18), from given texts, the structure
+  element's `/Alt`, named and string destinations ("Page N"), or the URI.
+- `wrap_list_bodies`: list item content moves into `LBody` (7.2-20), ParentTree updated.
+- `map_nonstandard_roles`: PDF 2.0 structure types get a RoleMap entry (7.1-5).
+- `retag_grouping_figures`: the `Figure` Chromium wraps around an HTML `<figure>` becomes a `Div`
+  (7.3-1); `figures_without_alt` counts what only a person can fix.
+- `add_pdfua_identification(title:)`: XMP `pdfuaid:part` and `dc:title`, `DisplayDocTitle`,
+  `Marked` (7.1-8).
+- `ensure_bbox` computes Figure bounds from the painted content (images, forms, strokes with line
+  width, caps and joins) and sets `Placement /Block` outside a line of text.
+- `parent_tree_mismatches`, `links`, `metadata` and `role_map` for inspection.
+
+### 🐛 Fixed
+
+- `ensure_bbox`: an uninitialized crop box crashed it, the CTM was replaced instead of
+  concatenated, MCIDs were matched across pages and Form XObjects, and `/A` was overwritten.
+- `to_memory` leaked the QPDF buffer behind every call.
+- Ruby exceptions no longer skip C++ destructors, and a `#to_s` callback that reopens the document
+  can no longer leave a freed handle in use.
+- Builds against QPDF 11.9 as well as QPDF 12, and runs on Ruby 4.
+
+### 🛠️ Development
+
+- veraPDF runs in CI (`bin/install-verapdf.sh`); `bin/asan-rspec.sh` runs the specs under
+  AddressSanitizer and LeakSanitizer.
+- `rake release` checks the push credential first, following RubyGems' own order
+  (`GEM_HOST_API_KEY`, `gem.push_key`, push-host key, `rubygems_api_key`).
+- The Docker image is built in two stages and pushed for linux/amd64 and linux/arm64 from `main`
+  and `v*` tags.
+
+
+## [0.1.1] - 2025-06-30
 
 ### 🚀 Features
 
@@ -24,5 +87,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.1..HEAD)
-- [0.1.1](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.0..v0.1.1) 
+- [unreleased](https://github.com/dieter-medium/qpdf_ruby/compare/v0.3.0..HEAD)
+- [0.3.0](https://github.com/dieter-medium/qpdf_ruby/compare/v0.2.0..v0.3.0)
+- [0.2.0](https://github.com/dieter-medium/qpdf_ruby/compare/v0.1.1..v0.2.0)
+- [0.1.1](https://github.com/dieter-medium/qpdf_ruby/compare/v0.1.0..v0.1.1) 

data/README.md

@@ -1,37 +1,74 @@
 # QpdfRuby
 
-> **Patch & polish PDFs so that PAC 2024 finally turns green.**
-
-QpdfRuby is a very small Ruby wrapper around the battle‑tested
-[QPDF \>= 12](https://qpdf.sourceforge.net/) C++ library.  Right now the
-library focuses on only **three specialised tasks** that are needed when
-PDFs are printed from Chromium‑based browsers and subsequently audited
-with the PAC 2024 accessibility checker:
-
-1. **Export the structure tree as XML** – handy for debugging.
-2. **Mark vector path objects as `/Artifact`** so that decorative lines,
-   boxes, &c. are ignored by assistive technologies.
-3. **Add missing `/BBox` entries to every `/Figure` element** (derived
-   from the page’s graphic operators) so that screen readers know the
-   physical extent of each image.
-
-Together these tweaks eliminate the most common complaints PAC 2024 has
-about browser‑generated PDFs.
-
----
-
-## Features in Detail
-
-| Feature                                        | Ruby API                                 |
-| ---------------------------------------------- | ---------------------------------------- |
-| Dump structure tree as XML                     | `doc.show_structure`                     |
-| Mark path objects ( `re … S/s/f/F/B/b` )       | `doc.mark_paths_as_artifacts`            |
-| Ensure `/Figure` elements have a layout BBox¹  | `doc.ensure_bbox`                        |
-
-_¹Internally the gem parses each page’s content stream, maps image
-`/MCID`s to their transformation matrix, computes the bounding box
-(courtesy of a little linear algebra) and finally writes the result into
-the structure tree._
+> **Make Chromium's tagged PDFs PDF/UA-1 conformant.**
+
+QpdfRuby is a small Ruby wrapper around the [QPDF](https://qpdf.sourceforge.net/) C++ library,
+made for PDFs printed by Chromium (`Page.printToPDF` with `generateTaggedPDF`) and checked with
+veraPDF or PAC 2024. Chromium tags the text of a page but leaves gaps that PDF/UA-1 rejects; the
+gem closes them without touching the content that is tagged:
+
+| PDF/UA-1 rule (veraPDF) | What Chromium does | What QpdfRuby does | Ruby API |
+| --- | --- | --- | --- |
+| 7.1-3 untagged content | backgrounds, borders, bars, `aria-hidden` and SVG decorations end up outside any marked content; it never writes `/Artifact` | wraps every painting operation outside marked content in `/Artifact BMC … EMC` (not a Form XObject that carries tagged content) | `doc.mark_untagged_content_as_artifacts` |
+| PAC: content in an inadmissible location, invalid TR | CSS backgrounds and borders are tagged as content of the grouping element they belong to (a `Table`'s cell backgrounds, an `<article>`'s card) | turns such shape-only content into artifacts and takes it out of the structure tree; content with text stays tagged | `doc.artifact_tagged_decorations` |
+| 7.18.1-2, 7.18.5-2 link descriptions | no `/Contents` on Link annotations | your text per URI, else the structure element's `/Alt`/`/ActualText`, else the URI (internal links: your text for `"#<destination>"`, else "Page N" - named destinations from `/Dests`, string destinations from the `/Names` tree) | `doc.describe_links(texts = {})` |
+| 7.2-20 list items | `LI` holds `Lbl` and the content directly, never `LBody` | moves the content into an `LBody`, ParentTree entries updated (a Form XObject's MCIDs in its own entry) | `doc.wrap_list_bodies` |
+| 7.1-5 non-standard types | PDF 2.0 types (`Strong`, `Em`, `Aside`, …) without a RoleMap | maps them to PDF 1.7 types in the RoleMap (table below) | `doc.map_nonstandard_roles` |
+| 7.3-1 figure alternative | an HTML `<figure>` becomes a `Figure` without alt text around the image's own `Figure` | retags that grouping `Figure` as `Div` | `doc.retag_grouping_figures` |
+| 7.1-8 metadata | no XMP `pdfuaid` identification | adds `pdfuaid:part 1` and `dc:title`, each only if missing (read namespace-aware - a commented-out one does not count, an empty one does; extends existing XMP, never replaces a title), sets `DisplayDocTitle` and `Marked` - the identification only for a file with a structure tree | `doc.add_pdfua_identification(title: nil)` |
+
+`doc.apply_pdfua_fixes(link_texts: {}, title: nil)` runs all of them and returns a report.
+Each step only adds what is missing, so running it twice changes nothing (the report's
+`identified` is true only when the identification step changed something). When the file cannot
+be identified - it has no structure tree, or its existing XMP has no RDF element the gem can find -
+the other steps still run and `unidentified_reason` says why; it is `nil` otherwise. Figures that
+have no alternative text at all cannot be fixed by a tool - `doc.figures_without_alt` counts them.
+
+The RoleMap entries `map_nonstandard_roles` adds, each only for a type the file uses and does not
+map yet. Some are lossy - an assistive technology reads `Title` as a paragraph, `Aside` as a
+section:
+
+| PDF 2.0 type | mapped to |
+| --- | --- |
+| `Aside` | `Sect` |
+| `DocumentFragment` | `Part` |
+| `Em`, `Strong`, `Sub` | `Span` |
+| `FENote` | `Note` |
+| `Title` | `P` |
+
+Untagged content is looked for in page content and the Form XObjects it draws - not in annotation
+appearance streams, tiling patterns or Type 3 glyph procedures, which Chromium does not emit.
+
+Also:
+
+| Feature | Ruby API |
+| --- | --- |
+| Count untagged content (dry run, per kind) | `doc.untagged_content` |
+| Add a layout `/BBox` to every `/Figure`¹, and `/Placement /Block` to one outside a line of text (PAC 2024 warns of a "possibly inappropriate use" of a Figure without it) | `doc.ensure_bbox` |
+| Dump the structure tree as XML | `doc.show_structure` |
+| Set who made the file: Info `/Creator` and `/Producer`, XMP `xmp:CreatorTool` and `pdf:Producer`, kept in agreement (another XMP value is replaced; `xmp_error` says why a packet that is not well-formed was left alone) | `doc.set_document_info(creator:, producer:)` |
+| Inspect links, XMP, RoleMap, the information dictionary | `doc.links`, `doc.metadata`, `doc.role_map`, `doc.document_info` |
+| Count ParentTree entries that do not name their content's structure element (0 = consistent) | `doc.parent_tree_mismatches` |
+| Encrypt | `doc.encrypt(user_pw:, owner_pw:, …)` |
+| Read/write files or memory | `Document.new(path, password = nil)`, `Document.from_memory(bytes, password = nil)`, `#write(path)`, `#to_memory` |
+
+_¹The gem parses each page's content stream, and the content of the Form XObjects it draws, under
+the full transformation matrix and unites what each piece of marked content paints - images, Form
+XObjects, paths - per page, content stream and MCID (a marked-content reference's `/Stm` names the
+form whose MCIDs it means). A stroked path counts with its line width, caps and joins (from `w`, `J`,
+`j`, `M` or an ExtGState); a curve's stroke is bounded a little generously. Text adds nothing (its extent needs font metrics), and content outside
+the crop box is ignored; a Figure with no other content gets the crop box._
+
+`#mark_paths_as_artifacts` is deprecated: it now does what `#mark_untagged_content_as_artifacts`
+does. Its old behaviour - wrapping rectangles anywhere, also inside tagged content - fixed few
+Chromium decorations and broke rules 7.1-1/7.1-2.
+
+Every error raises `QpdfRuby::Error` (a `RuntimeError`); an argument of the wrong type raises
+`TypeError`, an unknown keyword (`tittle:`) `ArgumentError`.
+
+Checked against veraPDF 1.30.2 on Chromium 154 output (`spec/fixtures/chromium/`): both
+fixtures are PDF/UA-1 compliant after `apply_pdfua_fixes`. A machine check covers the machine
+checkable part only - alternative texts, headings and reading order still need a person.
 
 ---
 
@@ -39,8 +76,8 @@ the structure tree._
 
 ### Requirements
 
-* **Ruby** \>= 3.1
-* **QPDF** \>= 12.0.0 (headers & libs)
+* **Ruby** \>= 3.3 (tested with 3.3, 3.4 and 4.0)
+* **QPDF** \>= 11.9 (headers & libs; tested with 11.9.1 and 12.2)
 
 ### macOS
 ```bash
@@ -50,12 +87,11 @@ bundle config set --local build.qpdf_ruby "--with-qpdf-dir=$(brew --prefix qpdf)
 
 ### Debian/Ubuntu
 ```bash
-# on Debian 11/Ubuntu 20.04 you may need newer packages from testing
+# Debian 13 (trixie) and newer ship QPDF 12
 sudo apt-get update && sudo apt-get install -y libqpdf-dev qpdf
 ```
-If `apt` cannot provide QPDF ≥ 12 you can compile it yourself or pull the
-package from *testing/unstable* – see the [Dockerfile](./docker/Dockerfile) for a working
-`apt preferences` snippet.
+If `apt` cannot provide QPDF ≥ 11.9, compile it yourself or use Debian trixie (see the
+[Dockerfile](./docker/Dockerfile)).
 
 ### Add the gem
 ```bash
@@ -70,24 +106,19 @@ bundle add qpdf_ruby
 ```ruby
 require "qpdf_ruby"
 
-pdf = QpdfRuby::Document.new("input.pdf")
-
-# 1. tag decorative paths
-pdf.mark_paths_as_artifacts
+pdf = QpdfRuby::Document.new("chromium-output.pdf")
 
-# 2. add BBox to every <Figure>
-pdf.ensure_bbox
+report = pdf.apply_pdfua_fixes(
+  link_texts: { "mailto:jana@example.com" => "E-mail Jana" }, # optional, per URI or "#destination"
+  title: "Curriculum vitae - Jana Example"                    # optional, else the PDF's /Title
+)
+# => { decorations: 3, artifacts: { paths: 75, texts: 101, …, total: 176 }, links: 2, list_bodies: 34,
+#      roles: 0, figure_groups: 0, figures_without_alt: 0, identified: true, unidentified_reason: nil }
 
-# 3. introspect structure tree (optional)
-File.write("structure.xml", pdf.show_structure)
-
-# 4. save 🎉
-pdf.write("fixed.pdf")
+pdf.ensure_bbox                     # layout BBoxes for figures (PAC 2024 asks for them)
+pdf.write("accessible.pdf")         # or pdf.to_memory
 ```
 
-Run PAC 2024 on `fixed.pdf` – it should report far fewer (or zero!)
-errors compared to the original browser output.
-
 ---
 
 ## Development
@@ -97,7 +128,17 @@ cd qpdf_ruby
 bin/setup        # install gem + test deps
 autotest         # guard & RSpec
 ```
-* Bump **version.rb** → `bundle exec rake release` to push a new gem.
+* Bump **version.rb** → `bundle exec rake release` to push a new gem. It first runs
+  `rake release_credentials_check`, which shows where the push credential comes from: a set
+  `GEM_HOST_API_KEY` wins (as in RubyGems), else `gem.push_key` in the credentials file RubyGems uses,
+  else that file's key for the push host, else its `rubygems_api_key`.
+* `bundle exec rspec` runs the specs; the veraPDF examples run only where `verapdf` is on the
+  `PATH` (`bin/install-verapdf.sh [DIR]` installs the pinned CLI; needs Java). They are skipped
+  otherwise - `REQUIRE_VERAPDF=1`, set in CI, makes them fail instead.
+* `bin/asan-rspec.sh [RSPEC_ARGS]` builds the extension with AddressSanitizer in a scratch copy and
+  runs the specs under it, with LeakSanitizer (`bin/lsan.supp` filters Ruby's own heap) - the way to
+  see a use-after-free a plain run survives by luck. A destructor skipped by a Ruby raise is the one
+  leak it cannot see; `spec/qpdf_ruby/document_error_path_memory_spec.rb` watches RSS for that.
 
 ### Testing with local QPDF builds
 If you tinker with QPDF itself, point Bundler to your custom prefix:
@@ -119,7 +160,7 @@ Bug reports & pull requests are welcome at
 
 ### Code Style
 * C++ 17, clang‑format enforced
-* Ruby 3.2, rubocop default rules
+* Ruby 3.3, rubocop default rules
 
 ---
 

data/ext/qpdf_ruby/document_handle.cpp

@@ -62,7 +62,7 @@ std::string DocumentHandle::write_to_memory() {
     w.setOutputMemory();
     w.write();
 
-    auto b = w.getBuffer();
+    auto b = w.getBufferSharedPointer();  // getBuffer() hands over a Buffer the caller must delete
     return std::string(reinterpret_cast<char const*>(b->getBuffer()), b->getSize());
   } catch (std::exception const& ex) {
     throw std::runtime_error("qpdf_ruby: write_to_memory failed: " + std::string(ex.what()));

data/ext/qpdf_ruby/figure_node.cpp

@@ -1,109 +1,134 @@
 #include "struct_node.hpp"
 
-static void add_bbox(PDFStructWalker& walker, QPDFObjectHandle node) {
-  int mcid = -std::numeric_limits<int>::infinity();
+#include <optional>
+#include <set>
 
-  if (node.getKey("/K").isInteger()) {
-    mcid = node.getKey("/K").getIntValue();
-  }
-
-  // Get the bbox from the walker or use defaults
-
-  QPDFObjectHandle pageObj;
-  QPDFObjectHandle currentNode = node;
-  bool found = false;
+namespace {
 
-  // Try to find /Pg by walking up the parent chain
-  while (currentNode.isDictionary()) {
-    if (currentNode.hasKey("/Pg")) {
-      pageObj = currentNode.getKey("/Pg");
-      found = true;
-      break;
-    }
-
-    if (currentNode.hasKey("/P")) {
-      currentNode = currentNode.getKey("/P");
-    } else {
-      break;  // No more parents to check
-    }
+// The page a structure element's content lives on: its own /Pg or the nearest ancestor's.
+QPDFObjectHandle page_of(QPDFObjectHandle elem) {
+  for (int guard = 0; elem.isDictionary() && guard < 256; ++guard) {
+    if (elem.getKey("/Pg").isDictionary()) return elem.getKey("/Pg");
+    elem = elem.getKey("/P");
   }
+  return QPDFObjectHandle::newNull();
+}
 
-  if (!found && node.hasKey("/K") && node.getKey("/K").isArray()) {
-    QPDFObjectHandle kids = node.getKey("/K");
-    for (int i = 0; i < kids.getArrayNItems(); ++i) {
-      QPDFObjectHandle kid = kids.getArrayItem(i);
-      if (kid.isDictionary() && kid.hasKey("/Pg")) {
-        pageObj = kid.getKey("/Pg");
-        found = true;
-        break;
-      }
-    }
+// Unites the bounds of every piece of marked content below `elem`: direct MCIDs (in the content of
+// the element's page), marked-content references (in their /Stm if given, else their own /Pg's
+// content) and nested structure elements.
+void collect_bounds(QPDFObjectHandle elem, qpdf_ruby::McidBounds const& bounds, std::optional<qpdf_ruby::Box>& out,
+                    std::set<QPDFObjGen>& seen, int depth = 0) {
+  if (depth > 256 || (elem.isIndirect() && !seen.insert(elem.getObjGen()).second)) return;
+  QPDFObjectHandle page = page_of(elem);
+
+  auto add = [&](QPDFObjectHandle on_page, QPDFObjectHandle owner, int mcid) {
+    if (!on_page.isDictionary() || !(owner.isDictionary() || owner.isStream())) return;
+    auto it = bounds.find({on_page.getObjGen(), owner.getObjGen(), mcid});
+    if (it == bounds.end()) return;
+    out = out ? qpdf_ruby::unite(*out, it->second) : it->second;
+  };
+
+  QPDFObjectHandle kids = elem.getKey("/K");
+  std::vector<QPDFObjectHandle> list;
+  if (kids.isArray()) {
+    for (auto kid : kids.aitems()) list.push_back(kid);
+  } else if (!kids.isNull()) {
+    list.push_back(kids);
   }
 
-  if (!found || !pageObj.isIndirect()) {
-    std::cerr << "No /Pg key found for MCID " << mcid << ", cannot add BBox." << std::endl;
-    return;
+  for (auto& kid : list) {
+    if (kid.isInteger()) {
+      add(page, page, kid.getIntValue());
+    } else if (kid.isDictionary() && kid.getKey("/Type").isNameAndEquals("/MCR") && kid.getKey("/MCID").isInteger()) {
+      QPDFObjectHandle on_page = kid.getKey("/Pg").isDictionary() ? kid.getKey("/Pg") : page;
+      // A /Stm that is not a stream names nothing we can look up: no bounds rather than the page's.
+      QPDFObjectHandle owner = kid.hasKey("/Stm") ? kid.getKey("/Stm") : on_page;
+      if (kid.hasKey("/Stm") && !owner.isStream()) continue;
+      add(on_page, owner, kid.getKey("/MCID").getIntValue());
+    } else if (kid.isDictionary() && kid.hasKey("/S")) {
+      collect_bounds(kid, bounds, out, seen, depth + 1);
+    }
   }
+}
 
-  auto media_box = walker.getPageCropBoxFor(pageObj);
-
-  double llx = media_box[0], lly = media_box[1], urx = media_box[2], ury = media_box[3];
-  auto const& bbox_map = walker.getMcidBboxMap();
+bool is_layout(QPDFObjectHandle attrs) {
+  return attrs.isDictionary() && attrs.getKey("/O").isNameAndEquals("/Layout");
+}
 
-  // Use a try/catch to prevent failures when accessing the map
-  try {
-    if (bbox_map.count(mcid) > 0) {
-      auto const& b = bbox_map.at(mcid);
-      llx = b[0];
-      lly = b[1];
-      urx = b[2];
-      ury = b[3];
+// The element's Layout attribute dictionary - /A itself, or the first one in an /A array - or null.
+QPDFObjectHandle layout_of(QPDFObjectHandle attrs) {
+  if (is_layout(attrs)) return attrs;
+  if (attrs.isArray()) {
+    for (auto item : attrs.aitems()) {
+      if (is_layout(item)) return item;
     }
-  } catch (const std::exception& e) {
-    std::cerr << "Error accessing mcid " << mcid << " in bbox map: " << e.what() << std::endl;
-    // Continue with default values
   }
+  return QPDFObjectHandle::newNull();
+}
 
-  QPDFObjectHandle attrs;
-  attrs = QPDFObjectHandle::newDictionary();
-  attrs.replaceKey("/O", QPDFObjectHandle::newName("/Layout"));
-
-  node.replaceKey("/A", attrs);
-
-  if (!attrs.hasKey("/BBox")) {
-    QPDFObjectHandle arr = QPDFObjectHandle::newArray();
-    arr.appendItem(QPDFObjectHandle::newReal(llx));
-    arr.appendItem(QPDFObjectHandle::newReal(lly));
-    arr.appendItem(QPDFObjectHandle::newReal(urx));
-    arr.appendItem(QPDFObjectHandle::newReal(ury));
-
-    attrs.replaceKey("/BBox", arr);
+// Structure types whose content is a line of text: a Figure among them is part of that line.
+const std::set<std::string> kInlineParents = {"/P",    "/H",        "/H1",      "/H2",  "/H3",  "/H4",   "/H5",
+                                              "/H6",   "/Lbl",      "/Span",    "/Quote", "/Note", "/Reference",
+                                              "/BibEntry", "/Code", "/Link",    "/Annot", "/Ruby", "/Warichu",
+                                              "/Strong", "/Em"};
+
+// True if the Figure sits in a line of text - its nearest parent that is not a NonStruct (which
+// only groups, ISO 32000-1 14.8.4.2) is one of kInlineParents.
+bool in_inline_context(QPDFObjectHandle elem) {
+  QPDFObjectHandle parent = elem.getKey("/P");
+  for (int guard = 0; guard < 64 && parent.isDictionary(); ++guard) {
+    if (!parent.getKey("/S").isNameAndEquals("/NonStruct")) break;
+    parent = parent.getKey("/P");
   }
+  QPDFObjectHandle type = parent.isDictionary() ? parent.getKey("/S") : QPDFObjectHandle::newNull();
+  return type.isName() && kInlineParents.count(type.getName()) > 0;
+}
+
+QPDFObjectHandle box_array(qpdf_ruby::Box const& box) {
+  QPDFObjectHandle array = QPDFObjectHandle::newArray();
+  for (double value : box) array.appendItem(QPDFObjectHandle::newReal(value, 4));
+  return array;
 }
 
+}  // namespace
+
+// Gives the Figure a Layout attribute with a /BBox (its painted bounds) and, outside a line of text,
+// /Placement /Block - without the placement PAC 2024 warns of a "possibly inappropriate use" of the
+// Figure (checked 2026-10-02). Existing values are kept; an existing attribute object is extended.
 void FigureNode::ensureLayoutBBox(PDFStructWalker& walker) {
   StructElemNode::ensureLayoutBBox(walker);
 
-  // Bail if a BBox is already present *anywhere* in /A
-  if (node.hasKey("/A")) {
-    QPDFObjectHandle A = node.getKey("/A");
-    auto has_bbox = [](QPDFObjectHandle const& dict) {
-      QPDFObjectHandle non_const_dict = dict;
-      return non_const_dict.isDictionary() && non_const_dict.hasKey("/O") &&
-             non_const_dict.getKey("/O").getName() == "/Layout" && non_const_dict.hasKey("/BBox");
-    };
-
-    if ((A.isDictionary() && has_bbox(A)) || (A.isArray() && [&]() -> bool {
-          for (int i = 0; i < A.getArrayNItems(); ++i) {
-            if (has_bbox(A.getArrayItem(i))) {
-              return true;
-            }
-          }
-          return false;
-        }())) {
-      return;  // nothing to do
-    }
+  QPDFObjectHandle attrs = node.getKey("/A");
+  QPDFObjectHandle layout = layout_of(attrs);
+  bool needs_bbox = !(layout.isDictionary() && layout.hasKey("/BBox"));
+  bool needs_placement = !(layout.isDictionary() && layout.hasKey("/Placement")) && !in_inline_context(node);
+  if (!needs_bbox && !needs_placement) return;
+
+  std::optional<qpdf_ruby::Box> box;
+  if (needs_bbox) {
+    std::set<QPDFObjGen> seen;
+    collect_bounds(node, walker.getMcidBounds(), box, seen);
+    QPDFObjectHandle page = page_of(node);
+    if (!box && page.isDictionary()) box = walker.getPageCropBoxFor(page);  // else nothing to anchor it to
   }
+  if (!box && !needs_placement) return;
 
-  add_bbox(walker, node);
-}
+  bool attached = layout.isDictionary();
+  if (!attached) {
+    layout = QPDFObjectHandle::newDictionary();
+    layout.replaceKey("/O", QPDFObjectHandle::newName("/Layout"));
+  }
+  if (box) layout.replaceKey("/BBox", box_array(*box));
+  if (needs_placement) layout.replaceKey("/Placement", QPDFObjectHandle::newName("/Block"));
+  if (attached) return;
+
+  // Keep every existing attribute object: append the new Layout dictionary to them.
+  if (attrs.isArray()) {
+    attrs.appendItem(layout);
+  } else if (attrs.isDictionary()) {
+    node.replaceKey("/A", QPDFObjectHandle::newArray({attrs, layout}));
+  } else {
+    node.replaceKey("/A", layout);
+  }
+}