From f7d106b57a5498df81f290b9e27359cc3bfc488f Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Tue, 18 Aug 2026 08:21:47 +0200
Subject: [PATCH 1/4] feat(html): read a document in the dark
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`HtmlConfig::color_scheme` is `light` — a white page, what every document has
rendered against until now — or `dark`, or `system`, which follows the reader's
`prefers-color-scheme`. It reaches every document type: a text document flowing
or paged, a sheet, a slide, a drawing.

The colors a file authors arrive as inline styles, which no media query can
reach, so a dark scheme cannot drop them as the file is read: a document setting
`fo:color="#000000"` would render black on black. `dark.css` overrides them
instead — every fill gives way to the page and every run of text to one legible
against it, which costs a slide its own fills and is what keeps its text
readable. A `background-image` is left alone: a page printed on a picture keeps
it.

Rather than writing every rule twice, once plain and once inside a query, the
stylesheet is written once and the element carrying it is gated —
`<style media="(prefers-color-scheme: dark)">`, or the same attribute on the
`<link>` where the config links shipped resources. One asset, one cascade, both
modes, and `light` emits nothing at all: it declares no `color-scheme` either,
so a reader whose webview darkens the page for them keeps that until the apps
offer the setting.

Reflowed to the viewport, a text document also gets 3mm of padding. It had none:
there is no page box to inset it there, and the body carries no margin of its
own, so the text began at the first pixel of the screen. A page's own margin is
a physical measure and so is this one, rather than a `ch` of whatever font the
browser happens to default to.

Mirrored in the python, wasm, jni and apple bindings as `HtmlColorScheme`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rD1SK4k5Y6GQSzbCeKExY
---
 CHANGELOG.md                                  |  9 +++
 apple/include/OdrCoreObjC/ODRHtml.h           | 13 ++++
 apple/src/ODRHtml.mm                          |  6 ++
 jni/CMakeLists.txt                            |  1 +
 .../opendocument/core/HtmlColorScheme.java    | 14 ++++
 .../app/opendocument/core/HtmlConfig.java     |  3 +
 jni/src/jni_style.cpp                         | 11 +++
 jni/tests/app/opendocument/core/HtmlTest.java | 16 +++++
 python/src/bind_html.cpp                      |  6 ++
 python/tests/test_html.py                     |  8 +++
 src/odr/html.hpp                              | 14 ++++
 src/odr/internal/html/document.cpp            |  4 +-
 src/odr/internal/html/frontend.cpp            | 64 ++++++++++++++++-
 src/odr/internal/html/frontend.hpp            |  4 ++
 src/odr/internal/html/html_writer.cpp         | 17 +++--
 src/odr/internal/html/html_writer.hpp         |  6 +-
 test/src/html_test.cpp                        | 70 +++++++++++++++++++
 wasm/js/index.d.ts                            |  2 +
 wasm/src/wasm_core.cpp                        |  4 ++
 wasm/src/wasm_html.cpp                        |  1 +
 wasm/tests/enums.test.mjs                     |  1 +
 21 files changed, 264 insertions(+), 10 deletions(-)
 create mode 100644 jni/java/app/opendocument/core/HtmlColorScheme.java

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c054a0869..be2632e3a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,15 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
+- A document can be read in the dark: `HtmlConfig::color_scheme` is `light` (a
+  white page, what it has always been), `dark`, or `system`, which follows the
+  reader's `prefers-color-scheme`. It reaches every document type, and the
+  colors the file itself authored give way to it — a fill to the page, a run of
+  text to one legible against it — because no media query reaches an inline
+  style. Mirrored in the python, wasm, jni and apple bindings as
+  `HtmlColorScheme`.
+- A text document reflowed to the viewport — page margins off — is inset from
+  the edge of the screen by 3mm instead of starting at the first pixel of it.
 - Prose is no longer read as a csv. A separator that every field follows with a
   space, in fields long enough to be sentences, is punctuation; `a, b, c` with
   short values is still a csv. One record is a line, not a table.
diff --git a/apple/include/OdrCoreObjC/ODRHtml.h b/apple/include/OdrCoreObjC/ODRHtml.h
index c93b22a3c..acbddc103 100644
--- a/apple/include/OdrCoreObjC/ODRHtml.h
+++ b/apple/include/OdrCoreObjC/ODRHtml.h
@@ -26,6 +26,17 @@ typedef NS_ENUM(NSInteger, ODRHtmlTableGridlines) {
   ODRHtmlTableGridlinesHard,
 } NS_SWIFT_NAME(HtmlTableGridlines);
 
