feat(html): let a host put a floor under the margin a view keeps

`HtmlConfig::min_content_margin` states, per side, the least distance the
generated content keeps from the view's border. Every view already insets
its content by some amount it names itself — 3mm for a reflowed text
document, 16px for the page column and the source views, 8px for a font
specimen, nothing for an image or a file listing — and no single number
could stand in for all of them, so the config is a floor rather than a
value: an unset side leaves the view exactly where it was, a set one only
ever raises it.

The arithmetic is css's. Each inset becomes `max(own, var(--odr-min-margin-*,
0px))`, so the view's own measure stays in the stylesheet and no unit has to
be converted to state it. `write_content_margin_style` declares the variables
per view and writes nothing at all when no side is set, which is what keeps
the shipped stylesheets independent of the config — they are shared under one
name when the config links rather than embeds them.

One place still needs the number: the gutter around the page column is part
of the width the view is fitted to, so `page_column_gutter_pixels` reads the
config and a side css can read but `css_pixels` cannot convert keeps the
built-in gutter — the margin still applies, only the fit cannot count it. A
unit css could not read at all is dropped rather than written into the style
element it would otherwise close.

A sheet and the media view are not inset: the one meets the edge by design,
the other is full-bleed.

Bound in python, jni, wasm (`minContentMargin`, css lengths as strings) and
apple, where `ODRMeasure` and `ODRDirectionalMeasure` gain the initialisers a
caller needs to state one.

Rendering with the default config is unchanged: every reference document is
byte-identical, and the stylesheets that did change render pixel-identically
under `compare-html`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UoWywNazPio5vphzB59U5g

Author: andiwand

CHANGELOG.md

@@ -16,6 +16,13 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
+- `HtmlConfig::min_content_margin` puts a floor under the distance the
+  generated content keeps from the view's border, per side. Unset, every view
+  keeps the inset it has today; a set side raises it - in a reflowed text
+  document, the page column of a text, presentation, drawing or pdf view, the
+  text and xml source views, the file listing, the image view and the font
+  specimen. A sheet and the media view are not inset. Bound in python, jni,
+  wasm (`minContentMargin`, css lengths as strings) and apple.
 - **Breaking** Bytes that do not read as text no longer come back as
   `text_file` and render as nonsense - `decode` throws `UnknownFileType` and
   `list_file_types` comes back empty. A file is text when it is empty, or its

apple/include/OdrCoreObjC/ODRHtml.h

@@ -1,6 +1,7 @@
 #import <Foundation/Foundation.h>
 
 #import <OdrCoreObjC/ODRFilesystem.h>
+#import <OdrCoreObjC/ODRStyle.h>
 #import <OdrCoreObjC/ODRTable.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -101,6 +102,11 @@ NS_SWIFT_NAME(HtmlConfig)
 /// The zoom the view opens at, 1 being actual size; `nil` follows the fit.
 @property(nonatomic, strong, nullable) NSNumber *initialZoom;
 
+/// The least distance the generated content keeps from the view's border. A
+/// `nil` side keeps the inset the view already has; a set side raises it,
+/// never lowers it.
+@property(nonatomic, strong) ODRDirectionalMeasure *minContentMargin;
+
 @property(nonatomic) BOOL formatHtml;
 /// Repeated `htmlIndentString` per nesting level; 0 disables indentation.
 @property(nonatomic) uint8_t htmlIndent;

apple/include/OdrCoreObjC/ODRStyle.h

@@ -79,6 +79,11 @@ NS_SWIFT_NAME(Measure)
 /// Magnitude and unit as odrcore writes them, e.g. `12pt`.
 @property(nonatomic, readonly, copy) NSString *stringValue;
 
+/// A css length as odrcore writes one, e.g. `3mm`. A magnitude with no unit
+/// reads as unitless.
+- (instancetype)initWithString:(NSString *)string;
+- (instancetype)initWithMagnitude:(double)magnitude unit:(NSString *)unit;
+
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
 @end
@@ -92,6 +97,13 @@ NS_SWIFT_NAME(DirectionalMeasure)
 @property(nonatomic, readonly, nullable) ODRMeasure *left;
 @property(nonatomic, readonly, nullable) ODRMeasure *bottom;
 
+/// For the sides a caller states itself, e.g.
+/// @ref ODRHtmlConfig.minContentMargin.
+- (instancetype)initWithRight:(nullable ODRMeasure *)right
+                          top:(nullable ODRMeasure *)top
+                         left:(nullable ODRMeasure *)left
+                       bottom:(nullable ODRMeasure *)bottom;
+
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
 @end

apple/src/ODRHtml.mm

@@ -108,6 +108,8 @@ - (instancetype)initWithNativeConfig:(const odr::HtmlConfig &)config {
   _viewportContent = config.viewport_content.has_value()
                          ? to_nsstring(*config.viewport_content)
                          : nil;
+  _minContentMargin =
+      [ODRDirectionalMeasure directionalWithHandle:config.min_content_margin];
   _viewportWidth = config.viewport_width.has_value()
                        ? @(static_cast<unsigned int>(*config.viewport_width))
                        : nil;
@@ -187,6 +189,11 @@ - (instancetype)initWithNativeConfig:(const odr::HtmlConfig &)config {
   } else {
     config.initial_zoom.reset();
   }
+  if (_minContentMargin != nil) {
+    config.min_content_margin = _minContentMargin.handle;
+  } else {
+    config.min_content_margin = odr::DirectionalStyle<odr::Measure>();
+  }
   config.format_html = _formatHtml == YES;
   config.html_indent = _htmlIndent;
   config.html_indent_string = to_string(_htmlIndentString);

apple/src/ODRPrivate.h

@@ -17,6 +17,8 @@
 #include <odr/logger.hpp>
 #include <odr/style.hpp>
 
+#include <optional>
+
 /// Cross-translation-unit access to the C++ value each wrapper owns.
 ///
 /// Each `@implementation` holds its handle as an ivar, destroyed by ARC's
@@ -85,11 +87,13 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface ODRMeasure (Private)
 + (instancetype)measureWithHandle:(const odr::Measure &)handle;
+- (const std::optional<odr::Measure> &)handle;
 @end
 
 @interface ODRDirectionalMeasure (Private)
 + (instancetype)directionalWithHandle:
     (const odr::DirectionalStyle<odr::Measure> &)handle;
+- (odr::DirectionalStyle<odr::Measure>)handle;
 @end
 
 @interface ODRDirectionalString (Private)

apple/src/ODRStyle.mm

@@ -9,6 +9,7 @@
 
 using odr::apple::guarded_value;
 using odr::apple::to_nsstring;
+using odr::apple::to_string;
 
 ODR_SAME_ENUM(ODRFontWeightNormal, odr::FontWeight::normal);
 ODR_SAME_ENUM(ODRFontWeightBold, odr::FontWeight::bold);
@@ -107,6 +108,26 @@ - (NSString *)stringValue {
   return guarded_value([&] { return to_nsstring(_handle->to_string()); }, @"");
 }
 
+- (instancetype)initWithString:(NSString *)string {
+  if ((self = [super init]) == nil) {
+    return nil;
+  }
+  _handle = odr::Measure(to_string(string));
+  return self;
+}
+
+- (instancetype)initWithMagnitude:(double)magnitude unit:(NSString *)unit {
+  if ((self = [super init]) == nil) {
+    return nil;
+  }
+  _handle = odr::Measure(magnitude, odr::DynamicUnit(to_string(unit)));
+  return self;
+}
+
+- (const std::optional<odr::Measure> &)handle {
+  return _handle;
+}
+
 - (NSString *)description {
   return self.stringValue;
 }
@@ -127,6 +148,29 @@ + (instancetype)directionalWithHandle:
   return result;
 }
 
+- (instancetype)initWithRight:(ODRMeasure *)right
+                          top:(ODRMeasure *)top
+                         left:(ODRMeasure *)left
+                       bottom:(ODRMeasure *)bottom {
+  if ((self = [super init]) == nil) {
+    return nil;
+  }
+  _right = right;
+  _top = top;
+  _left = left;
+  _bottom = bottom;
+  return self;
+}
+
+- (odr::DirectionalStyle<odr::Measure>)handle {
+  odr::DirectionalStyle<odr::Measure> result;
+  result.right = _right != nil ? _right.handle : std::nullopt;
+  result.top = _top != nil ? _top.handle : std::nullopt;
+  result.left = _left != nil ? _left.handle : std::nullopt;
+  result.bottom = _bottom != nil ? _bottom.handle : std::nullopt;
+  return result;
+}
+
 @end
 
 @implementation ODRDirectionalString

apple/tests/OdrCoreTests.swift

@@ -119,6 +119,26 @@ final class HtmlTests: XCTestCase {
     XCTAssertTrue(html.contains("<style"), "the html has no stylesheet")
   }
 
+  /// The C++ suite covers where the floor lands; this only proves the margin
+  /// crosses the binding, `nil` sides and all.
+  func testMinContentMarginReachesTheHtml() throws {
+    let config = HtmlConfig()
+    config.minContentMargin = DirectionalMeasure(
+      right: nil, top: Measure(string: "12px"), left: Measure(string: "1cm"),
+      bottom: nil)
+
+    let file = try DecodedFile.decode(path: try Fixture.odt())
+    let service = try HtmlTranslator.translate(
+      file: file, cachePath: try temporaryDirectory(), config: config)
+    var resources: NSArray?
+    let html = try XCTUnwrap(service.views.first).writeHtml(resources: &resources)
+
+    XCTAssertTrue(
+      html.contains(":root{--odr-min-margin-top:12px;--odr-min-margin-left:1cm;}"),
+      "the margin did not reach the html")
+    XCTAssertFalse(html.contains("--odr-min-margin-right:"), "an unset side was written")
+  }
+
   /// A view's impl points into its service without owning it, so the view has
   /// to keep the service alive itself — the analogue of
   /// `ElementTreeTests.testElementsKeepTheirDocumentAlive`. Rendering off a

jni/java/app/opendocument/core/HtmlConfig.java

@@ -42,6 +42,13 @@ public final class HtmlConfig {
   /** The zoom the view opens at, 1 being actual size; {@code null} follows the fit. */
   public Double initialZoom;
 
+  /**
+   * The least distance the generated content keeps from the view's border. A {@code null} side
+   * keeps the inset the view already has; a set side raises it, never lowers it.
+   */
+  public DirectionalMeasure minContentMargin =
+      new DirectionalMeasure(null, null, null, null);
+
   public boolean formatHtml = false;
   public int htmlIndent = 1;
   public String htmlIndentString = "\t";

jni/src/jni_style.cpp

@@ -173,6 +173,44 @@ make_directional_measure(JNIEnv *env,
       make_measure(env, style.left), make_measure(env, style.bottom));
 }
 
+std::optional<odr::Measure> measure_from_java(JNIEnv *env, jobject value) {
+  if (value == nullptr) {
+    return std::nullopt;
+  }
+  jclass cls = env->GetObjectClass(value);
+  const double magnitude =
+      env->GetDoubleField(value, env->GetFieldID(cls, "magnitude", "D"));
+  auto unit = static_cast<jstring>(env->GetObjectField(
+      value, env->GetFieldID(cls, "unit", "Ljava/lang/String;")));
+  const odr::Measure result(magnitude, odr::DynamicUnit(to_string(env, unit)));
+  env->DeleteLocalRef(unit);
+  env->DeleteLocalRef(cls);
+  return result;
+}
+
+odr::DirectionalStyle<odr::Measure>
+directional_measure_from_java(JNIEnv *env, jobject value) {
+  odr::DirectionalStyle<odr::Measure> result;
+  if (value == nullptr) {
+    return result;
+  }
+
+  jclass cls = env->GetObjectClass(value);
+  const auto side = [&](const char *name) {
+    jobject measure = env->GetObjectField(
+        value, env->GetFieldID(cls, name, "Lapp/opendocument/core/Measure;"));
+    std::optional<odr::Measure> parsed = measure_from_java(env, measure);
+    env->DeleteLocalRef(measure);
+    return parsed;
+  };
+  result.right = side("right");
+  result.top = side("top");
+  result.left = side("left");
+  result.bottom = side("bottom");
+  env->DeleteLocalRef(cls);
+  return result;
+}
+
 jobject
 make_directional_string(JNIEnv *env,
                         const odr::DirectionalStyle<std::string> &style) {
@@ -374,6 +412,8 @@ jobject html_config_to_java(JNIEnv *env, const odr::HtmlConfig &config) {
              box_integer(env, config.viewport_width));
   set_object("initialZoom", "Ljava/lang/Double;",
              box_double(env, config.initial_zoom));
+  set_object("minContentMargin", "Lapp/opendocument/core/DirectionalMeasure;",
+             make_directional_measure(env, config.min_content_margin));
   set_boolean("formatHtml", config.format_html);
   set_int("htmlIndent", config.html_indent);
   set_string("htmlIndentString", config.html_indent_string);
@@ -540,6 +580,12 @@ odr::HtmlConfig html_config_from_java(JNIEnv *env, jobject config) {
     }
     env->DeleteLocalRef(zoom);
   }
+  {
+    jobject margin = get_object("minContentMargin",
+                                "Lapp/opendocument/core/DirectionalMeasure;");
+    result.min_content_margin = directional_measure_from_java(env, margin);
+    env->DeleteLocalRef(margin);
+  }
   result.format_html = get_boolean("formatHtml");
   result.html_indent = static_cast<std::uint8_t>(get_int("htmlIndent"));
   result.html_indent_string = get_string("htmlIndentString");

jni/tests/app/opendocument/core/HtmlTest.java

@@ -62,6 +62,26 @@ void viewportConfigRoundTrips() throws IOException {
     assertEquals(Double.valueOf(1.5), readBack.initialZoom);
   }
 
+  /** The C++ suite covers where the floor lands; this only proves it crosses JNI. */
+  @Test
+  void minContentMarginReachesTheHtml() throws IOException {
+    assertNull(new HtmlConfig().minContentMargin.top);
+    assertTrue(!renderOdt(new HtmlConfig()).contains(":root{--odr-min-margin"));
+
+    HtmlConfig config = new HtmlConfig();
+    config.minContentMargin =
+        new DirectionalMeasure(null, new Measure(12, "px"), new Measure(1, "cm"), null);
+    assertTrue(
+        renderOdt(config).contains(":root{--odr-min-margin-top:12px;--odr-min-margin-left:1cm;}"));
+
+    Path cache = Files.createDirectories(tempDir.resolve("margin"));
+    DecodedFile file = Odr.open(TestFiles.odtFile(tempDir).toString());
+    HtmlConfig readBack = Html.translate(file, cache.toString(), config).config();
+    assertEquals(new Measure(12, "px"), readBack.minContentMargin.top);
+    assertEquals(new Measure(1, "cm"), readBack.minContentMargin.left);
+    assertNull(readBack.minContentMargin.right);
+  }
+
   /** The C++ suite covers the mode matrix; this only proves the config crosses JNI. */
   @Test
   void viewportModeReachesTheHtml() throws IOException {