Readium colGap CSS var breaks pagination scroll math
Adding a user-facing column-gap setting to a paginated EPUB reader built on the Readium navigator library
The --RS__colGap CSS variable that Readium exposes for column-gap is honored by CSS multi-column layout but NOT subtracted from Readium internal pagination scroll-offset math (the JS computes offsets as viewport_width / column_count per page, ignoring the gap). Setting it to any non-zero value introduces a per-page error of gap / column_count pixels that accumulates as the reader scrolls, producing visible artifacts: a partial extra column appearing on one edge, columns drifting past the viewport boundary, and text getting clipped at misaligned column boundaries. The bug is in the vendored @readium/navigator package (see node_modules/@readium/navigator/dist/index.js around the colGap-applying section) — not patchable at the consumer level without forking Readium. The principled workaround is to use --RS__pageGutter instead, which adds padding-inline to the body without changing the column-count math, giving similar visual breathing room (wider book-like margins) without breaking pagination.
If you are tempted to expose --RS__colGap as a user-tunable preference in a Readium-based reader, do not — it will silently break pagination after a few pages of scroll. Use --RS__pageGutter for any user-facing margin/spacing slider on paginated content.