feat(render): typed text in read-only image + device-accurate layout & wrapping (#116)

SamMorrowDrums · Copilot · web-flow · commit a9c23360b937 · 2026-06-12T18:01:39.000+02:00
* feat(render): show typed text in read-only remarkable_image render

The content-cropped render path used by remarkable_image (and the
merged-PDF annotation layer) only drew ink strokes, so typed text was
invisible and text-only pages returned no image at all.

Refactor _v6_text_svg_elements into _v6_text_elements_with_bounds, which
also returns each line's bounding coordinates, and fold those into the
cropped viewBox in _render_rm_v6_to_svg. Text is drawn under strokes to
match device compositing, and a text-only page now renders instead of
returning None.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;

* fix(render): calibrate typed-text layout to device + wrap long lines

The typed-text layout used rmc's rM2-derived constants (7pt font in a
72/226-DPI space, top offset -88). Validated against a reMarkable Paper
Pro's own page thumbnail, that renders text noticeably smaller and ~50
units higher than the device actually draws it, so a circle drawn around
a title in the canvas landed above the title on-device. Long paragraphs
also overflowed the text box because SVG &lt;text&gt; does not wrap.

- Recalibrate constants in raw stroke units against the device thumbnail:
  font 30, top offset -39, line height 70. First-line baseline and every
  body line now match the device within ~1px.
- Add greedy word-wrapping (_wrap_text) to the text-box width, with
  continuation lines spaced tighter (~44 vs 70) like the device. The long
  'Goliath frog' line now wraps at the same point the device wraps it.
- Scale all metrics by the page's real height so they adapt to other
  geometries (Move, Paper Pro, classic) that normalize differently;
  identity for the standard 1404x1872 page.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;

* test: guard typed-text metric scaling across page geometries

Add test_typed_text_metrics_scale_with_page_height asserting that the
typed-text line height and font size scale linearly with the page's
normalized height. run_smoke only checks render PASS/FAIL, not pixel
layout, so this is the regression guard for the Move/classic page-height
scaling path.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;

---------

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/remarkable_mcp/extract.py b/remarkable_mcp/extract.py
@@ -578,86 +578,154 @@ def _v6_paths_from_blocks(blocks: list) -> Tuple[list, list]:
     return paths, all_coords
 
 
-# reMarkable typed-text layout, in stroke/screen units. Mirrors the rmc
-# exporter (github.com/ricklupton/rmc) so typed text (a RootTextBlock) renders
-# in the full-page view at the same place the device draws it. rmc lays text
-# out in a 72/226-DPI point space; our full-page SVG works in raw screen units,
-# so point font sizes are converted to screen units via _PT_TO_SCREEN.
-_TEXT_TOP_Y = -88
-_PT_TO_SCREEN = 226.0 / 72.0
+# reMarkable typed-text layout, in raw stroke units. Calibrated against
+# device-rendered page thumbnails (a reMarkable Paper Pro / "Ferrari", which
+# normalizes typed text into the same 1404x1872 coordinate space as the rM1/2).
+# These differ from the rmc exporter's constants (github.com/ricklupton/rmc):
+# rmc lays text out in a 72/226-DPI-scaled space and its plain font (7pt) and
+# top offset (-88) render text noticeably smaller and higher than the device
+# actually draws it. Values here are in the reference 1404x1872 space and are
+# scaled by the page's real height (see ``_TEXT_REF_PAGE_HEIGHT``) so they adapt
+# to other geometries (e.g. reMarkable Move) that normalize differently.
+_TEXT_REF_PAGE_HEIGHT = 1872.0
+_TEXT_TOP_Y = -39.0
+_TEXT_DEFAULT_LINE_HEIGHT = 70.0
+_TEXT_DEFAULT_FONT_SIZE = 30.0
+# Continuation lines of a wrapped paragraph are spaced tighter than the gap
+# between paragraphs (device uses ~44 vs ~70 units for plain text).
+_TEXT_WRAP_LINE_RATIO = 44.0 / 70.0
+# Average glyph advance as a fraction of font size, used only to wrap a
+# paragraph to the text-box width (SVG <text> does not wrap on its own).
+_TEXT_CHAR_ADVANCE = 0.5
+
+
+def _wrap_text(text: str, max_width: float, char_advance: float) -> List[str]:
+    """Greedily word-wrap ``text`` to ``max_width`` (stroke units).
+
+    SVG ``<text>`` does not wrap, so paragraphs wider than the text box are
+    split here the way the device wraps them. Line width is approximated as
+    ``len(line) * char_advance`` -- good enough for a faithful preview without
+    embedding the device font. A single word longer than the box is left on its
+    own line rather than split. Returns ``[text]`` when no wrapping applies.
+    """
+    if max_width <= 0 or char_advance <= 0:
+        return [text]
+    lines: List[str] = []
+    cur = ""
+    for word in text.split(" "):
+        trial = word if not cur else f"{cur} {word}"
+        if not cur or len(trial) * char_advance <= max_width:
+            cur = trial
+        else:
+            lines.append(cur)
+            cur = word
+    if cur:
+        lines.append(cur)
+    return lines
 
 
 def _v6_text_svg_elements(blocks: list) -> list:
     """Build SVG ``<text>`` strings for typed text (a RootTextBlock) on a page.
 
-    Returns an empty list when the page has no typed text (the common case for
+    Thin wrapper around :func:`_v6_text_elements_with_bounds` for callers (e.g.
+    the full-page render) that fix the viewBox to the page extent and so do not
+    need the text's bounding coordinates.
+    """
+    return _v6_text_elements_with_bounds(blocks)[0]
+
+
+def _v6_text_elements_with_bounds(blocks: list) -> Tuple[list, list]:
+    """Build SVG ``<text>`` strings plus their bounding coords for typed text.
+
+    Returns ``(elements, coords)`` where ``coords`` is a flat list of ``(x, y)``
+    extent points (in the page's stroke/screen units, center-origin X) so a
+    content-cropped render can size its viewBox to include the text. Returns
+    ``([], [])`` when the page has no typed text (the common case for
     handwritten notebooks) or when rmscene's text helpers are unavailable.
-    Coordinates are in the page's own stroke/screen units (center-origin X),
-    matching :func:`_svg_full_page`, so text lands where the device shows it.
     """
     try:
         from rmscene.scene_items import ParagraphStyle, Text
         from rmscene.text import TextDocument
     except ImportError:
-        return []
+        return [], []
 
     text_item = next(
         (b.value for b in blocks if isinstance(getattr(b, "value", None), Text)),
         None,
     )
     if text_item is None:
-        return []
+        return [], []
 
     # Blank pages we synthesize carry an empty RootTextBlock; skip them so we
     # neither emit empty <text> nodes nor trigger rmscene's empty-item warning.
     try:
         if not any(isinstance(v, str) and v.strip() for v in text_item.items.values()):
-            return []
+            return [], []
     except Exception:
         pass
 
     line_heights = {
-        ParagraphStyle.PLAIN: 70,
-        ParagraphStyle.HEADING: 150,
-        ParagraphStyle.BOLD: 70,
-        ParagraphStyle.BULLET: 35,
-        ParagraphStyle.BULLET2: 35,
-        ParagraphStyle.CHECKBOX: 35,
-        ParagraphStyle.CHECKBOX_CHECKED: 35,
+        ParagraphStyle.PLAIN: 70.0,
+        ParagraphStyle.HEADING: 150.0,
+        ParagraphStyle.BOLD: 70.0,
+        ParagraphStyle.BULLET: 35.0,
+        ParagraphStyle.BULLET2: 35.0,
+        ParagraphStyle.CHECKBOX: 35.0,
+        ParagraphStyle.CHECKBOX_CHECKED: 35.0,
     }
     font_sizes = {
-        ParagraphStyle.HEADING: 14 * _PT_TO_SCREEN,
-        ParagraphStyle.BOLD: 8 * _PT_TO_SCREEN,
+        ParagraphStyle.HEADING: 60.0,
+        ParagraphStyle.BOLD: 34.0,
     }
-    default_font = 7 * _PT_TO_SCREEN
 
     try:
         doc = TextDocument.from_scene_item(text_item)
     except Exception:
-        return []
+        return [], []
 
     pos_x = float(getattr(text_item, "pos_x", 0.0) or 0.0)
     pos_y = float(getattr(text_item, "pos_y", 0.0) or 0.0)
+    box_width = float(getattr(text_item, "width", 0.0) or 0.0)
+
+    # Scale the reference metrics to the page's real height so text on devices
+    # that normalize to a different coordinate space (e.g. reMarkable Move)
+    # stays proportional. Identity for the standard 1404x1872 page.
+    _, paper_h = _v6_paper_size(blocks)
+    scale = paper_h / _TEXT_REF_PAGE_HEIGHT if paper_h else 1.0
 
     elements: list = []
-    y_offset = _TEXT_TOP_Y
+    coords: list = []
+    y_offset = _TEXT_TOP_Y * scale
     for para in doc.contents:
         style = para.style.value if getattr(para, "style", None) is not None else None
-        y_offset += line_heights.get(style, 70)
+        line_height = line_heights.get(style, _TEXT_DEFAULT_LINE_HEIGHT) * scale
+        size = font_sizes.get(style, _TEXT_DEFAULT_FONT_SIZE) * scale
         text = str(para).strip()
         if not text:
+            # A blank paragraph still consumes a line (e.g. spacing under a title).
+            y_offset += line_height
             continue
-        size = font_sizes.get(style, default_font)
         family = "serif" if style == ParagraphStyle.HEADING else "sans-serif"
         weight = (
             ' font-weight="bold"' if style in (ParagraphStyle.BOLD, ParagraphStyle.HEADING) else ""
         )
-        elements.append(
-            f'<text x="{pos_x:.1f}" y="{pos_y + y_offset:.1f}" '
-            f'font-family="{family}" font-size="{size:.1f}"{weight} '
-            f'fill="black" xml:space="preserve">{_xml_escape(text)}</text>'
-        )
-    return elements
+        # Wrap long paragraphs to the text box; each wrapped line takes a line,
+        # with continuation lines spaced tighter than a paragraph break.
+        for idx, line in enumerate(_wrap_text(text, box_width, size * _TEXT_CHAR_ADVANCE)):
+            y_offset += line_height if idx == 0 else line_height * _TEXT_WRAP_LINE_RATIO
+            baseline = pos_y + y_offset
+            elements.append(
+                f'<text x="{pos_x:.1f}" y="{baseline:.1f}" '
+                f'font-family="{family}" font-size="{size:.1f}"{weight} '
+                f'fill="black" xml:space="preserve">{_xml_escape(line)}</text>'
+            )
+            # Estimate the line's extent for crop sizing, capped at the box width.
+            est_width = len(line) * size * _TEXT_CHAR_ADVANCE
+            if box_width > 0:
+                est_width = min(est_width, box_width)
+            coords.append((pos_x, baseline - size))
+            coords.append((pos_x + est_width, baseline + size * 0.3))
+    return elements, coords
 
 
 def _render_rm_v6_to_svg(rm_file_path: Path) -> Optional[str]:
@@ -674,7 +742,10 @@ def _render_rm_v6_to_svg(rm_file_path: Path) -> Optional[str]:
         return None
     try:
         paths, all_coords = _v6_paths_from_blocks(blocks)
-        return _svg_from_paths(paths, all_coords)
+        text_elements, text_coords = _v6_text_elements_with_bounds(blocks)
+        # Typed text is drawn under strokes (handwriting layers on top), and its
+        # extent is folded into the crop so a text-only page still renders.
+        return _svg_from_paths(text_elements + paths, all_coords + text_coords)
     except Exception:
         return None
 
diff --git a/test_server.py b/test_server.py
@@ -3877,6 +3877,143 @@ def test_typed_text_rasterizes_to_visible_pixels(self):
         finally:
             rm_path.unlink(missing_ok=True)
 
