Settings

Standard CSS carries most of a document’s appearance. What it can’t express — how content flows (pages vs scroll), where the app’s panes sit, what page furniture prints, what the editor does — rides the same stylesheet as namespaced custom properties. They cascade, condition, and layer exactly like every other declaration (put one inside @media print, inside a guard — it just works), and a bare browser simply ignores them.

Declare them on the document surface (main), or under any condition:

main { --spub-flow: continuous; --spub-outline: right; }
@media print { main { --spub-flow: paged; --spub-numbering: on; --spub-numbering-format: "{n}."; } }
html[data-spub-intent~="edit"] main { --spub-editor-current-line: highlight; }

Renderers resolve them through the engine’s cascade (resolveSettings) — the same result the browser would compute — and read them as one typed Settings object. Unknown values degrade to the default (warn, never fail).

The vocabulary

Pagination and flow — whether one-column content scrolls continuously or is split into pages. Multiple columns use a viewport-height horizontal flow:

The workspace is a CSS grid whose content and visible in-layout Outline occupy separate, gapless tracks. In multi-column reading the canvas track stretches to the workspace edges, resolving outer layout justification to stretch for that flow. --spub-canvas-margin becomes padding inside the scrolling canvas, so the initial and snapped views retain their inset while text travels to the viewport edge (or beneath an overlay Outline) during horizontal scrolling. --spub-layout-justify-content distributes the outer canvas and Outline tracks; non-stretch modes pack those tracks to their requested widths before distributing the remaining workspace. Column width, count, gap, and justification apply inside the content track in both continuous and paged reading. auto chooses the greatest whole number of preferred-width columns (up to the supported maximum) that fit inside the content track, including their gaps; the packed column block is then placed by --spub-justify-content. With multiple columns, space-between, space-around, and space-evenly distribute the content track’s remaining inline space between and, where applicable, around the columns; stretch expands the columns across that track. Once auto is resolved or an explicit count is selected, that count is authoritative; columns may shrink below their preferred width rather than collapsing to fewer columns. auto for snap resolves to page snapping for paged one-column and multi-column flows, and to none for continuous one-column flow.

Pagination is resolved after the column count. With one resolved column, paged (Always) uses vertical pages and continuous (Multi column only) leaves the document continuous. With two or more resolved columns, both values use native CSS multi-column fragmentation in a viewport-height container: the browser fills each column from top to bottom and continues the document horizontally. Scrolling snaps to each viewport-sized group of columns by default. CSS columns are anonymous boxes, so the renderer derives only the horizontal group step from the CSS container width and gap; it never measures text, lines, or content height. This avoids measured line slices and prevents content from extending below the viewport or being clipped at an inferred page boundary. The used horizontal column gap is never smaller than the padded inset, which keeps neighboring fragments outside that inset at snap points. The resolved count is recomputed when workspace or Outline geometry changes. The reading measure, padding, and margins are real CSS on main (max-width, padding, margin-inline).

Navbar — the outline / index navigator beside the document:

Source — the raw document source beside its continuous reading preview:

Source is a workspace scope, not a modal or a second document representation. The canvas renders the parsed work exactly as Read does, but resolves to one continuous scroll column while the source track shows the original text. Activating Source replaces any visible Outline and resolves the outer workspace distribution to stretch. The source track reaches both the workspace edge and the canvas seam; padding belongs inside the panel. Syntax coloring is a viewer aid and does not alter source bytes. HTML-aware coloring recognizes embedded JSON and CSS regions as their respective languages.

Progress — the reading-progress indicators:

Page furniture — templates take {n} {pages} {title} {author} {division}:

Hiding a whole section is real CSS: section.notes { display: none; }.

Editor behaviour — ignored by read-only renderers:

Graceful degradation

A renderer that can’t page falls back to continuous flow and honours the rest. Settings a surface has no use for (editor knobs in a reader, panes in an EPUB) are simply unread. The machine-readable catalog — names, types, enums, defaults — is SETTINGS in @script-pub/format (sheet/settings.ts), the single source for the format editor’s forms and validation’s warnings.