+/// The colors the emitted HTML renders a document against. Only the document
+/// views honor it; a pdf, a source view or a file listing brings its own.
+typedef NS_ENUM(NSInteger, ODRHtmlColorScheme) {
+  /// A white page, carrying the colors the document gives its content.
+  ODRHtmlColorSchemeLight = 0,
+  /// A dark page, which the document's own text and fill colors give way to.
+  ODRHtmlColorSchemeDark,
+  /// Light or dark, by the reader's `prefers-color-scheme`.
+  ODRHtmlColorSchemeSystem,
+} NS_SWIFT_NAME(HtmlColorScheme);
+
 /// Initial zoom of the emitted HTML on mobile (the viewport meta tag). Desktop
 /// browsers ignore it entirely.
 typedef NS_ENUM(NSInteger, ODRHtmlViewportMode) {
@@ -71,6 +82,8 @@ NS_SWIFT_NAME(HtmlConfig)
 @property(nonatomic) BOOL editable;
 @property(nonatomic) BOOL textDocumentMargin;
 
+@property(nonatomic) ODRHtmlColorScheme colorScheme;
+
 /// `nil` for no limit.
 @property(nonatomic, strong, nullable) NSValue *spreadsheetLimit;
 @property(nonatomic) BOOL spreadsheetLimitByContent;
diff --git a/apple/src/ODRHtml.mm b/apple/src/ODRHtml.mm
index 6881fb8dd..bb8fb3201 100644
--- a/apple/src/ODRHtml.mm
+++ b/apple/src/ODRHtml.mm
@@ -27,6 +27,10 @@
 ODR_SAME_ENUM(ODRHtmlTableGridlinesSoft, odr::HtmlTableGridlines::soft);
 ODR_SAME_ENUM(ODRHtmlTableGridlinesHard, odr::HtmlTableGridlines::hard);
 
+ODR_SAME_ENUM(ODRHtmlColorSchemeLight, odr::HtmlColorScheme::light);
+ODR_SAME_ENUM(ODRHtmlColorSchemeDark, odr::HtmlColorScheme::dark);
+ODR_SAME_ENUM(ODRHtmlColorSchemeSystem, odr::HtmlColorScheme::system);
+
 ODR_SAME_ENUM(ODRHtmlViewportModeAutomatic, odr::HtmlViewportMode::automatic);
 ODR_SAME_ENUM(ODRHtmlViewportModeFitWidth, odr::HtmlViewportMode::fit_width);
 ODR_SAME_ENUM(ODRHtmlViewportModeActualSize,
@@ -84,6 +88,7 @@ - (instancetype)initWithNativeConfig:(const odr::HtmlConfig &)config {
   _relativeResourcePaths = config.relative_resource_paths ? YES : NO;
   _editable = config.editable ? YES : NO;
   _textDocumentMargin = config.text_document_margin ? YES : NO;
+  _colorScheme = static_cast<ODRHtmlColorScheme>(config.color_scheme);
   if (config.spreadsheet_limit.has_value()) {
     const ODRTableDimensions limit = ODRTableDimensionsMake(
         config.spreadsheet_limit->rows, config.spreadsheet_limit->columns);
@@ -141,6 +146,7 @@ - (instancetype)initWithNativeConfig:(const odr::HtmlConfig &)config {
   config.relative_resource_paths = _relativeResourcePaths == YES;
   config.editable = _editable == YES;
   config.text_document_margin = _textDocumentMargin == YES;
+  config.color_scheme = static_cast<odr::HtmlColorScheme>(_colorScheme);
   if (_spreadsheetLimit != nil) {
     ODRTableDimensions limit{};
     [_spreadsheetLimit getValue:&limit size:sizeof(limit)];
diff --git a/jni/CMakeLists.txt b/jni/CMakeLists.txt
index e0f36089a..e5ced466a 100644
--- a/jni/CMakeLists.txt
+++ b/jni/CMakeLists.txt
@@ -105,6 +105,7 @@ add_jar(odr_java
         "java/app/opendocument/core/GuardedNativeResource.java"
         "java/app/opendocument/core/HorizontalAlign.java"
         "java/app/opendocument/core/Html.java"
+        "java/app/opendocument/core/HtmlColorScheme.java"
         "java/app/opendocument/core/HtmlConfig.java"
         "java/app/opendocument/core/HtmlPage.java"
         "java/app/opendocument/core/HtmlResource.java"
diff --git a/jni/java/app/opendocument/core/HtmlColorScheme.java b/jni/java/app/opendocument/core/HtmlColorScheme.java
new file mode 100644
index 000000000..bdd96409c
--- /dev/null
+++ b/jni/java/app/opendocument/core/HtmlColorScheme.java
@@ -0,0 +1,14 @@
+package app.opendocument.core;
+
+/** Mirrors {@code odr::HtmlColorScheme}; constant order must match the C++ declaration. */
+public enum HtmlColorScheme {
+  LIGHT, DARK, SYSTEM;
+
+  static HtmlColorScheme fromNative(int code) {
+    return code < 0 ? null : values()[code];
+  }
+
+  int toNative() {
+    return ordinal();
+  }
+}
diff --git a/jni/java/app/opendocument/core/HtmlConfig.java b/jni/java/app/opendocument/core/HtmlConfig.java
index 7621ef191..4d9c3a61c 100644
--- a/jni/java/app/opendocument/core/HtmlConfig.java
+++ b/jni/java/app/opendocument/core/HtmlConfig.java
@@ -23,6 +23,9 @@ public final class HtmlConfig {
 
   public boolean textDocumentMargin = false;
 
+  /** The colors a document renders against. */
+  public HtmlColorScheme colorScheme = HtmlColorScheme.LIGHT;
+
   /** {@code null} disables the spreadsheet limit. */
   public TableDimensions spreadsheetLimit = new TableDimensions(10000, 500);
   public boolean spreadsheetLimitByContent = true;
diff --git a/jni/src/jni_style.cpp b/jni/src/jni_style.cpp
index 84a6c6c89..e890ff1b6 100644
--- a/jni/src/jni_style.cpp
+++ b/jni/src/jni_style.cpp
@@ -344,6 +344,9 @@ jobject html_config_to_java(JNIEnv *env, const odr::HtmlConfig &config) {
   set_boolean("relativeResourcePaths", config.relative_resource_paths);
   set_boolean("editable", config.editable);
   set_boolean("textDocumentMargin", config.text_document_margin);
+  set_object("colorScheme", "Lapp/opendocument/core/HtmlColorScheme;",
+             enum_from_code(env, "app/opendocument/core/HtmlColorScheme",
+                            static_cast<jint>(config.color_scheme)));
   set_object("spreadsheetLimit", "Lapp/opendocument/core/TableDimensions;",
              config.spreadsheet_limit.has_value()
                  ? make_table_dimensions(env, *config.spreadsheet_limit)
@@ -452,6 +455,14 @@ odr::HtmlConfig html_config_from_java(JNIEnv *env, jobject config) {
   result.relative_resource_paths = get_boolean("relativeResourcePaths");
   result.editable = get_boolean("editable");
   result.text_document_margin = get_boolean("textDocumentMargin");
+  {
+    const jint code = enum_ordinal(
+        env,
+        get_object("colorScheme", "Lapp/opendocument/core/HtmlColorScheme;"));
+    if (code >= 0) {
+      result.color_scheme = static_cast<odr::HtmlColorScheme>(code);
+    }
+  }
   {
     jobject limit = get_object("spreadsheetLimit",
                                "Lapp/opendocument/core/TableDimensions;");
diff --git a/jni/tests/app/opendocument/core/HtmlTest.java b/jni/tests/app/opendocument/core/HtmlTest.java
index b5b9bc86c..747f79f8c 100644
--- a/jni/tests/app/opendocument/core/HtmlTest.java
+++ b/jni/tests/app/opendocument/core/HtmlTest.java
@@ -80,6 +80,22 @@ void viewportModeReachesTheHtml() throws IOException {
     assertTrue(renderOdt(raw).contains("<meta name=\"viewport\" content=\"width=420\"/>"));
   }
 
+  /** The C++ suite covers what the scheme paints; this only proves it crosses JNI. */
+  @Test
+  void colorSchemeReachesTheHtml() throws IOException {
+    assertEquals(HtmlColorScheme.LIGHT, new HtmlConfig().colorScheme);
+    assertTrue(!renderOdt(new HtmlConfig()).contains("prefers-color-scheme"));
+
+    HtmlConfig system = new HtmlConfig();
+    system.colorScheme = HtmlColorScheme.SYSTEM;
+    assertTrue(renderOdt(system).contains("media=\"(prefers-color-scheme: dark)\""));
+
+    Path cache = Files.createDirectories(tempDir.resolve("scheme"));
+    DecodedFile file = Odr.open(TestFiles.odtFile(tempDir).toString());
+    HtmlConfig readBack = Html.translate(file, cache.toString(), system).config();
+    assertEquals(HtmlColorScheme.SYSTEM, readBack.colorScheme);
+  }
+
   @Test
   void translateText() throws IOException {
     Html html = translateOffline(TestFiles.txtFile(tempDir));
diff --git a/python/src/bind_html.cpp b/python/src/bind_html.cpp
index 375b838ce..956b1d177 100644
--- a/python/src/bind_html.cpp
+++ b/python/src/bind_html.cpp
@@ -30,6 +30,11 @@ void odr_python::bind_html(py::module_ &m) {
       .value("soft", odr::HtmlTableGridlines::soft)
       .value("hard", odr::HtmlTableGridlines::hard);
 
+  py::enum_<odr::HtmlColorScheme>(m, "HtmlColorScheme")
+      .value("light", odr::HtmlColorScheme::light)
+      .value("dark", odr::HtmlColorScheme::dark)
+      .value("system", odr::HtmlColorScheme::system);
+
   py::enum_<odr::HtmlViewportMode>(m, "HtmlViewportMode")
       .value("automatic", odr::HtmlViewportMode::automatic)
       .value("fit_width", odr::HtmlViewportMode::fit_width)
@@ -75,6 +80,7 @@ void odr_python::bind_html(py::module_ &m) {
       .def_readwrite("editable", &odr::HtmlConfig::editable)
       .def_readwrite("text_document_margin",
                      &odr::HtmlConfig::text_document_margin)
+      .def_readwrite("color_scheme", &odr::HtmlConfig::color_scheme)
       .def_readwrite("spreadsheet_limit", &odr::HtmlConfig::spreadsheet_limit)
       .def_readwrite("spreadsheet_limit_by_content",
                      &odr::HtmlConfig::spreadsheet_limit_by_content)
diff --git a/python/tests/test_html.py b/python/tests/test_html.py
index be5382c01..e55c14346 100644
--- a/python/tests/test_html.py
+++ b/python/tests/test_html.py
@@ -26,6 +26,14 @@ def test_html_config_defaults():
     assert config.spreadsheet_limit.rows == 100
 
 
+def test_html_config_color_scheme_defaults():
+    config = pyodr.HtmlConfig()
+    assert config.color_scheme == pyodr.HtmlColorScheme.light
+
+    config.color_scheme = pyodr.HtmlColorScheme.system
+    assert config.color_scheme == pyodr.HtmlColorScheme.system
+
+
 def test_html_config_viewport_defaults():
     config = pyodr.HtmlConfig()
     assert config.viewport_mode == pyodr.HtmlViewportMode.automatic
diff --git a/src/odr/html.hpp b/src/odr/html.hpp
index 4a4b06cf8..f1ee2e4b4 100644
--- a/src/odr/html.hpp
+++ b/src/odr/html.hpp
@@ -73,6 +73,17 @@ enum class HtmlTableGridlines {
   hard,
 };
 
+/// @brief The colors the emitted HTML renders a document against. Only the
+/// document views honor it; a pdf, a source view or a file listing brings its
+/// own.
+enum class HtmlColorScheme {
+  light, ///< a white page, carrying the colors the document gives its content
+  dark,  ///< a dark page, which the document's own text and fill colors give
+         ///< way to — no media query reaches an inline style, so they lose to
+         ///< `!important` rather than being dropped as the file is read
+  system, ///< `light` or `dark`, by the reader's `prefers-color-scheme`
+};
+
 /// @brief Initial zoom of the emitted HTML on mobile (viewport meta tag).
 /// Desktop browsers ignore the tag entirely.
 enum class HtmlViewportMode {
@@ -124,6 +135,9 @@ struct HtmlConfig {
   // text document margin
   bool text_document_margin{false};
 
+  // colors the document renders against
+  HtmlColorScheme color_scheme{HtmlColorScheme::light};
+
   // spreadsheet table limit
   std::optional<TableDimensions> spreadsheet_limit{TableDimensions(10000, 500)};
   bool spreadsheet_limit_by_content{true};
diff --git a/src/odr/internal/html/document.cpp b/src/odr/internal/html/document.cpp
index 06d0d5d71..837068a8b 100644
--- a/src/odr/internal/html/document.cpp
+++ b/src/odr/internal/html/document.cpp
@@ -58,6 +58,7 @@ void front(const Document &document, const WritingState &state,
   if (document.document_type() == DocumentType::spreadsheet) {
     write_spreadsheet_style(state);
   }
+  write_color_scheme_style(state);
 
   out.write_header_end();
 
@@ -317,7 +318,8 @@ class TextHtmlFragment final : public HtmlFragmentBase {
       out.write_element_end("div");
       out.write_element_end("div");
     } else {
-      out.write_element_begin("div");
+      out.write_element_begin("div",
+                              HtmlElementOptions().set_class("odr-text-flow"));
       translate_children(element.children(), state);
       out.write_element_end("div");
     }
diff --git a/src/odr/internal/html/frontend.cpp b/src/odr/internal/html/frontend.cpp
index 0f3063b02..bbe387b3d 100644
--- a/src/odr/internal/html/frontend.cpp
+++ b/src/odr/internal/html/frontend.cpp
@@ -35,6 +35,11 @@ x-s{display:inline}
    Not a negative `z-index`, which is one too but takes the page out of reach of
    hit testing. */
 .odr-page-outer{display:flex;margin:0 16px;background:#fff;box-shadow:0 1px 4px rgba(0,0,0,.5);isolation:isolate}
+/* Reflowed to the viewport there is no page box to inset the text, and the body
+   has no margin of its own, so it would begin at the screen edge. A page's own
+   margin is a physical measure, and so is this one, rather than a `ch` of
+   whatever font the browser happens to default to. */
+.odr-text-flow{padding:3mm}
 /* The label is text rather than a `::marker`, which no selection would copy.
    It hangs into the item's padding so wrapped lines align under the text. */
 .odr-list-item{padding-left:2em}
@@ -179,6 +184,41 @@ body{margin:0;background:#000}
 .odr-media audio{width:100%;max-width:40rem;margin:0 1rem}
 )css";
 
+/// The dark palette. Written after every stylesheet it restates, and — for
+/// @ref odr::HtmlColorScheme::system — carried by an element whose `media`
+/// attribute gates it, so no rule in here needs a query of its own.
+constexpr std::string_view dark_css = R"css(
+:root{
+color-scheme:dark;
+--odr-sheet-line:#30363d;
+--odr-sheet-rule:#484f58;
+--odr-sheet-ruler:#161b22;
+--odr-sheet-ruler-text:#8b949e;
+--odr-sheet-canvas:#0d1117;
+--odr-sheet-wash:rgba(255,255,255,.05);
+--odr-sheet-wash-pinned:rgba(255,255,255,.10);
+--odr-sheet-wash-ruler:rgba(255,255,255,.12);
+--odr-sheet-focus:#4c8dff;
+}
+body{background:#0d1117;color:#e6edf3}
+/* The backdrop stays darker than the page, as it is lighter than it in light:
+   what makes a page read as a sheet is the step between them. */
+.odr-background{background:#010409}
+.odr-page-outer{background-color:#161b22!important;box-shadow:0 1px 4px rgba(0,0,0,.8)}
+.odr-sheet{background-color:#161b22!important}
+/* The colors the file authored are inline, and no media query reaches an inline
+   style — so they are overridden here rather than dropped as the file is read.
+   Every fill gives way to the page and every run of text to one legible against
+   it, which costs a slide its own fills and is what keeps its text readable.
+   `background-image` is left alone: a page printed on a picture keeps it. */
+div,table,tr,td,x-p,x-s{background-color:transparent!important}
+td,x-p,x-s{color:#e6edf3!important}
+a,a x-p,a x-s{color:#6cb6ff!important}
+/* Ours rather than the file's, and the only light thing left: the search mark
+   keeps its yellow and takes dark text against it. */
+mark{color:#0d1117!important}
+)css";
+
 /// What the search script paints.
 constexpr std::string_view search_css = R"css(
 mark{background:#ff0}
@@ -1110,6 +1150,8 @@ constexpr Asset filesystem_css_asset{HtmlResourceType::css, "text/css",
                                      "filesystem.css", filesystem_css};
 constexpr Asset media_css_asset{HtmlResourceType::css, "text/css", "media.css",
                                 media_css};
+constexpr Asset dark_css_asset{HtmlResourceType::css, "text/css", "dark.css",
+                               dark_css};
 constexpr Asset search_css_asset{HtmlResourceType::css, "text/css",
                                  "search.css", search_css};
 constexpr Asset document_js_asset{HtmlResourceType::js, "text/javascript",
@@ -1142,15 +1184,17 @@ HtmlResources locate_all(const std::span<const Asset> assets,
   return resources;
 }
 
-void write_style(const Asset &asset, const WritingState &state) {
+/// @p media, when given, gates the stylesheet on that media query.
+void write_style(const Asset &asset, const WritingState &state,
+                 const std::string_view media = {}) {
   if (const HtmlResourceLocation location =
           locate(asset, state.config(), state.resources());
       location.has_value()) {
-    state.out().write_header_style(escape_attribute(*location));
+    state.out().write_header_style(escape_attribute(*location), media);
     return;
   }
 
-  state.out().write_header_style_begin();
+  state.out().write_header_style_begin(media);
   state.out().out() << asset.content;
   state.out().write_header_style_end();
 }
@@ -1182,6 +1226,20 @@ void html::write_spreadsheet_style(const WritingState &state) {
   write_style(spreadsheet_css_asset, state);
 }
 
+void html::write_color_scheme_style(const WritingState &state) {
+  switch (state.config().color_scheme) {
+  case HtmlColorScheme::dark:
+    write_style(dark_css_asset, state);
+    break;
+  case HtmlColorScheme::system:
+    write_style(dark_css_asset, state, "(prefers-color-scheme: dark)");
+    break;
+  case HtmlColorScheme::light:
+  default:
+    break;
+  }
+}
+
 void html::write_text_style(const WritingState &state) {
   write_style(text_css_asset, state);
 }
diff --git a/src/odr/internal/html/frontend.hpp b/src/odr/internal/html/frontend.hpp
index 5d2c8ba99..7896b3380 100644
--- a/src/odr/internal/html/frontend.hpp
+++ b/src/odr/internal/html/frontend.hpp
@@ -12,6 +12,10 @@ struct WritingState;
 void write_document_style(const WritingState &state);
 /// Written in addition to the document style.
 void write_spreadsheet_style(const WritingState &state);
+/// Written last of a document's styles, and only where the config asks for a
+/// scheme other than @ref odr::HtmlColorScheme::light: it restates what those
+/// before it painted white.
+void write_color_scheme_style(const WritingState &state);
 void write_text_style(const WritingState &state);
 void write_xml_style(const WritingState &state);
 void write_filesystem_style(const WritingState &state);
diff --git a/src/odr/internal/html/html_writer.cpp b/src/odr/internal/html/html_writer.cpp
index bcb68fb24..0ef852a0b 100644
--- a/src/odr/internal/html/html_writer.cpp
+++ b/src/odr/internal/html/html_writer.cpp
@@ -192,19 +192,28 @@ void HtmlWriter::write_header_charset(const std::string &charset) {
   out() << "\"/>";
 }
 
-void HtmlWriter::write_header_style(const std::string &href) {
+void HtmlWriter::write_header_style(const std::string &href,
+                                    const std::string_view media) {
   write_new_line();
 
   out() << R"(<link rel="stylesheet" href=")";
   out() << href;
-  out() << "\"/>";
+  out() << "\"";
+  if (!media.empty()) {
+    out() << R"( media=")" << media << "\"";
+  }
+  out() << "/>";
 }
 
-void HtmlWriter::write_header_style_begin() {
+void HtmlWriter::write_header_style_begin(const std::string_view media) {
   write_new_line();
   ++m_current_indent;
 
-  out() << "<style>";
+  out() << "<style";
+  if (!media.empty()) {
+    out() << R"( media=")" << media << "\"";
+  }
+  out() << ">";
 }
 
 void HtmlWriter::write_header_style_end() {
diff --git a/src/odr/internal/html/html_writer.hpp b/src/odr/internal/html/html_writer.hpp
index b26713d02..88068c0fc 100644
--- a/src/odr/internal/html/html_writer.hpp
+++ b/src/odr/internal/html/html_writer.hpp
@@ -5,6 +5,7 @@
 #include <functional>
 #include <iosfwd>
 #include <string>
+#include <string_view>
 #include <variant>
 #include <vector>
 
@@ -61,8 +62,9 @@ class HtmlWriter {
   void write_header_viewport(const std::string &viewport);
   void write_header_target(const std::string &target);
   void write_header_charset(const std::string &charset);
-  void write_header_style(const std::string &href);
-  void write_header_style_begin();
+  /// @p media, when given, gates the stylesheet on that media query.
+  void write_header_style(const std::string &href, std::string_view media = {});
+  void write_header_style_begin(std::string_view media = {});
   void write_header_style_end();
 
   void write_script(const std::string &src);
diff --git a/test/src/html_test.cpp b/test/src/html_test.cpp
index 89331af1a..5ab82099f 100644
--- a/test/src/html_test.cpp
+++ b/test/src/html_test.cpp
@@ -1,3 +1,4 @@
+#include <algorithm>
 #include <filesystem>
 #include <fstream>
 #include <sstream>
@@ -140,6 +141,75 @@ TEST(html, archive_listing) {
       "10000000000001F4000001FF1D2394A8.jpg"));
 }
 
+namespace {
+
+std::string render_odt(const HtmlConfig &config) {
+  const DecodedFile file(TestData::test_file_path("odr-public/odt/about.odt"),
+                         Logger::null());
+
+  std::ostringstream out;
+  html::translate(file, config).list_views().at(0).write_html(out);
+  return out.str();
+}
+
+} // namespace
+
+// Reflowed to the viewport a text document has no page box to inset it, and the
+// body carries no margin of its own.
+TEST(html, flowing_text_is_inset_from_the_screen_edge) {
+  HtmlConfig config;
+  config.text_document_margin = false;
+
+  const std::string page = render_odt(config);
+
+  EXPECT_NE(page.find(R"(<div class="odr-text-flow">)"), std::string::npos);
+  EXPECT_NE(page.find(".odr-text-flow{padding:"), std::string::npos);
+}
+
+// The colors a document sets are inline, out of reach of a media query, so the
+// dark scheme is a stylesheet that overrides them — and for `system` it is the
+// element carrying that stylesheet which is gated, not a rule inside it.
+TEST(html, color_scheme_writes_the_dark_style) {
+  HtmlConfig config;
+
+  EXPECT_EQ(config.color_scheme, HtmlColorScheme::light);
+  EXPECT_EQ(render_odt(config).find("color-scheme:dark"), std::string::npos);
+
+  config.color_scheme = HtmlColorScheme::dark;
+  const std::string dark = render_odt(config);
+  EXPECT_NE(dark.find("color-scheme:dark"), std::string::npos);
+  EXPECT_EQ(dark.find("prefers-color-scheme"), std::string::npos);
+
+  config.color_scheme = HtmlColorScheme::system;
+  const std::string system = render_odt(config);
+  EXPECT_NE(
+      system.find(R"html(<style media="(prefers-color-scheme: dark)">)html"),
+      std::string::npos);
+}
+
+// A linked stylesheet keeps its media query, and the service answers for it.
+TEST(html, linked_dark_style_is_served) {
+  HtmlConfig config;
+  config.embed_shipped_resources = false;
+  config.color_scheme = HtmlColorScheme::system;
+
+  const DecodedFile file(TestData::test_file_path("odr-public/odt/about.odt"),
+                         Logger::null());
+  const HtmlService service = html::translate(file, config);
+
+  std::ostringstream out;
+  const HtmlResources resources = service.list_views().at(0).write_html(out);
+
+  EXPECT_NE(
+      out.str().find(
+          R"html(<link rel="stylesheet" href="dark.css" media="(prefers-color-scheme: dark)"/>)html"),
+      std::string::npos);
+  EXPECT_TRUE(std::ranges::any_of(resources, [](const auto &entry) {
+    return entry.second.has_value() && *entry.second == "dark.css";
+  }));
+  EXPECT_TRUE(service.exists("dark.css"));
+}
+
 TEST(html, views) {
   const auto logger = Logger::create_stdio("odr-test", LogLevel::verbose);
 
diff --git a/wasm/js/index.d.ts b/wasm/js/index.d.ts
index 261f1889e..783a71f35 100644
--- a/wasm/js/index.d.ts
+++ b/wasm/js/index.d.ts
@@ -7,6 +7,7 @@ export interface EnumTables {
   FileCategory: Record<string, number>;
   DocumentType: Record<string, number>;
   HtmlResourceType: Record<string, number>;
+  HtmlColorScheme: Record<string, number>;
   HtmlTableGridlines: Record<string, number>;
   HtmlViewportMode: Record<string, number>;
   PdfTextMode: Record<string, number>;
@@ -77,6 +78,7 @@ export interface HtmlConfig {
   backgroundImageDpi?: number;
   pageRangeBegin?: number;
   pageRangeEnd?: number;
+  colorScheme?: number;
   spreadsheetGridlines?: number;
   viewportMode?: number;
   pdfTextMode?: number;
diff --git a/wasm/src/wasm_core.cpp b/wasm/src/wasm_core.cpp
index 5b1861587..ff0ff5eb8 100644
--- a/wasm/src/wasm_core.cpp
+++ b/wasm/src/wasm_core.cpp
@@ -103,6 +103,10 @@ emscripten::val enum_tables() {
              table(entry("none", HtmlTableGridlines::none),
                    entry("soft", HtmlTableGridlines::soft),
                    entry("hard", HtmlTableGridlines::hard)));
+  result.set("HtmlColorScheme",
+             table(entry("light", HtmlColorScheme::light),
+                   entry("dark", HtmlColorScheme::dark),
+                   entry("system", HtmlColorScheme::system)));
   result.set("HtmlViewportMode",
              table(entry("automatic", HtmlViewportMode::automatic),
                    entry("fit_width", HtmlViewportMode::fit_width),
diff --git a/wasm/src/wasm_html.cpp b/wasm/src/wasm_html.cpp
index 2914338db..416553483 100644
--- a/wasm/src/wasm_html.cpp
+++ b/wasm/src/wasm_html.cpp
@@ -138,6 +138,7 @@ HtmlConfig to_html_config(const emscripten::val &value) {
     config.page_range_end = end.as<std::uint32_t>();
   }
 
+  read_enum(value, "colorScheme", config.color_scheme);
   read_enum(value, "spreadsheetGridlines", config.spreadsheet_gridlines);
   read_enum(value, "viewportMode", config.viewport_mode);
   read_enum(value, "pdfTextMode", config.pdf_text_mode);
diff --git a/wasm/tests/enums.test.mjs b/wasm/tests/enums.test.mjs
index 42c3a7bd4..2966c75bb 100644
--- a/wasm/tests/enums.test.mjs
+++ b/wasm/tests/enums.test.mjs
@@ -18,6 +18,7 @@ const pinned = {
     font: 4,
     media: 5,
   },
+  HtmlColorScheme: { light: 0, dark: 1, system: 2 },
   HtmlTableGridlines: { none: 0, soft: 1, hard: 2 },
   HtmlViewportMode: {
     automatic: 0,

From 573f5f2a89a646c67ed3a264ecc1f8ed2cc64c1d Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Tue, 18 Aug 2026 08:34:44 +0200
Subject: [PATCH 2/4] feat(html): read a text file, a listing, an image in the
 dark too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Only the document views had a dark palette. Every view but the pdf one has one
now — a text file and its gutter, a source view and its six syntax cuts, a file
listing and its washes, an image, a font specimen — each written straight after
the sheet it restates and gated the same way. The media view is black in any
scheme and keeps no dark sheet of its own. The pdf view is left out: it paints
its page backgrounds itself, and turning those over is a different job.

The one dark stylesheet is split along the same lines its light counterparts
already follow, `document-dark.css` beside `document.css` and so on, so a page
carries the dark palette of the views it is, not of all of them. A view writing
its style inline rather than as a shipped asset asks `writes_dark_style` and
`dark_style_media` for the same gating.

A shape's fill is not a background: `translate_drawing_style` writes it as the
svg `fill` that the rect or circle inside inherits, so clearing
`background-color` left a light-filled text box light while the ink above it
turned white — the title of an odg read as white on white. The fill gives way
like a background does. The stroke is left as the file set it: it is the shape's
line, not its ground.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rD1SK4k5Y6GQSzbCeKExY
---
 CHANGELOG.md                         |  16 +-
 src/odr/html.hpp                     |   8 +-
 src/odr/internal/html/document.cpp   |   4 +-
 src/odr/internal/html/filesystem.cpp |   2 +
 src/odr/internal/html/font_file.cpp  |  10 ++
 src/odr/internal/html/frontend.cpp   | 218 ++++++++++++++++++++-------
 src/odr/internal/html/frontend.hpp   |  24 ++-
 src/odr/internal/html/image_file.cpp |   6 +
 src/odr/internal/html/text_file.cpp  |   2 +
 src/odr/internal/html/xml_file.cpp   |   2 +
 test/src/html_test.cpp               |  46 +++++-
 11 files changed, 265 insertions(+), 73 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index be2632e3a..795a778a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,13 +16,15 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
-- A document can be read in the dark: `HtmlConfig::color_scheme` is `light` (a
-  white page, what it has always been), `dark`, or `system`, which follows the
-  reader's `prefers-color-scheme`. It reaches every document type, and the
-  colors the file itself authored give way to it — a fill to the page, a run of
-  text to one legible against it — because no media query reaches an inline
-  style. Mirrored in the python, wasm, jni and apple bindings as
-  `HtmlColorScheme`.
+- A file can be read in the dark: `HtmlConfig::color_scheme` is `light` (a white
+  page, what it has always been), `dark`, or `system`, which follows the
+  reader's `prefers-color-scheme`. Every view honors it but the pdf one, which
+  paints its page backgrounds itself — a text document flowing or paged, a
+  sheet, a slide, a drawing, a text file, a source view, a file listing, an
+  image, a font specimen. The colors the file itself authored give way to it — a
+  fill to the page, a run of text to one legible against it — because no media
+  query reaches an inline style. Mirrored in the python, wasm, jni and apple
+  bindings as `HtmlColorScheme`.
 - A text document reflowed to the viewport — page margins off — is inset from
   the edge of the screen by 3mm instead of starting at the first pixel of it.
 - Prose is no longer read as a csv. A separator that every field follows with a
diff --git a/src/odr/html.hpp b/src/odr/html.hpp
index f1ee2e4b4..367206f11 100644
--- a/src/odr/html.hpp
+++ b/src/odr/html.hpp
@@ -73,9 +73,9 @@ enum class HtmlTableGridlines {
   hard,
 };
 
-/// @brief The colors the emitted HTML renders a document against. Only the
-/// document views honor it; a pdf, a source view or a file listing brings its
-/// own.
+/// @brief The colors the emitted HTML renders against. Every view honors it but
+/// the pdf one, which paints its page backgrounds itself; a media view is black
+/// in any scheme.
 enum class HtmlColorScheme {
   light, ///< a white page, carrying the colors the document gives its content
   dark,  ///< a dark page, which the document's own text and fill colors give
@@ -135,7 +135,7 @@ struct HtmlConfig {
   // text document margin
   bool text_document_margin{false};
 
-  // colors the document renders against
+  // colors the output renders against
   HtmlColorScheme color_scheme{HtmlColorScheme::light};
 
   // spreadsheet table limit
diff --git a/src/odr/internal/html/document.cpp b/src/odr/internal/html/document.cpp
index 837068a8b..a73530af0 100644
--- a/src/odr/internal/html/document.cpp
+++ b/src/odr/internal/html/document.cpp
@@ -54,11 +54,13 @@ void front(const Document &document, const WritingState &state,
                           : std::nullopt);
 
   write_document_style(state);
+  write_document_dark_style(state);
   write_search_style(state);
+  write_search_dark_style(state);
   if (document.document_type() == DocumentType::spreadsheet) {
     write_spreadsheet_style(state);
+    write_spreadsheet_dark_style(state);
   }
-  write_color_scheme_style(state);
 
   out.write_header_end();
 
diff --git a/src/odr/internal/html/filesystem.cpp b/src/odr/internal/html/filesystem.cpp
index 5cfe12370..ad8b14c85 100644
--- a/src/odr/internal/html/filesystem.cpp
+++ b/src/odr/internal/html/filesystem.cpp
@@ -189,7 +189,9 @@ class HtmlServiceImpl final : public HtmlService {
     out.write_header_title("odr");
     write_viewport_meta(out, config(), false);
     write_filesystem_style(state);
+    write_filesystem_dark_style(state);
     write_search_style(state);
+    write_search_dark_style(state);
     out.write_header_end();
 
     out.write_body_begin();
diff --git a/src/odr/internal/html/font_file.cpp b/src/odr/internal/html/font_file.cpp
index ffb6baa3f..b1555e455 100644
--- a/src/odr/internal/html/font_file.cpp
+++ b/src/odr/internal/html/font_file.cpp
@@ -9,6 +9,7 @@
 #include <odr/internal/font/sfnt_font.hpp>
 #include <odr/internal/font/sfnt_transform.hpp>
 #include <odr/internal/html/common.hpp>
+#include <odr/internal/html/frontend.hpp>
 #include <odr/internal/html/html_service.hpp>
 #include <odr/internal/html/html_writer.hpp>
 #include <odr/internal/util/stream_util.hpp>
@@ -122,6 +123,15 @@ class HtmlServiceImpl final : public HtmlService {
     out.out() << ".gid{font-size:.6em;color:#888;}";
     out.out() << "</style>";
 
+    if (writes_dark_style(config())) {
+      out.write_header_style_begin(dark_style_media(config()));
+      out.out() << ":root{color-scheme:dark}";
+      out.out() << "body{background:#0d1117;color:#e6edf3;}";
+      out.out() << ".cell{border-color:#30363d;}";
+      out.out() << ".gid{color:#8b949e;}";
+      out.write_header_style_end();
+    }
+
     out.out() << "<h1>" << escape_text(font->name()) << "</h1>";
     out.out() << "<p>glyphs: " << font->glyph_count()
               << " &middot; units/em: " << font->units_per_em()
diff --git a/src/odr/internal/html/frontend.cpp b/src/odr/internal/html/frontend.cpp
index bbe387b3d..20a3c9021 100644
--- a/src/odr/internal/html/frontend.cpp
+++ b/src/odr/internal/html/frontend.cpp
@@ -46,6 +46,34 @@ x-s{display:inline}
 .odr-list-marker{display:inline-block;min-width:2em;margin-left:-2em;white-space:pre}
 )css";
 
+/// The dark counterpart of the style above. Every view but the pdf one has one,
+/// written straight after the sheet it restates, and — for @ref
+/// odr::HtmlColorScheme::system — carried by an element whose `media` attribute
+/// gates it. That is what lets a rule in here be plain: none of them could sit
+/// inside a query and still reach a color the document sets inline.
+constexpr std::string_view document_dark_css = R"css(
+:root{color-scheme:dark}
+body{background:#0d1117;color:#e6edf3}
+/* The backdrop stays darker than the page, as it is lighter than it in light:
+   what makes a page read as a sheet is the step between them. */
+.odr-background{background:#010409}
+.odr-page-outer{background-color:#161b22!important;box-shadow:0 1px 4px rgba(0,0,0,.8)}
+/* The colors the file authored are inline, and no media query reaches an inline
+   style — so they are overridden here rather than dropped as the file is read.
+   Every fill gives way to the page and every run of text to one legible against
+   it, which costs a slide its own fills and is what keeps its text readable.
+   `background-image` is left alone: a page printed on a picture keeps it. */
+div,table,tr,td,x-p,x-s{background-color:transparent!important}
+/* A shape's fill is not a background: `translate_drawing_style` writes it as the
+   svg `fill` that the rect or circle we draw inside it inherits. It gives way
+   like one, or a light box would keep its fill and lose its text to the ink
+   above. The stroke is left as the file set it: it is the shape's line, not its
+   ground. */
+svg,svg *{fill:transparent!important}
+td,x-p,x-s{color:#e6edf3!important}
+a,a x-p,a x-s{color:#6cb6ff!important}
+)css";
+
 /// No `text-overflow`: it sat on `td`, whose overflow is visible, and making it
 /// work would mean clipping.
 constexpr std::string_view spreadsheet_css = R"css(
@@ -93,6 +121,22 @@ body{margin:0;background:var(--odr-sheet-canvas)}
 .odr-sheet-sort-asc::after{content:"\25B4"}
 )css";
 
+/// The sheet is a surface like a page, and reads against a canvas the same way.
+constexpr std::string_view spreadsheet_dark_css = R"css(
+:root{
+--odr-sheet-line:#30363d;
+--odr-sheet-rule:#484f58;
+--odr-sheet-ruler:#161b22;
+--odr-sheet-ruler-text:#8b949e;
+--odr-sheet-canvas:#0d1117;
+--odr-sheet-wash:rgba(255,255,255,.05);
+--odr-sheet-wash-pinned:rgba(255,255,255,.10);
+--odr-sheet-wash-ruler:rgba(255,255,255,.12);
+--odr-sheet-focus:#4c8dff;
+}
+.odr-sheet{background-color:#161b22!important}
+)css";
+
 /// A whole-pixel line height, because the line numbers are a second column
 /// whose cells are sized to the lines by script - a fractional line would round
 /// per cell and the two columns would drift apart.
@@ -120,6 +164,20 @@ body{margin:0;background:#fff}
 [contenteditable]:focus{outline:none}
 )css";
 
+/// The gutter is a surface beside the page, so it steps the other way in dark:
+/// lighter than the text it numbers, where in light it is darker.
+constexpr std::string_view text_dark_css = R"css(
+:root{
+color-scheme:dark;
+--odr-text-fg:#e6edf3;
+--odr-text-muted:#8b949e;
+--odr-text-line:#30363d;
+--odr-text-gutter:#161b22;
+--odr-text-wash:rgba(255,255,255,.05);
+}
+body{background:#0d1117}
+)css";
+
 /// No numbered gutter - the numbers would be ours, not the file's. The column
 /// carries the fold handles, and every line reserves it.
 constexpr std::string_view xml_css = R"css(
@@ -155,6 +213,23 @@ body{margin:0;background:#fff}
 .odr-xml-decl,.odr-xml-doctype,.odr-xml-pi{color:var(--odr-xml-meta)}
 )css";
 
+/// The same six parts of a document, in the cuts of them that carry on a dark
+/// ground.
+constexpr std::string_view xml_dark_css = R"css(
+:root{
+color-scheme:dark;
+--odr-xml-text:#e6edf3;
+--odr-xml-muted:#8b949e;
+--odr-xml-punct:#9198a1;
+--odr-xml-name:#7ee787;
+--odr-xml-attr:#ffa657;
+--odr-xml-value:#a5d6ff;
+--odr-xml-meta:#d2a8ff;
+}
+body{background:#0d1117}
+.odr-xml summary:hover{background:rgba(255,255,255,.06)}
+)css";
+
 constexpr std::string_view filesystem_css = R"css(
 :root{
 --odr-files-line:#e3e5e8;
@@ -177,6 +252,20 @@ body{margin:0;background:#fff;color:#1f2328;font:13px/1.5 var(--odr-files-font)}
 .odr-files-action a:hover{background:rgba(0,0,0,.07);color:var(--odr-files-link)}
 )css";
 
+/// The washes are lightened rather than darkened: on a dark row a black one
+/// paints nothing.
+constexpr std::string_view filesystem_dark_css = R"css(
+:root{
+color-scheme:dark;
+--odr-files-line:#30363d;
+--odr-files-muted:#8b949e;
+--odr-files-link:#6cb6ff;
+}
+body{background:#0d1117;color:#e6edf3}
+.odr-files tbody tr:hover>*{background-image:linear-gradient(rgba(255,255,255,.05),rgba(255,255,255,.05))}
+.odr-files-action a:hover{background:rgba(255,255,255,.08)}
+)css";
+
 constexpr std::string_view media_css = R"css(
 body{margin:0;background:#000}
 .odr-media{display:flex;align-items:center;justify-content:center;min-height:100vh}
@@ -184,47 +273,18 @@ body{margin:0;background:#000}
 .odr-media audio{width:100%;max-width:40rem;margin:0 1rem}
 )css";
 
-/// The dark palette. Written after every stylesheet it restates, and — for
-/// @ref odr::HtmlColorScheme::system — carried by an element whose `media`
-/// attribute gates it, so no rule in here needs a query of its own.
-constexpr std::string_view dark_css = R"css(
-:root{
-color-scheme:dark;
---odr-sheet-line:#30363d;
---odr-sheet-rule:#484f58;
---odr-sheet-ruler:#161b22;
---odr-sheet-ruler-text:#8b949e;
---odr-sheet-canvas:#0d1117;
---odr-sheet-wash:rgba(255,255,255,.05);
---odr-sheet-wash-pinned:rgba(255,255,255,.10);
---odr-sheet-wash-ruler:rgba(255,255,255,.12);
---odr-sheet-focus:#4c8dff;
-}
-body{background:#0d1117;color:#e6edf3}
-/* The backdrop stays darker than the page, as it is lighter than it in light:
-   what makes a page read as a sheet is the step between them. */
-.odr-background{background:#010409}
-.odr-page-outer{background-color:#161b22!important;box-shadow:0 1px 4px rgba(0,0,0,.8)}
-.odr-sheet{background-color:#161b22!important}
-/* The colors the file authored are inline, and no media query reaches an inline
-   style — so they are overridden here rather than dropped as the file is read.
-   Every fill gives way to the page and every run of text to one legible against
-   it, which costs a slide its own fills and is what keeps its text readable.
-   `background-image` is left alone: a page printed on a picture keeps it. */
-div,table,tr,td,x-p,x-s{background-color:transparent!important}
-td,x-p,x-s{color:#e6edf3!important}
-a,a x-p,a x-s{color:#6cb6ff!important}
-/* Ours rather than the file's, and the only light thing left: the search mark
-   keeps its yellow and takes dark text against it. */
-mark{color:#0d1117!important}
-)css";
-
 /// What the search script paints.
 constexpr std::string_view search_css = R"css(
 mark{background:#ff0}
 mark.current{background:orange}
 )css";
 
+/// The mark is ours rather than the file's and keeps its yellow, the one light
+/// thing left on the page; only the text on it turns over.
+constexpr std::string_view search_dark_css = R"css(
+mark{color:#0d1117!important}
+)css";
+
 constexpr std::string_view document_js = R"js(
 (function () {
   "use strict";
@@ -1140,20 +1200,32 @@ struct Asset {
 
 constexpr Asset document_css_asset{HtmlResourceType::css, "text/css",
                                    "document.css", document_css};
+constexpr Asset document_dark_css_asset{HtmlResourceType::css, "text/css",
+                                        "document-dark.css", document_dark_css};
 constexpr Asset spreadsheet_css_asset{HtmlResourceType::css, "text/css",
                                       "spreadsheet.css", spreadsheet_css};
+constexpr Asset spreadsheet_dark_css_asset{HtmlResourceType::css, "text/css",
+                                           "spreadsheet-dark.css",
+                                           spreadsheet_dark_css};
 constexpr Asset text_css_asset{HtmlResourceType::css, "text/css", "text.css",
                                text_css};
+constexpr Asset text_dark_css_asset{HtmlResourceType::css, "text/css",
+                                    "text-dark.css", text_dark_css};
 constexpr Asset xml_css_asset{HtmlResourceType::css, "text/css", "xml.css",
                               xml_css};
+constexpr Asset xml_dark_css_asset{HtmlResourceType::css, "text/css",
+                                   "xml-dark.css", xml_dark_css};
 constexpr Asset filesystem_css_asset{HtmlResourceType::css, "text/css",
                                      "filesystem.css", filesystem_css};
+constexpr Asset filesystem_dark_css_asset{HtmlResourceType::css, "text/css",
+                                          "filesystem-dark.css",
+                                          filesystem_dark_css};
 constexpr Asset media_css_asset{HtmlResourceType::css, "text/css", "media.css",
                                 media_css};
-constexpr Asset dark_css_asset{HtmlResourceType::css, "text/css", "dark.css",
-                               dark_css};
 constexpr Asset search_css_asset{HtmlResourceType::css, "text/css",
                                  "search.css", search_css};
+constexpr Asset search_dark_css_asset{HtmlResourceType::css, "text/css",
+                                      "search-dark.css", search_dark_css};
 constexpr Asset document_js_asset{HtmlResourceType::js, "text/javascript",
                                   "document.js", document_js};
 constexpr Asset search_js_asset{HtmlResourceType::js, "text/javascript",
@@ -1184,6 +1256,20 @@ HtmlResources locate_all(const std::span<const Asset> assets,
   return resources;
 }
 
+/// Adds the dark sheets where the config asks for them: a view has to answer
+/// for what its markup links, and it links those only then.
+HtmlResources locate_all(const std::span<const Asset> assets,
+                         const std::span<const Asset> dark,
+                         const HtmlConfig &config) {
+  HtmlResources resources = locate_all(assets, config);
+  if (writes_dark_style(config)) {
+    for (const Asset &asset : dark) {
+      locate(asset, config, resources);
+    }
+  }
+  return resources;
+}
+
 /// @p media, when given, gates the stylesheet on that media query.
 void write_style(const Asset &asset, const WritingState &state,
                  const std::string_view media = {}) {
@@ -1199,6 +1285,14 @@ void write_style(const Asset &asset, const WritingState &state,
   state.out().write_header_style_end();
 }
 
+/// Writes @p asset where the config asks for a dark scheme, gated on the
+/// reader's preference where it asks to follow it.
+void write_dark_style(const Asset &asset, const WritingState &state) {
+  if (writes_dark_style(state.config())) {
+    write_style(asset, state, dark_style_media(state.config()));
+  }
+}
+
 void write_script(const Asset &asset, const WritingState &state) {
   if (const HtmlResourceLocation location =
           locate(asset, state.config(), state.resources());
@@ -1218,6 +1312,16 @@ void write_script(const Asset &asset, const WritingState &state) {
 
 namespace odr::internal {
 
+bool html::writes_dark_style(const HtmlConfig &config) {
+  return config.color_scheme != HtmlColorScheme::light;
+}
+
+std::string_view html::dark_style_media(const HtmlConfig &config) {
+  return config.color_scheme == HtmlColorScheme::system
+             ? "(prefers-color-scheme: dark)"
+             : "";
+}
+
 void html::write_document_style(const WritingState &state) {
   write_style(document_css_asset, state);
 }
@@ -1226,32 +1330,38 @@ void html::write_spreadsheet_style(const WritingState &state) {
   write_style(spreadsheet_css_asset, state);
 }
 
-void html::write_color_scheme_style(const WritingState &state) {
-  switch (state.config().color_scheme) {
-  case HtmlColorScheme::dark:
-    write_style(dark_css_asset, state);
-    break;
-  case HtmlColorScheme::system:
-    write_style(dark_css_asset, state, "(prefers-color-scheme: dark)");
-    break;
-  case HtmlColorScheme::light:
-  default:
-    break;
-  }
+void html::write_document_dark_style(const WritingState &state) {
+  write_dark_style(document_dark_css_asset, state);
+}
+
+void html::write_spreadsheet_dark_style(const WritingState &state) {
+  write_dark_style(spreadsheet_dark_css_asset, state);
 }
 
 void html::write_text_style(const WritingState &state) {
   write_style(text_css_asset, state);
 }
 
+void html::write_text_dark_style(const WritingState &state) {
+  write_dark_style(text_dark_css_asset, state);
+}
+
 void html::write_xml_style(const WritingState &state) {
   write_style(xml_css_asset, state);
 }
 
+void html::write_xml_dark_style(const WritingState &state) {
+  write_dark_style(xml_dark_css_asset, state);
+}
+
 void html::write_filesystem_style(const WritingState &state) {
   write_style(filesystem_css_asset, state);
 }
 
+void html::write_filesystem_dark_style(const WritingState &state) {
+  write_dark_style(filesystem_dark_css_asset, state);
+}
+
 void html::write_media_style(const WritingState &state) {
   write_style(media_css_asset, state);
 }
@@ -1260,6 +1370,10 @@ void html::write_search_style(const WritingState &state) {
   write_style(search_css_asset, state);
 }
 
+void html::write_search_dark_style(const WritingState &state) {
+  write_dark_style(search_dark_css_asset, state);
+}
+
 void html::write_document_script(const WritingState &state) {
   write_script(document_js_asset, state);
 }
@@ -1279,13 +1393,15 @@ void html::write_text_script(const WritingState &state) {
 HtmlResources html::locate_text_resources(const HtmlConfig &config) {
   static constexpr std::array assets{text_css_asset, search_css_asset,
                                      search_js_asset, text_js_asset};
-  return locate_all(assets, config);
+  static constexpr std::array dark{text_dark_css_asset, search_dark_css_asset};
+  return locate_all(assets, dark, config);
 }
 
 HtmlResources html::locate_xml_resources(const HtmlConfig &config) {
   static constexpr std::array assets{xml_css_asset, search_css_asset,
                                      search_js_asset};
-  return locate_all(assets, config);
+  static constexpr std::array dark{xml_dark_css_asset, search_dark_css_asset};
+  return locate_all(assets, dark, config);
 }
 
 HtmlResources html::locate_search_resources(const HtmlConfig &config) {
diff --git a/src/odr/internal/html/frontend.hpp b/src/odr/internal/html/frontend.hpp
index 7896b3380..8d63af7e3 100644
--- a/src/odr/internal/html/frontend.hpp
+++ b/src/odr/internal/html/frontend.hpp
@@ -2,6 +2,8 @@
 
 #include <odr/html.hpp>
 
+#include <string_view>
+
 namespace odr::internal::html {
 
 struct WritingState;
@@ -9,19 +11,33 @@ struct WritingState;
 /// Each of these writes one complete `<style>`/`<script>` element, or links it
 /// as a shipped @ref odr::HtmlResource when the config asks for that.
 
+/// Each `write_*_dark_style` follows the style it restates and writes nothing
+/// unless the config asks for a scheme other than
+/// @ref odr::HtmlColorScheme::light. The pdf view has none: it paints its page
+/// backgrounds itself.
+
 void write_document_style(const WritingState &state);
+void write_document_dark_style(const WritingState &state);
 /// Written in addition to the document style.
 void write_spreadsheet_style(const WritingState &state);
-/// Written last of a document's styles, and only where the config asks for a
-/// scheme other than @ref odr::HtmlColorScheme::light: it restates what those
-/// before it painted white.
-void write_color_scheme_style(const WritingState &state);
+void write_spreadsheet_dark_style(const WritingState &state);
 void write_text_style(const WritingState &state);
+void write_text_dark_style(const WritingState &state);
 void write_xml_style(const WritingState &state);
+void write_xml_dark_style(const WritingState &state);
 void write_filesystem_style(const WritingState &state);
+void write_filesystem_dark_style(const WritingState &state);
+/// The media view is black in every scheme, and has no dark style.
 void write_media_style(const WritingState &state);
 /// Written by every view that writes the search script.
 void write_search_style(const WritingState &state);
+void write_search_dark_style(const WritingState &state);
+
+/// For a view writing its style inline rather than as a shipped asset: whether
+/// to write a dark one at all, and the `media` gating it — empty where the
+/// config asks for dark outright.
+bool writes_dark_style(const HtmlConfig &config);
+std::string_view dark_style_media(const HtmlConfig &config);
 
 /// The `odr` object a document view exposes to its host: `generateDiff()`.
 void write_document_script(const WritingState &state);
diff --git a/src/odr/internal/html/image_file.cpp b/src/odr/internal/html/image_file.cpp
index 9a4cd355d..6b2ad7f7b 100644
--- a/src/odr/internal/html/image_file.cpp
+++ b/src/odr/internal/html/image_file.cpp
@@ -7,6 +7,7 @@
 
 #include <odr/internal/common/file.hpp>
 #include <odr/internal/html/common.hpp>
+#include <odr/internal/html/frontend.hpp>
 #include <odr/internal/html/html_service.hpp>
 #include <odr/internal/html/html_writer.hpp>
 #include <odr/internal/svm/svm_file.hpp>
@@ -107,6 +108,11 @@ class HtmlServiceImpl final : public HtmlService {
     out.write_header_style_begin();
     out.out() << "body{margin:0;background:#fff}";
     out.write_header_style_end();
+    if (writes_dark_style(config())) {
+      out.write_header_style_begin(dark_style_media(config()));
+      out.out() << ":root{color-scheme:dark}body{background:#0d1117}";
+      out.write_header_style_end();
+    }
     out.write_header_end();
 
     out.write_body_begin();
diff --git a/src/odr/internal/html/text_file.cpp b/src/odr/internal/html/text_file.cpp
index bf778d30e..4f1ceacb1 100644
--- a/src/odr/internal/html/text_file.cpp
+++ b/src/odr/internal/html/text_file.cpp
@@ -101,7 +101,9 @@ class HtmlServiceImpl final : public HtmlService {
     write_viewport_meta(out, config(), false);
 
     write_text_style(state);
+    write_text_dark_style(state);
     write_search_style(state);
+    write_search_dark_style(state);
 
     out.write_header_end();
 
diff --git a/src/odr/internal/html/xml_file.cpp b/src/odr/internal/html/xml_file.cpp
index 225099862..6cc6a9ebd 100644
--- a/src/odr/internal/html/xml_file.cpp
+++ b/src/odr/internal/html/xml_file.cpp
@@ -261,7 +261,9 @@ class HtmlServiceImpl final : public HtmlService {
     write_viewport_meta(out, config(), false);
 
     write_xml_style(state);
+    write_xml_dark_style(state);
     write_search_style(state);
+    write_search_dark_style(state);
 
     out.write_header_end();
 
diff --git a/test/src/html_test.cpp b/test/src/html_test.cpp
index 5ab82099f..9d05add0d 100644
--- a/test/src/html_test.cpp
+++ b/test/src/html_test.cpp
@@ -143,15 +143,18 @@ TEST(html, archive_listing) {
 
 namespace {
 
-std::string render_odt(const HtmlConfig &config) {
-  const DecodedFile file(TestData::test_file_path("odr-public/odt/about.odt"),
-                         Logger::null());
+std::string render(const std::string &path, const HtmlConfig &config) {
+  const DecodedFile file(TestData::test_file_path(path), Logger::null());
 
   std::ostringstream out;
   html::translate(file, config).list_views().at(0).write_html(out);
   return out.str();
 }
 
+std::string render_odt(const HtmlConfig &config) {
+  return render("odr-public/odt/about.odt", config);
+}
+
 } // namespace
 
 // Reflowed to the viewport a text document has no page box to inset it, and the
@@ -202,12 +205,43 @@ TEST(html, linked_dark_style_is_served) {
 
   EXPECT_NE(
       out.str().find(
-          R"html(<link rel="stylesheet" href="dark.css" media="(prefers-color-scheme: dark)"/>)html"),
+          R"html(<link rel="stylesheet" href="document-dark.css" media="(prefers-color-scheme: dark)"/>)html"),
       std::string::npos);
   EXPECT_TRUE(std::ranges::any_of(resources, [](const auto &entry) {
-    return entry.second.has_value() && *entry.second == "dark.css";
+    return entry.second.has_value() && *entry.second == "document-dark.css";
   }));
-  EXPECT_TRUE(service.exists("dark.css"));
+  EXPECT_TRUE(service.exists("document-dark.css"));
+}
+
+// Every view but the pdf one has a dark palette of its own: those are ours
+// rather than the file's, so the dark sheet only restates their tokens.
+TEST(html, color_scheme_reaches_every_view) {
+  HtmlConfig config;
+  config.color_scheme = HtmlColorScheme::dark;
+
+  // a text file, and the gutter it numbers its lines in
+  const std::string text = render("odr-public/txt/lorem ipsum.txt", config);
+  EXPECT_NE(text.find("--odr-text-gutter:#161b22"), std::string::npos);
+
+  // a source view
+  const DecodedFile xml_file(File::from_memory("<a><b>c</b></a>"),
+                             FileType::xml);
+  std::ostringstream xml;
+  html::translate(xml_file, config).list_views().at(0).write_html(xml);
+  EXPECT_NE(xml.str().find("--odr-xml-name:#7ee787"), std::string::npos);
+
+  // a file listing: the archive view of a zip
+  const DecodedFile archive(
+      TestData::test_file_path("odr-public/odt/about.odt"), FileType::zip,
+      Logger::null());
+  std::ostringstream listing;
+  html::translate(archive, config).list_views().at(0).write_html(listing);
+  EXPECT_NE(listing.str().find("--odr-files-link:#6cb6ff"), std::string::npos);
+
+  // the search mark turns its text over wherever a view paints one
+  EXPECT_NE(text.find("mark{color:#0d1117!important}"), std::string::npos);
+  EXPECT_NE(listing.str().find("mark{color:#0d1117!important}"),
+            std::string::npos);
 }
 
 TEST(html, views) {

From 1c37c3163c7793fa72803c1ac145b12e3ef868b8 Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Tue, 18 Aug 2026 08:43:12 +0200
Subject: [PATCH 3/4] feat: say whether a file type's view turns over in the
 dark
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`FileTypeCapabilities::color_scheme` answers for a file type what
`translate_html` answers about rendering at all: whether the view it renders as
honors `HtmlConfig::color_scheme`. A caller can offer the setting for the files
it applies to rather than for all of them, before it holds one.

True for every type that renders but a pdf, whose pages carry their own painted
backgrounds, and audio and video, which are black in any scheme. A decoded file
narrows it the way it narrows `translate_html`: a scheme only reaches html there
is.

The declaration is held against the renderer rather than maintained by hand:
the new test renders a file of each type in `light` and in `dark` and asserts
that the two differ exactly where the table says they should — flipping the pdf
row to claim support fails it.

Mirrored in the python, wasm, jni and apple bindings beside the capabilities
already there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rD1SK4k5Y6GQSzbCeKExY
---
 CHANGELOG.md                                  |   5 +
 apple/include/OdrCoreObjC/ODRFile.h           |   2 +
 apple/src/ODRFile.mm                          |   1 +
 .../core/FileTypeCapabilities.java            |   5 +
 jni/src/jni_style.cpp                         |   3 +-
 jni/tests/app/opendocument/core/MetaTest.java |   6 +
 python/src/bind_file.cpp                      |   1 +
 python/tests/test_meta.py                     |   6 +
 src/odr/file.cpp                              |   2 +
 src/odr/file.hpp                              |   8 +-
 src/odr/internal/file_type_table.cpp          | 146 ++++++++++++++----
 test/src/odr_test.cpp                         |  54 +++++++
 wasm/js/index.d.ts                            |   2 +
 wasm/src/odr_wasm.cpp                         |   1 +
 wasm/tests/smoke.test.mjs                     |   6 +
 15 files changed, 216 insertions(+), 32 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 795a778a8..36a539647 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,11 @@ The release run heads these entries with the version and opens a fresh
   fill to the page, a run of text to one legible against it — because no media
   query reaches an inline style. Mirrored in the python, wasm, jni and apple
   bindings as `HtmlColorScheme`.
+- `FileTypeCapabilities::color_scheme` says whether a file type's view honors
+  the setting, the way `translate_html` says whether it renders at all — true
+  for every type that renders but a pdf, whose pages paint their own
+  backgrounds, and audio and video, which are black in any scheme. Mirrored in
+  the bindings beside the capabilities already there.
 - A text document reflowed to the viewport — page margins off — is inset from
   the edge of the screen by 3mm instead of starting at the first pixel of it.
 - Prose is no longer read as a csv. A separator that every field follows with a
diff --git a/apple/include/OdrCoreObjC/ODRFile.h b/apple/include/OdrCoreObjC/ODRFile.h
index 337ded16f..d1b070786 100644
--- a/apple/include/OdrCoreObjC/ODRFile.h
+++ b/apple/include/OdrCoreObjC/ODRFile.h
@@ -129,6 +129,8 @@ NS_SWIFT_NAME(FileTypeCapabilities)
 @property(nonatomic, readonly) BOOL decrypt;
 /// `ODRHtml` produces output for it.
 @property(nonatomic, readonly) BOOL translateHtml;
+/// The view it renders as honors `ODRHtmlConfig.colorScheme`.
+@property(nonatomic, readonly) BOOL colorScheme;
 @property(nonatomic, readonly) BOOL edit;
 @property(nonatomic, readonly) BOOL save;
 /// Saving with a password is supported.
diff --git a/apple/src/ODRFile.mm b/apple/src/ODRFile.mm
index d1dad972d..472f05f83 100644
--- a/apple/src/ODRFile.mm
+++ b/apple/src/ODRFile.mm
@@ -156,6 +156,7 @@ + (instancetype)capabilitiesWithHandle:
   result->_open = handle.open ? YES : NO;
   result->_decrypt = handle.decrypt ? YES : NO;
   result->_translateHtml = handle.translate_html ? YES : NO;
+  result->_colorScheme = handle.color_scheme ? YES : NO;
   result->_edit = handle.edit ? YES : NO;
   result->_save = handle.save ? YES : NO;
   result->_encrypt = handle.encrypt ? YES : NO;
diff --git a/jni/java/app/opendocument/core/FileTypeCapabilities.java b/jni/java/app/opendocument/core/FileTypeCapabilities.java
index 8bb1369c2..2a36b7743 100644
--- a/jni/java/app/opendocument/core/FileTypeCapabilities.java
+++ b/jni/java/app/opendocument/core/FileTypeCapabilities.java
@@ -22,6 +22,9 @@ public final class FileTypeCapabilities {
   /** {@link Html#translate} produces output. */
   public final boolean translateHtml;
 
+  /** The view this type renders as honors {@link HtmlConfig#colorScheme}. */
+  public final boolean colorScheme;
+
   /** {@link Document#isEditable} can be {@code true}. */
   public final boolean edit;
 
@@ -36,6 +39,7 @@ public final class FileTypeCapabilities {
       boolean open,
       boolean decrypt,
       boolean translateHtml,
+      boolean colorScheme,
       boolean edit,
       boolean save,
       boolean encrypt) {
@@ -43,6 +47,7 @@ public final class FileTypeCapabilities {
     this.open = open;
     this.decrypt = decrypt;
     this.translateHtml = translateHtml;
+    this.colorScheme = colorScheme;
     this.edit = edit;
     this.save = save;
     this.encrypt = encrypt;
diff --git a/jni/src/jni_style.cpp b/jni/src/jni_style.cpp
index e890ff1b6..cddad91c3 100644
--- a/jni/src/jni_style.cpp
+++ b/jni/src/jni_style.cpp
@@ -296,11 +296,12 @@ jobject
 make_file_type_capabilities(JNIEnv *env,
                             const odr::FileTypeCapabilities &capabilities) {
   return new_object(env, "app/opendocument/core/FileTypeCapabilities",
-                    "(ZZZZZZZ)V",
+                    "(ZZZZZZZZ)V",
                     static_cast<jboolean>(capabilities.detect_by_content),
                     static_cast<jboolean>(capabilities.open),
                     static_cast<jboolean>(capabilities.decrypt),
                     static_cast<jboolean>(capabilities.translate_html),
+                    static_cast<jboolean>(capabilities.color_scheme),
                     static_cast<jboolean>(capabilities.edit),
                     static_cast<jboolean>(capabilities.save),
                     static_cast<jboolean>(capabilities.encrypt));
diff --git a/jni/tests/app/opendocument/core/MetaTest.java b/jni/tests/app/opendocument/core/MetaTest.java
index 1697b25e6..a54187c79 100644
--- a/jni/tests/app/opendocument/core/MetaTest.java
+++ b/jni/tests/app/opendocument/core/MetaTest.java
@@ -72,6 +72,7 @@ void capabilitiesByFileType() {
     FileTypeCapabilities odt = Odr.capabilitiesByFileType(FileType.OPENDOCUMENT_TEXT);
     assertTrue(odt.open);
     assertTrue(odt.translateHtml);
+    assertTrue(odt.colorScheme);
     assertTrue(odt.edit);
 
     // detected and named, but there is no decoder behind it
@@ -82,6 +83,11 @@ void capabilitiesByFileType() {
 
     // spreadsheet editing is force-disabled
     assertFalse(Odr.capabilitiesByFileType(FileType.OPENDOCUMENT_SPREADSHEET).edit);
+
+    // a pdf renders, but paints its own page backgrounds
+    FileTypeCapabilities pdf = Odr.capabilitiesByFileType(FileType.PORTABLE_DOCUMENT_FORMAT);
+    assertTrue(pdf.translateHtml);
+    assertFalse(pdf.colorScheme);
   }
 
   @Test
diff --git a/python/src/bind_file.cpp b/python/src/bind_file.cpp
index b0eaf79d6..ac48ef545 100644
--- a/python/src/bind_file.cpp
+++ b/python/src/bind_file.cpp
@@ -145,6 +145,7 @@ void odr_python::bind_file(py::module_ &m) {
       .def_readwrite("decrypt", &odr::FileTypeCapabilities::decrypt)
       .def_readwrite("translate_html",
                      &odr::FileTypeCapabilities::translate_html)
+      .def_readwrite("color_scheme", &odr::FileTypeCapabilities::color_scheme)
       .def_readwrite("edit", &odr::FileTypeCapabilities::edit)
       .def_readwrite("save", &odr::FileTypeCapabilities::save)
       .def_readwrite("encrypt", &odr::FileTypeCapabilities::encrypt);
diff --git a/python/tests/test_meta.py b/python/tests/test_meta.py
index 01cde621f..8c0a71acf 100644
--- a/python/tests/test_meta.py
+++ b/python/tests/test_meta.py
@@ -96,6 +96,7 @@ def test_capabilities_by_file_type():
     odt = pyodr.capabilities_by_file_type(pyodr.FileType.opendocument_text)
     assert odt.open
     assert odt.translate_html
+    assert odt.color_scheme
     assert odt.edit
 
     # detected and named, but there is no decoder behind it
@@ -109,6 +110,11 @@ def test_capabilities_by_file_type():
         pyodr.FileType.opendocument_spreadsheet
     ).edit
 
+    # a pdf renders, but paints its own page backgrounds
+    pdf = pyodr.capabilities_by_file_type(pyodr.FileType.portable_document_format)
+    assert pdf.translate_html
+    assert not pdf.color_scheme
+
 
 def test_decoded_file_capabilities(odt_path):
     capabilities = pyodr.open(str(odt_path)).capabilities()
diff --git a/src/odr/file.cpp b/src/odr/file.cpp
index e64fc15e1..46fb29e1c 100644
--- a/src/odr/file.cpp
+++ b/src/odr/file.cpp
@@ -172,6 +172,8 @@ FileTypeCapabilities DecodedFile::capabilities() const {
   // an encrypted file has to be decrypted before it renders
   result.translate_html =
       result.translate_html && encryption_state() != EncryptionState::encrypted;
+  // a scheme only reaches html there is
+  result.color_scheme = result.color_scheme && result.translate_html;
 
   // `edit`/`save`/`encrypt` stay as declared — resolving them would mean
   // decoding the document; ask `Document` for the precise answer
diff --git a/src/odr/file.hpp b/src/odr/file.hpp
index 61ed44c74..3d5d19143 100644
--- a/src/odr/file.hpp
+++ b/src/odr/file.hpp
@@ -182,8 +182,12 @@ struct FileTypeCapabilities final {
   bool open{};              ///< a decoder exists; @ref odr::open can decode it
   bool decrypt{};           ///< encrypted instances can be decrypted
   bool translate_html{};    ///< @ref html::translate produces output
-  bool edit{};              ///< @ref Document::is_editable can be `true`
-  bool save{};              ///< @ref Document::save is supported
+  /// the view this type renders as honors @ref HtmlConfig::color_scheme — a
+  /// pdf paints its page backgrounds itself, and a media view is black in any
+  /// scheme
+  bool color_scheme{};
+  bool edit{};    ///< @ref Document::is_editable can be `true`
+  bool save{};    ///< @ref Document::save is supported
   bool encrypt{}; ///< @ref Document::save with a password is supported
 };
 
diff --git a/src/odr/internal/file_type_table.cpp b/src/odr/internal/file_type_table.cpp
index 093ecd948..61c6ecdd1 100644
--- a/src/odr/internal/file_type_table.cpp
+++ b/src/odr/internal/file_type_table.cpp
@@ -269,6 +269,7 @@ constexpr std::array table{
          .open = true,
          .decrypt = true,
          .translate_html = true,
+         .color_scheme = true,
          .edit = true,
          .save = true}},
     Row{FileType::opendocument_presentation,
@@ -281,6 +282,7 @@ constexpr std::array table{
          .open = true,
          .decrypt = true,
          .translate_html = true,
+         .color_scheme = true,
          .edit = true,
          .save = true}},
     // ODF spreadsheet editing is force-disabled, see `odf::Document`.
@@ -294,6 +296,7 @@ constexpr std::array table{
          .open = true,
          .decrypt = true,
          .translate_html = true,
+         .color_scheme = true,
          .save = true}},
     Row{FileType::opendocument_graphics,
         "odg"sv,
@@ -305,6 +308,7 @@ constexpr std::array table{
          .open = true,
          .decrypt = true,
          .translate_html = true,
+         .color_scheme = true,
          .edit = true,
          .save = true}},
 
@@ -318,6 +322,7 @@ constexpr std::array table{
          .open = true,
          .decrypt = true,
          .translate_html = true,
+         .color_scheme = true,
          .edit = true,
          .save = true}},
     Row{FileType::office_open_xml_presentation,
@@ -329,7 +334,8 @@ constexpr std::array table{
         {.detect_by_content = true,
          .open = true,
          .decrypt = true,
-         .translate_html = true}},
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::office_open_xml_workbook,
         "xlsx"sv,
         xlsx_extensions,
@@ -339,7 +345,8 @@ constexpr std::array table{
         {.detect_by_content = true,
          .open = true,
          .decrypt = true,
-         .translate_html = true}},
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::office_open_xml_encrypted,
         "ooxml_encrypted"sv,
         {},
@@ -362,21 +369,30 @@ constexpr std::array table{
         doc_mimetypes,
         FileCategory::document,
         DocumentType::text,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::legacy_powerpoint_presentation,
         "ppt"sv,
         ppt_extensions,
         ppt_mimetypes,
         FileCategory::document,
         DocumentType::presentation,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::legacy_excel_worksheets,
         "xls"sv,
         xls_extensions,
         xls_mimetypes,
         FileCategory::document,
         DocumentType::spreadsheet,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 
     // Recognised by magic so a caller can name the type, but there is no
     // decoder behind either of these.
@@ -412,21 +428,30 @@ constexpr std::array table{
         txt_mimetypes,
         FileCategory::text,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::comma_separated_values,
         "csv"sv,
         csv_extensions,
         csv_mimetypes,
         FileCategory::text,
         DocumentType::spreadsheet,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::javascript_object_notation,
         "json"sv,
         json_extensions,
         json_mimetypes,
         FileCategory::text,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     // Classified for callers that route files by type; there is no decoder.
     Row{FileType::markdown,
         "md"sv,
@@ -442,14 +467,20 @@ constexpr std::array table{
         zip_mimetypes,
         FileCategory::archive,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::compound_file_binary_format,
         "cfb"sv,
         cfb_extensions,
         cfb_mimetypes,
         FileCategory::archive,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 
     Row{FileType::portable_network_graphics,
         "png"sv,
@@ -457,35 +488,50 @@ constexpr std::array table{
         png_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::graphics_interchange_format,
         "gif"sv,
         gif_extensions,
         gif_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::jpeg,
         "jpg"sv,
         jpg_extensions,
         jpg_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::bitmap_image_file,
         "bmp"sv,
         bmp_extensions,
         bmp_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::starview_metafile,
         "svm"sv,
         svm_extensions,
         svm_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 
     Row{FileType::truetype_font,
         "ttf"sv,
@@ -493,14 +539,20 @@ constexpr std::array table{
         ttf_mimetypes,
         FileCategory::font,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::opentype_font,
         "otf"sv,
         otf_extensions,
         otf_mimetypes,
         FileCategory::font,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 
     // Named but not decoded: `open` wraps the bytes and `translate_html` hands
     // them to the browser in an `<img>` or a player. Nothing reads a pixel or
@@ -511,28 +563,40 @@ constexpr std::array table{
         webp_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::tagged_image_file_format,
         "tiff"sv,
         tiff_extensions,
         tiff_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::high_efficiency_image_format,
         "heif"sv,
         heif_extensions,
         heif_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::av1_image_file_format,
         "avif"sv,
         avif_extensions,
         avif_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 
     Row{FileType::mpeg_audio,
         "mp3"sv,
@@ -615,49 +679,70 @@ constexpr std::array table{
         svg_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::windows_icon,
         "ico"sv,
         ico_extensions,
         ico_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::jpeg_xl,
         "jxl"sv,
         jxl_extensions,
         jxl_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::jpeg_2000,
         "jp2"sv,
         jp2_extensions,
         jp2_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::photoshop_document,
         "psd"sv,
         psd_extensions,
         psd_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::windows_metafile,
         "wmf"sv,
         wmf_extensions,
         wmf_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
     Row{FileType::enhanced_metafile,
         "emf"sv,
         emf_extensions,
         emf_mimetypes,
         FileCategory::image,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 
     // Not decoded: it renders as a source view of itself.
     Row{FileType::xml,
@@ -666,7 +751,10 @@ constexpr std::array table{
         xml_mimetypes,
         FileCategory::text,
         DocumentType::unknown,
-        {.detect_by_content = true, .open = true, .translate_html = true}},
+        {.detect_by_content = true,
+         .open = true,
+         .translate_html = true,
+         .color_scheme = true}},
 };
 
 /// Finds the row whose list, selected by @p list, contains @p needle.
diff --git a/test/src/odr_test.cpp b/test/src/odr_test.cpp
index fd91eb55d..2bcc8bfa6 100644
--- a/test/src/odr_test.cpp
+++ b/test/src/odr_test.cpp
@@ -1,6 +1,7 @@
 #include <odr/document.hpp>
 #include <odr/exceptions.hpp>
 #include <odr/file.hpp>
+#include <odr/html.hpp>
 #include <odr/odr.hpp>
 
 #include <test_util.hpp>
@@ -8,6 +9,7 @@
 #include <algorithm>
 #include <optional>
 #include <set>
+#include <sstream>
 #include <string>
 #include <string_view>
 #include <vector>
@@ -155,6 +157,58 @@ TEST(FileTypeTable, capabilities_build_on_each_other) {
     if (capabilities.edit) {
       EXPECT_TRUE(capabilities.save) << file_type_to_string(type);
     }
+    if (!capabilities.translate_html) {
+      EXPECT_FALSE(capabilities.color_scheme) << file_type_to_string(type);
+    }
+  }
+}
+
+/// The anti-drift check behind `color_scheme`: the declaration names the views
+/// that turn over, so it is held against what the renderer emits. A scheme
+/// other than light either changes the html or the type does not claim it.
+TEST(FileTypeCapabilities, color_scheme_matches_the_html) {
+  const auto &logger = Logger::null();
+
+  for (const FileType type : every_file_type()) {
+    const FileTypeCapabilities declared = capabilities_by_file_type(type);
+    if (!declared.translate_html) {
+      continue;
+    }
+
+    const std::vector<TestFile> test_files = TestData::test_files(type);
+    if (test_files.empty() || test_files.front().password.has_value()) {
+      continue;
+    }
+
+    std::optional<DecodedFile> file;
+    try {
+      file = open(test_files.front().absolute_path, type, logger);
+    } catch (...) {
+      continue;
+    }
+
+    const auto render = [&](const HtmlColorScheme scheme) {
+      HtmlConfig config;
+      config.color_scheme = scheme;
+      // one page of a pdf is enough, and the rest is slow
+      config.page_range_end = 1;
+
+      std::ostringstream out;
+      html::translate(*file, config).list_views().at(0).write_html(out);
+      return out.str();
+    };
+
+    std::string light;
+    std::string dark;
+    try {
+      light = render(HtmlColorScheme::light);
+      dark = render(HtmlColorScheme::dark);
+    } catch (...) {
+      continue;
+    }
+
+    EXPECT_EQ(light != dark, declared.color_scheme)
+        << file_type_to_string(type) << " " << test_files.front().short_path;
   }
 }
 
diff --git a/wasm/js/index.d.ts b/wasm/js/index.d.ts
index 783a71f35..d2e3de296 100644
--- a/wasm/js/index.d.ts
+++ b/wasm/js/index.d.ts
@@ -20,6 +20,8 @@ export interface Capabilities {
   open: boolean;
   decrypt: boolean;
   translateHtml: boolean;
+  /** The view this type renders as honors `HtmlConfig.colorScheme`. */
+  colorScheme: boolean;
   edit: boolean;
   save: boolean;
   encrypt: boolean;
diff --git a/wasm/src/odr_wasm.cpp b/wasm/src/odr_wasm.cpp
index 1c9f09411..4cc983a5e 100644
--- a/wasm/src/odr_wasm.cpp
+++ b/wasm/src/odr_wasm.cpp
@@ -118,6 +118,7 @@ emscripten::val to_capabilities(const FileTypeCapabilities &capabilities) {
   result.set("open", capabilities.open);
   result.set("decrypt", capabilities.decrypt);
   result.set("translateHtml", capabilities.translate_html);
+  result.set("colorScheme", capabilities.color_scheme);
   result.set("edit", capabilities.edit);
   result.set("save", capabilities.save);
   result.set("encrypt", capabilities.encrypt);
diff --git a/wasm/tests/smoke.test.mjs b/wasm/tests/smoke.test.mjs
index 8dec6820a..703accc6e 100644
--- a/wasm/tests/smoke.test.mjs
+++ b/wasm/tests/smoke.test.mjs
@@ -64,8 +64,14 @@ describe('smoke', () => {
     assert.ok(odt.extensions.includes('odt'));
     assert.ok(odt.mimeTypes.includes('application/vnd.oasis.opendocument.text'));
     assert.equal(odt.capabilities.translateHtml, true);
+    assert.equal(odt.capabilities.colorScheme, true);
     assert.equal(odt.capabilities.open, true);
 
+    // a pdf renders, but paints its own page backgrounds
+    const pdf = types.find((t) => t.name === 'pdf');
+    assert.equal(pdf.capabilities.translateHtml, true);
+    assert.equal(pdf.capabilities.colorScheme, false);
+
     // both tables are always present, so a caller may concatenate without
     // checking
     for (const type of types) {

From d69b83e8e82c38d9988c1b79a36cc0781890c89a Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Tue, 18 Aug 2026 09:12:05 +0200
Subject: [PATCH 4/4] docs: say the dark scheme in fewer words

Trim the comments and changelog entries added with the color scheme down
to the point they make. Also drops a wrong line in ODRHtml.h: the source
view and the file listing do honor the scheme.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FEQYAReR6DqLpHFSisoehj
---
 CHANGELOG.md                        | 24 +++++----------
 apple/include/OdrCoreObjC/ODRHtml.h |  4 +--
 src/odr/file.cpp                    |  2 +-
 src/odr/file.hpp                    |  9 ++----
 src/odr/html.hpp                    | 11 +++----
 src/odr/internal/html/frontend.cpp  | 45 ++++++++---------------------
 src/odr/internal/html/frontend.hpp  | 11 +++----
 test/src/html_test.cpp              | 11 +++----
 test/src/odr_test.cpp               |  4 +--
 9 files changed, 39 insertions(+), 82 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 36a539647..387a4c073 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,22 +16,14 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
-- A file can be read in the dark: `HtmlConfig::color_scheme` is `light` (a white
-  page, what it has always been), `dark`, or `system`, which follows the
-  reader's `prefers-color-scheme`. Every view honors it but the pdf one, which
-  paints its page backgrounds itself — a text document flowing or paged, a
-  sheet, a slide, a drawing, a text file, a source view, a file listing, an
-  image, a font specimen. The colors the file itself authored give way to it — a
-  fill to the page, a run of text to one legible against it — because no media
-  query reaches an inline style. Mirrored in the python, wasm, jni and apple
-  bindings as `HtmlColorScheme`.
-- `FileTypeCapabilities::color_scheme` says whether a file type's view honors
-  the setting, the way `translate_html` says whether it renders at all — true
-  for every type that renders but a pdf, whose pages paint their own
-  backgrounds, and audio and video, which are black in any scheme. Mirrored in
-  the bindings beside the capabilities already there.
-- A text document reflowed to the viewport — page margins off — is inset from
-  the edge of the screen by 3mm instead of starting at the first pixel of it.
+- A file can be read in the dark: `HtmlConfig::color_scheme` is `light`, `dark`
+  or `system`, following the reader's `prefers-color-scheme`. Every view honors
+  it but the pdf one, and the colors the file authored give way to it. Bound in
+  the python, wasm, jni and apple bindings as `HtmlColorScheme`.
+- `FileTypeCapabilities::color_scheme` says whether a type's view honors it —
+  every type that renders but pdf, audio and video. Bound in the bindings too.
+- A text document reflowed to the viewport is inset 3mm from the screen edge
+  rather than starting at the first pixel of it.
 - Prose is no longer read as a csv. A separator that every field follows with a
   space, in fields long enough to be sentences, is punctuation; `a, b, c` with
   short values is still a csv. One record is a line, not a table.
diff --git a/apple/include/OdrCoreObjC/ODRHtml.h b/apple/include/OdrCoreObjC/ODRHtml.h
index acbddc103..8b46496c1 100644
--- a/apple/include/OdrCoreObjC/ODRHtml.h
+++ b/apple/include/OdrCoreObjC/ODRHtml.h
@@ -26,8 +26,8 @@ typedef NS_ENUM(NSInteger, ODRHtmlTableGridlines) {
   ODRHtmlTableGridlinesHard,
 } NS_SWIFT_NAME(HtmlTableGridlines);
 
-/// The colors the emitted HTML renders a document against. Only the document
-/// views honor it; a pdf, a source view or a file listing brings its own.
+/// The colors the emitted HTML renders against. `ODRFileTypeCapabilities`
+/// says which views honor it.
 typedef NS_ENUM(NSInteger, ODRHtmlColorScheme) {
   /// A white page, carrying the colors the document gives its content.
   ODRHtmlColorSchemeLight = 0,
diff --git a/src/odr/file.cpp b/src/odr/file.cpp
index 46fb29e1c..c91d2e488 100644
--- a/src/odr/file.cpp
+++ b/src/odr/file.cpp
@@ -172,7 +172,7 @@ FileTypeCapabilities DecodedFile::capabilities() const {
   // an encrypted file has to be decrypted before it renders
   result.translate_html =
       result.translate_html && encryption_state() != EncryptionState::encrypted;
-  // a scheme only reaches html there is
+  // there is no scheme without html
   result.color_scheme = result.color_scheme && result.translate_html;
 
   // `edit`/`save`/`encrypt` stay as declared — resolving them would mean
diff --git a/src/odr/file.hpp b/src/odr/file.hpp
index 3d5d19143..45aea9375 100644
--- a/src/odr/file.hpp
+++ b/src/odr/file.hpp
@@ -182,12 +182,9 @@ struct FileTypeCapabilities final {
   bool open{};              ///< a decoder exists; @ref odr::open can decode it
   bool decrypt{};           ///< encrypted instances can be decrypted
   bool translate_html{};    ///< @ref html::translate produces output
-  /// the view this type renders as honors @ref HtmlConfig::color_scheme — a
-  /// pdf paints its page backgrounds itself, and a media view is black in any
-  /// scheme
-  bool color_scheme{};
-  bool edit{};    ///< @ref Document::is_editable can be `true`
-  bool save{};    ///< @ref Document::save is supported
+  bool color_scheme{};      ///< the view honors @ref HtmlConfig::color_scheme
+  bool edit{};              ///< @ref Document::is_editable can be `true`
+  bool save{};              ///< @ref Document::save is supported
   bool encrypt{}; ///< @ref Document::save with a password is supported
 };
 
diff --git a/src/odr/html.hpp b/src/odr/html.hpp
index 367206f11..2f7cfa8ee 100644
--- a/src/odr/html.hpp
+++ b/src/odr/html.hpp
@@ -73,14 +73,11 @@ enum class HtmlTableGridlines {
   hard,
 };
 
-/// @brief The colors the emitted HTML renders against. Every view honors it but
-/// the pdf one, which paints its page backgrounds itself; a media view is black
-/// in any scheme.
+/// @brief The colors the emitted HTML renders against. @ref
+/// FileTypeCapabilities::color_scheme says which views honor it.
 enum class HtmlColorScheme {
-  light, ///< a white page, carrying the colors the document gives its content
-  dark,  ///< a dark page, which the document's own text and fill colors give
-         ///< way to — no media query reaches an inline style, so they lose to
-         ///< `!important` rather than being dropped as the file is read
+  light,  ///< a white page, carrying the colors the document gives its content
+  dark,   ///< a dark page, which the document's own colors give way to
   system, ///< `light` or `dark`, by the reader's `prefers-color-scheme`
 };
 
diff --git a/src/odr/internal/html/frontend.cpp b/src/odr/internal/html/frontend.cpp
index 20a3c9021..733406993 100644
--- a/src/odr/internal/html/frontend.cpp
+++ b/src/odr/internal/html/frontend.cpp
@@ -35,10 +35,8 @@ x-s{display:inline}
    Not a negative `z-index`, which is one too but takes the page out of reach of
    hit testing. */
 .odr-page-outer{display:flex;margin:0 16px;background:#fff;box-shadow:0 1px 4px rgba(0,0,0,.5);isolation:isolate}
-/* Reflowed to the viewport there is no page box to inset the text, and the body
-   has no margin of its own, so it would begin at the screen edge. A page's own
-   margin is a physical measure, and so is this one, rather than a `ch` of
-   whatever font the browser happens to default to. */
+/* Reflowed to the viewport there is no page box to inset the text. A physical
+   measure, like the page margin it stands in for. */
 .odr-text-flow{padding:3mm}
 /* The label is text rather than a `::marker`, which no selection would copy.
    It hangs into the item's padding so wrapped lines align under the text. */
@@ -46,29 +44,19 @@ x-s{display:inline}
 .odr-list-marker{display:inline-block;min-width:2em;margin-left:-2em;white-space:pre}
 )css";
 
-/// The dark counterpart of the style above. Every view but the pdf one has one,
-/// written straight after the sheet it restates, and — for @ref
-/// odr::HtmlColorScheme::system — carried by an element whose `media` attribute
-/// gates it. That is what lets a rule in here be plain: none of them could sit
-/// inside a query and still reach a color the document sets inline.
+/// Dark counterpart of the style above. The `media` attribute of the element
+/// carrying it gates it — a rule inside a query cannot beat an inline color.
 constexpr std::string_view document_dark_css = R"css(
 :root{color-scheme:dark}
 body{background:#0d1117;color:#e6edf3}
-/* The backdrop stays darker than the page, as it is lighter than it in light:
-   what makes a page read as a sheet is the step between them. */
+/* The step to the page is what makes it read as a sheet. */
 .odr-background{background:#010409}
 .odr-page-outer{background-color:#161b22!important;box-shadow:0 1px 4px rgba(0,0,0,.8)}
-/* The colors the file authored are inline, and no media query reaches an inline
-   style — so they are overridden here rather than dropped as the file is read.
-   Every fill gives way to the page and every run of text to one legible against
-   it, which costs a slide its own fills and is what keeps its text readable.
+/* Fills give way to the page, text to one legible against it.
    `background-image` is left alone: a page printed on a picture keeps it. */
 div,table,tr,td,x-p,x-s{background-color:transparent!important}
-/* A shape's fill is not a background: `translate_drawing_style` writes it as the
-   svg `fill` that the rect or circle we draw inside it inherits. It gives way
-   like one, or a light box would keep its fill and lose its text to the ink
-   above. The stroke is left as the file set it: it is the shape's line, not its
-   ground. */
+/* A shape's fill is an svg `fill` (`translate_drawing_style`), not a
+   background, and gives way like one. The stroke stays: it is the line. */
 svg,svg *{fill:transparent!important}
 td,x-p,x-s{color:#e6edf3!important}
 a,a x-p,a x-s{color:#6cb6ff!important}
@@ -121,7 +109,6 @@ body{margin:0;background:var(--odr-sheet-canvas)}
 .odr-sheet-sort-asc::after{content:"\25B4"}
 )css";
 
-/// The sheet is a surface like a page, and reads against a canvas the same way.
 constexpr std::string_view spreadsheet_dark_css = R"css(
 :root{
 --odr-sheet-line:#30363d;
@@ -164,8 +151,7 @@ body{margin:0;background:#fff}
 [contenteditable]:focus{outline:none}
 )css";
 
-/// The gutter is a surface beside the page, so it steps the other way in dark:
-/// lighter than the text it numbers, where in light it is darker.
+/// The gutter steps the other way in dark: lighter than the ground.
 constexpr std::string_view text_dark_css = R"css(
 :root{
 color-scheme:dark;
@@ -213,8 +199,6 @@ body{margin:0;background:#fff}
 .odr-xml-decl,.odr-xml-doctype,.odr-xml-pi{color:var(--odr-xml-meta)}
 )css";
 
-/// The same six parts of a document, in the cuts of them that carry on a dark
-/// ground.
 constexpr std::string_view xml_dark_css = R"css(
 :root{
 color-scheme:dark;
@@ -252,8 +236,7 @@ body{margin:0;background:#fff;color:#1f2328;font:13px/1.5 var(--odr-files-font)}
 .odr-files-action a:hover{background:rgba(0,0,0,.07);color:var(--odr-files-link)}
 )css";
 
-/// The washes are lightened rather than darkened: on a dark row a black one
-/// paints nothing.
+/// The washes lighten rather than darken: a black one paints nothing here.
 constexpr std::string_view filesystem_dark_css = R"css(
 :root{
 color-scheme:dark;
@@ -279,8 +262,7 @@ mark{background:#ff0}
 mark.current{background:orange}
 )css";
 
-/// The mark is ours rather than the file's and keeps its yellow, the one light
-/// thing left on the page; only the text on it turns over.
+/// The mark keeps its yellow; only the text on it turns over.
 constexpr std::string_view search_dark_css = R"css(
 mark{color:#0d1117!important}
 )css";
@@ -1256,8 +1238,7 @@ HtmlResources locate_all(const std::span<const Asset> assets,
   return resources;
 }
 
-/// Adds the dark sheets where the config asks for them: a view has to answer
-/// for what its markup links, and it links those only then.
+/// Adds the dark sheets where the config asks for them.
 HtmlResources locate_all(const std::span<const Asset> assets,
                          const std::span<const Asset> dark,
                          const HtmlConfig &config) {
@@ -1285,8 +1266,6 @@ void write_style(const Asset &asset, const WritingState &state,
   state.out().write_header_style_end();
 }
 
-/// Writes @p asset where the config asks for a dark scheme, gated on the
-/// reader's preference where it asks to follow it.
 void write_dark_style(const Asset &asset, const WritingState &state) {
   if (writes_dark_style(state.config())) {
     write_style(asset, state, dark_style_media(state.config()));
diff --git a/src/odr/internal/html/frontend.hpp b/src/odr/internal/html/frontend.hpp
index 8d63af7e3..f0047335f 100644
--- a/src/odr/internal/html/frontend.hpp
+++ b/src/odr/internal/html/frontend.hpp
@@ -12,9 +12,7 @@ struct WritingState;
 /// as a shipped @ref odr::HtmlResource when the config asks for that.
 
 /// Each `write_*_dark_style` follows the style it restates and writes nothing
-/// unless the config asks for a scheme other than
-/// @ref odr::HtmlColorScheme::light. The pdf view has none: it paints its page
-/// backgrounds itself.
+/// for @ref odr::HtmlColorScheme::light.
 
 void write_document_style(const WritingState &state);
 void write_document_dark_style(const WritingState &state);
@@ -27,15 +25,14 @@ void write_xml_style(const WritingState &state);
 void write_xml_dark_style(const WritingState &state);
 void write_filesystem_style(const WritingState &state);
 void write_filesystem_dark_style(const WritingState &state);
-/// The media view is black in every scheme, and has no dark style.
+/// Black in every scheme, so no dark style.
 void write_media_style(const WritingState &state);
 /// Written by every view that writes the search script.
 void write_search_style(const WritingState &state);
 void write_search_dark_style(const WritingState &state);
 
-/// For a view writing its style inline rather than as a shipped asset: whether
-/// to write a dark one at all, and the `media` gating it — empty where the
-/// config asks for dark outright.
+/// For a view writing its style inline: whether to write a dark one, and the
+/// `media` gating it — empty for @ref odr::HtmlColorScheme::dark.
 bool writes_dark_style(const HtmlConfig &config);
 std::string_view dark_style_media(const HtmlConfig &config);
 
diff --git a/test/src/html_test.cpp b/test/src/html_test.cpp
index 9d05add0d..5cddf632d 100644
--- a/test/src/html_test.cpp
+++ b/test/src/html_test.cpp
@@ -157,8 +157,7 @@ std::string render_odt(const HtmlConfig &config) {
 
 } // namespace
 
-// Reflowed to the viewport a text document has no page box to inset it, and the
-// body carries no margin of its own.
+// Reflowed to the viewport there is no page box to inset the text.
 TEST(html, flowing_text_is_inset_from_the_screen_edge) {
   HtmlConfig config;
   config.text_document_margin = false;
@@ -169,9 +168,8 @@ TEST(html, flowing_text_is_inset_from_the_screen_edge) {
   EXPECT_NE(page.find(".odr-text-flow{padding:"), std::string::npos);
 }
 
-// The colors a document sets are inline, out of reach of a media query, so the
-// dark scheme is a stylesheet that overrides them — and for `system` it is the
-// element carrying that stylesheet which is gated, not a rule inside it.
+// For `system` it is the element carrying the dark style that is gated, not a
+// rule inside it.
 TEST(html, color_scheme_writes_the_dark_style) {
   HtmlConfig config;
 
@@ -213,8 +211,7 @@ TEST(html, linked_dark_style_is_served) {
   EXPECT_TRUE(service.exists("document-dark.css"));
 }
 
-// Every view but the pdf one has a dark palette of its own: those are ours
-// rather than the file's, so the dark sheet only restates their tokens.
+// Every view but the pdf one turns over.
 TEST(html, color_scheme_reaches_every_view) {
   HtmlConfig config;
   config.color_scheme = HtmlColorScheme::dark;
diff --git a/test/src/odr_test.cpp b/test/src/odr_test.cpp
index 2bcc8bfa6..11bd2d6e8 100644
--- a/test/src/odr_test.cpp
+++ b/test/src/odr_test.cpp
@@ -163,9 +163,7 @@ TEST(FileTypeTable, capabilities_build_on_each_other) {
   }
 }
 
-/// The anti-drift check behind `color_scheme`: the declaration names the views
-/// that turn over, so it is held against what the renderer emits. A scheme
-/// other than light either changes the html or the type does not claim it.
+/// Holds the declared `color_scheme` against what the renderer emits.
 TEST(FileTypeCapabilities, color_scheme_matches_the_html) {
   const auto &logger = Logger::null();