+    def test_typed_text_in_cropped_read_only_render(self):
+        """remarkable_image's content-cropped render also draws typed text."""
+        from remarkable_mcp import notebooks as nb
+        from remarkable_mcp.extract import _render_rm_v6_to_svg
+
+        with tempfile.NamedTemporaryFile(suffix=".rm", delete=False) as rm_tmp:
+            # A text-only page has no strokes; the cropped render must still
+            # produce output (it previously returned None with no ink).
+            rm_tmp.write(nb.page_rm_bytes("Hello world\nSecond line"))
+            rm_path = Path(rm_tmp.name)
+        try:
+            svg = _render_rm_v6_to_svg(rm_path)
+            assert svg is not None
+            assert "<text " in svg
+            assert "Hello world" in svg
+        finally:
+            rm_path.unlink(missing_ok=True)
+
+    def test_typed_text_png_read_only_path_has_dark_pixels(self):
+        import io as _io
+
+        from PIL import Image
+
+        from remarkable_mcp import notebooks as nb
+        from remarkable_mcp.extract import render_rm_file_to_png
+
+        with tempfile.NamedTemporaryFile(suffix=".rm", delete=False) as rm_tmp:
+            rm_tmp.write(nb.page_rm_bytes("Hello world"))
+            rm_path = Path(rm_tmp.name)
+        try:
+            png = render_rm_file_to_png(rm_path, background_color="#FFFFFF")
+            assert png is not None
+            im = Image.open(_io.BytesIO(png)).convert("L")
+            assert sum(im.histogram()[:128]) > 0
+        finally:
+            rm_path.unlink(missing_ok=True)
+
+    def test_wrap_text_helper(self):
+        from remarkable_mcp.extract import _wrap_text
+
+        # No wrapping when the text fits or no width/advance is known.
+        assert _wrap_text("short line", 936, 15) == ["short line"]
+        assert _wrap_text("anything at all", 0, 15) == ["anything at all"]
+        # A long line wraps into multiple pieces, each within the width budget.
+        long = " ".join(["word"] * 60)  # 60 words -> well past a 936-unit box
+        lines = _wrap_text(long, 936, 15)
+        assert len(lines) > 1
+        for line in lines:
+            assert len(line) * 15 <= 936
+        # Round-trips the words (wrapping only changes whitespace).
+        assert " ".join(lines).split() == long.split()
+        # A single over-long word is kept on its own line rather than split.
+        assert _wrap_text("supercalifragilistic", 50, 15) == ["supercalifragilistic"]
+
+    def test_long_paragraph_wraps_into_multiple_lines(self):
+        from remarkable_mcp import notebooks as nb
+        from remarkable_mcp.extract import _v6_blocks, _v6_text_svg_elements
+
+        long_para = (
+            "The smallest frog is under 8mm long; the largest, the Goliath "
+            "frog, can reach 32cm and is genuinely enormous for an amphibian."
+        )
+        with tempfile.NamedTemporaryFile(suffix=".rm", delete=False) as rm_tmp:
+            rm_tmp.write(nb.page_rm_bytes(long_para))
+            rm_path = Path(rm_tmp.name)
+        try:
+            elements = _v6_text_svg_elements(_v6_blocks(rm_path))
+            # One paragraph wider than the text box must emit more than one line.
+            assert len(elements) > 1
+        finally:
+            rm_path.unlink(missing_ok=True)
+
+    def test_typed_text_baseline_matches_device_offset(self):
+        """First line sits where the device draws it (calibrated, not the old
+        rmc offset that rendered text ~50 units too high)."""
+        import re
+
+        from remarkable_mcp import notebooks as nb
+        from remarkable_mcp.extract import _v6_blocks, _v6_text_svg_elements
+
+        with tempfile.NamedTemporaryFile(suffix=".rm", delete=False) as rm_tmp:
+            rm_tmp.write(nb.page_rm_bytes("Frog Facts"))
+            rm_path = Path(rm_tmp.name)
+        try:
+            elements = _v6_text_svg_elements(_v6_blocks(rm_path))
+            y = float(re.search(r'y="([-\d.]+)"', elements[0]).group(1))
+            # pos_y(234) + TOP(-39) + line_height(70) == 265 for a 1404x1872 page;
+            # comfortably below the old value of 216.
+            assert 255 <= y <= 275
+        finally:
+            rm_path.unlink(missing_ok=True)
+
+    def test_typed_text_metrics_scale_with_page_height(self):
+        """Layout metrics scale linearly with the page's normalized height so
+        typed text stays proportional on non-1872 geometries (e.g. reMarkable
+        Move/classic). run_smoke only asserts render PASS/FAIL, not pixel
+        layout, so this is the guard against a scaling regression."""
+        import re
+        from unittest.mock import patch
+
+        from remarkable_mcp import extract
+        from remarkable_mcp import notebooks as nb
+        from remarkable_mcp.extract import _v6_blocks, _v6_text_svg_elements
+
+        with tempfile.NamedTemporaryFile(suffix=".rm", delete=False) as rm_tmp:
+            # Two paragraphs so the line-to-line gap isolates the scaled
+            # line_height independent of the (unscaled) text-box position.
+            rm_tmp.write(nb.page_rm_bytes("First line\nSecond line"))
+            rm_path = Path(rm_tmp.name)
+        try:
+            blocks = _v6_blocks(rm_path)
+            width, _ = extract._v6_paper_size(blocks)
+
+            def metrics_at(page_h):
+                with patch.object(extract, "_v6_paper_size", return_value=(width, page_h)):
+                    els = _v6_text_svg_elements(blocks)
+                y0 = float(re.search(r'y="([-\d.]+)"', els[0]).group(1))
+                y1 = float(re.search(r'y="([-\d.]+)"', els[1]).group(1))
+                size = float(re.search(r'font-size="([-\d.]+)"', els[0]).group(1))
+                return y1 - y0, size
+
+            # Reference 1872-tall page: full-size metrics.
+            gap_ref, size_ref = metrics_at(extract._TEXT_REF_PAGE_HEIGHT)
+            assert gap_ref == pytest.approx(extract._TEXT_DEFAULT_LINE_HEIGHT, abs=0.5)
+            assert size_ref == pytest.approx(extract._TEXT_DEFAULT_FONT_SIZE, abs=0.5)
+
+            # Half / double height -> metrics scale linearly.
+            gap_half, size_half = metrics_at(extract._TEXT_REF_PAGE_HEIGHT / 2)
+            assert gap_half == pytest.approx(gap_ref / 2, abs=0.5)
+            assert size_half == pytest.approx(size_ref / 2, abs=0.5)
+
+            gap_dbl, size_dbl = metrics_at(extract._TEXT_REF_PAGE_HEIGHT * 2)
+            assert gap_dbl == pytest.approx(gap_ref * 2, abs=0.5)
+            assert size_dbl == pytest.approx(size_ref * 2, abs=0.5)
+        finally:
+            rm_path.unlink(missing_ok=True)
+
 
 class TestRenderCanvasPage:
     """Test the read-only canvas page renderer."""
