Skip to content

DOCX: split blocks across pages and load fonts; canvas is not the fix #30

Open

Description

@pierreneter

Summary

The DOCX view renders with DOM and leaves text layout to the browser. Two limits follow from that, and both tend to be answered with "render to canvas, like Google Docs":

  1. A block is never split across pages.
  2. Where a line breaks depends on the browser and on the fonts installed.

Decision: canvas is not the fix. Canvas is where the pixels go. Both problems are about who decides where a line and a page end. We keep DOM rendering, fix pagination and font loading, and do not write our own line breaker unless page numbers have to match exactly (see "Not planned").

What happens today

  • paginate() in src/react/docx/paginate.ts places whole blocks. A paragraph or table that does not fit what is left of a page moves to the next page whole and leaves a gap behind it.
  • A block taller than a page stretches its page: DocxView.tsx sizes a page as max(page height, margins + used). A long table becomes one very tall page.
  • w:tblHeader is parsed (row.header), but the view does not repeat header rows. keepNext is parsed, but pagination ignores it. keepLines and widowControl are not read.
  • cssFont() in src/core/fonts.ts names metric-compatible fallbacks (Carlito, Caladea, Liberation, ...) in the font stack, but nothing loads them. On a machine with neither Calibri nor Carlito the text falls back to the generic family, and lines and pages break in other places.
  • With the same fonts, Chrome, Safari and Firefox can still break a line differently when it nearly fills its width.

Why not canvas

  • Moving the painting to canvas changes none of the above. To draw text on a canvas we would first need our own line layout, and that layout is the fix. The same layout can emit DOM lines.
  • Google Docs did its own line layout on top of DOM from 2010. The move to canvas in 2021 was a later, separate step.
  • Canvas costs what DOM gives for free: selection, IME, accessibility, find in page, copy and paste, printing, font fallback.

Plan

  1. Tables split between rows, and header rows repeat on each page.
  2. Paragraphs split between lines. The measure pass reads the line boxes (Range.getClientRects()), pagination picks the last line that fits, and the paragraph is rendered as two fragments: the second without first-line indent and space before, the first with its last line still justified.
  3. Keep rules when choosing a break: widow and orphan control, keepNext, keepLines.
  4. Fonts. The host supplies font URLs, the view loads them with FontFace and measures only once they are ready. This adds no runtime dependency: fonts are assets, and the fallbacks already named are under the OFL.

Open point for 2: editing. One paragraph becomes two DOM nodes on two pages, so caret, selection and data-pa offsets have to map across the fragments.

Not planned: our own line breaking

Measuring words ourselves and emitting one element per line would take the choice of line breaks away from the browser. It means reimplementing tabs, justification, bidi, CJK breaking, hyphenation, floats and inline objects, and editing on top of per-line DOM.

Do this only if a use case needs page numbers to match exactly, for example documents that are cited by page. Until one does, it is out of scope.

Two limits remain even then:

  • The reference is Word, not another browser. Our own layout would still differ from Word in some documents.
  • Exact agreement between browsers also needs our own text shaping, which means shipping a shaping engine. That goes against the zero-dependency rule.

Activity

  1. pierreneter commented on Nov 18, 2026

    @pierreneter
    MemberAuthor

    Amendment: exact pagination becomes an option, on by default

    This replaces the section "Not planned: our own line breaking" above. Our own line breaking is now planned, as the default layout mode. The rest of the issue stands, including the decision on canvas: the exact mode computes the lines itself and still emits DOM, one element per line.

    The option

    Proposed name: pageLayout: 'exact' | 'browser', default 'exact'.

    Mode Who breaks lines and pages Result
    'exact' (default) the library the same line and page breaks in every browser and OS, for the same file and fonts
    'browser' the browser, as today breaks can differ between browsers and between machines

    What 'exact' needs

    • Text widths and line heights come from the font file's own tables, read in the worker, instead of being measured by the browser. This adds no dependency.
    • So each font has to be available as a file: embedded in the document, or supplied by the host (plan item 4).
    • Proposed fallback: a run whose font is not available as a file is measured by the browser, and the document is reported as not exact, so it never looks exact when it is not.

    Plan items 1 to 3 apply to both modes. In 'exact', item 2 needs no line-box measuring, since the lines are already known.

    What 'exact' does not promise

    • Word's page numbers. They are the target, but Word's layout is not specified, and some documents will differ.
    • Scripts that need shaping (Arabic, Indic). Their widths still come from the browser, because a shaping engine stays excluded by the zero-dependency rule.

    Order of work

    1. Plan items 1 to 4 in the current layout. Both modes need them, and the current layout becomes 'browser'.
    2. 'exact': line breaking with tabs, justification, bidi, CJK breaking, hyphenation, floats and inline objects, then editing on top of per-line DOM.
  2. mkroemer commented on Nov 18, 2026

    @mkroemer
    Contributor

    #31 adds a bounded physical scroll range mapped to logical page positions, following the spreadsheet viewer’s approach. Caret, find, outline and comment navigation use the same mapping.

    It seems useful to keep this scrolling layer shared between the proposed exact and browser modes, independently of how lines and pages are calculated.

    The regression fixture in e2e/plain.spec.ts reaches, finds, edits and saves text on the final page of a document beyond the browser’s scroll-height limit. It could also help test the new pagination modes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions