SPB Git

Repository Public

layout-engine.md 20.0 KB 200 lines markdown

1<!--2ORIX Docs3File: docs/architecture/layout-engine.md4Description: Paragraph typesetting with Core Text, fonts, inline boxes, the layout cache, table layout, the page renderer and geometry queries.5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->8# Layout engine910`DocLayout` turns a `DocumentModel` into pages and draws them. This document covers typesetting, caching, tables, drawing and the geometry queries the editor uses. The flow of blocks into columns and pages has its own document: [pagination.md](pagination.md). PDF output is in [pdf.md](pdf.md).1112| Part | Code (`Packages/ORIXDocsKit/Sources/`) |13|---|---|14| Font resolution | `DocLayout/Fonts.swift` |15| Paragraph typesetting | `DocLayout/ParagraphLayout.swift` |16| Layout result, cache, table layout types | `DocLayout/DocumentLayout.swift` |17| Flow into pages | `DocLayout/Paginator.swift` |18| Drawing | `DocLayout/PageRenderer.swift` |19| Caret, selection, hit testing | `DocLayout/Geometry.swift` |20| Equations | `DocMath/MathRenderer.swift` |21| Tests | `Tests/DocLayoutTests/PaginationTests.swift` (`TypesettingTests`, `GeometryQueryTests`, `TableLayoutTests`), `PDFTests.swift`, `SmokeTests.swift` |2223## Why Core Text and an own paginator2425The decision and its evidence are in [technology-evaluation.md, section 1](../research/technology-evaluation.md#1-text-layout-and-editing). In short: `NSTextLayoutManager` (TextKit 2) has a single text container and viewport-based layout, so it cannot flow text through a sequence of pages with exact geometry for the whole document; TextKit 1 paginates through multiple containers but offers no footnote placement, repeated table header rows, keep rules or widow/orphan control. `CTTypesetter` returns one line at a time for a width the caller chooses, which is what a paginator needs, and the same drawing code can target the screen, a bitmap or a PDF context. The cost is that everything `NSTextView` gives for free must be written by hand ([text-engine.md](text-engine.md#15-limits)).2627```mermaid28flowchart LR29    M[DocumentModel] --> N[Numbering]30    M --> PG[Paginator]31    N --> PG32    PG -->|"paragraph + environment"| LC[LayoutCache]33    LC -->|miss| PL[ParagraphLayout]34    PL --> FC[FontCache]35    PL --> MR[MathRenderer]36    LC --> PG37    PG --> DL["DocumentLayout: pages of fragments"]38    DL --> PR[PageRenderer]39    DL --> GQ["Geometry queries"]40    PR --> SC["Screen: EditorCanvasView"]41    PR --> BM["Bitmap: thumbnails, previews"]42    PR --> PDF["PDF context: PDFPublisher"]43    GQ --> SC44```4546## Font resolution4748`FontCache.shared.font(family:size:weight:italic:smallCaps:)` returns a `CTFont` and memoises it by those five values (lock-protected).4950* **System designs by name.** `New York`, `SF Pro` (also `SF Pro Display`, `SF Pro Text`, `System`), `SF Pro Rounded` and `SF Mono` are not font files; they map to `NSFontDescriptor.SystemDesign` `.serif`, `.default`, `.rounded`, `.monospaced` on `NSFont.systemFont(ofSize:weight:)`.51* **Weights.** The model's CSS-like weight (100–900; `bold` is 700) maps to an `NSFont.Weight` for system designs (`nsWeight`) and to a `kCTFontWeightTrait` value for other families (`ctWeight`); the bold symbolic trait is requested from 600 up.52* **Italic.** Requested as a symbolic trait. A family that yields a font without the italic trait gets a **synthetic slant** (a copy with the matrix `c = 0.2`). System designs take the italic trait on the descriptor and get no synthetic fallback.53* **Small capitals.** When `smallCaps` is set the font descriptor gets OpenType feature type 37, selector 1 (lowercase small capitals). Nothing is synthesised for fonts that lack the feature.54* **Superscript and subscript** use the same family at 0.66 of the size (`font(for:scale:)`), with a baseline shift of +0.33 or −0.14 of the font size added in `ParagraphLayout`.55* **Missing families.** The list of installed families is read once (`CTFontManagerCopyAvailableFontFamilyNames`, lower-cased). A family that is neither installed nor a system design is recorded in `missingFamilies` and replaced by Times New Roman. `DocumentConverter.preflight(_:format:)` reports the list as a "Missing fonts" warning before a PDF export. The set only grows during the life of the process.56* **No-break space correction.** `noBreakSpaceCorrection(_:)` measures the difference between the advances of U+0020 and U+00A0 in a font. Some fonts (the code comment names Charter) give the no-break space a figure-wide advance, which shows as a visibly wide gap, for example in "Figure 3" or before French punctuation. `ParagraphLayout` adds the difference as kerning (or to the tracking value when the run already uses tracking, because the two do not add up on one character) on every U+00A0 of a run.5758Per-glyph fallback for characters a font does not contain (CJK, emoji, symbols) is left to Core Text; the code sets no cascade list.5960## Building the attributed string6162`ParagraphLayout.init(_:env:)` receives a paragraph and a `ParagraphEnvironment` (style sheet, layout options, width, list label and level, heading number, texts of text-like inline objects, exclusions, math typeface, colour override, language).6364**Invariant: one model character is one display character.** The attributed string has exactly the UTF-16 length of the paragraph (`precondition(text.length == length)`), so a model offset is a Core Text string index and no mapping table exists. To keep it:6566* an inline object stays the single character U+FFFC and gets a `CTRunDelegate` that supplies its width, ascent and descent;67* `allCaps` text is replaced by its uppercase form only when the UTF-16 length is unchanged (so "ß" is left alone rather than becoming "SS");68* tracked deletions hidden by `LayoutOptions.markup == .none` keep their characters but each gets a zero-size delegate, so they take no room (`TypesettingTests.trackedDeletionsAreHiddenWithoutMarkup`);69* the only exception is a hyphenated line (below).7071Each run carries a `RunInfo` object under the private attribute key `orix.run` (resolved formatting, colour, revision, comment flag, box, underline and strikethrough). Underline and strikethrough are not Core Text attributes; the renderer draws them. With markup shown, an inserted run is coloured per author (`ReviewColors.color(for:)`, a hash into six colours) and underlined, a deleted run is coloured and struck through.7273### Inline boxes7475`InlineBox` holds the metrics and what to draw:7677| Content | Source | Notes |78|---|---|---|79| `.image`, `.shape` | Inline images and shapes | Width and height from the object (bounding box of a rotated image); ascent = height, descent 0. |80| `.equation(MathLayout)` | `.equation` | Typeset by `MathRenderer.layout` at 1.1 × the run's font size. |81| `.text(CTLine, rise:)` | Note marks, citations, cross-references, fields | The displayed string comes from `env.boxTexts` in order of appearance; it is typeset as its own `CTLine` and behaves as one unbreakable box. Note marks are superscript. |82| `.dropCap` | Drop capital | See below. |83| `.anchor` | Bookmarks, anchors of floating objects, hidden deleted text | Zero size. |8485Floating images and shapes are not in the line: the paragraph records a `FloatBox` (rectangle relative to the paragraph's top-left corner, from alignment and offsets) and leaves a zero-size anchor at the object's position.8687## Line breaking8889For each line the builder asks `extent(at:height:first:)` for the usable horizontal extent at the current y, then `CTTypesetterSuggestLineBreakWithOffset` for a break in that width, then `CTTypesetterCreateLineWithOffset`.9091* **Indents.** Left and right indents, and a first-line indent that may be negative (hanging). A list label or heading number changes the first-line start (below).92* **Exclusions.** An `Exclusion` narrows lines between two y values from the left and/or right. They come from floats of earlier paragraphs (passed in by the paginator), from the paragraph's own floats (`.square` narrows on the side the float is on when its centre is in the outer 40 % of the column, otherwise the lines skip below it; `.topAndBottom` always skips; `.behindText` and `.inFrontOfText` exclude nothing), and from a drop cap. When fewer than 40 pt would remain, the line skips to the bottom of the exclusion. Test: `floatingObjectsNarrowTheLinesBesideThem`.93* **Drop caps.** With `dropCapLines ≥ 2` (capped at 6), on a paragraph that is not a list item and starts with a letter in an untracked text run, the first composed character gets a delegate box as wide as the enlarged glyph and an exclusion pushes the following lines aside. Test: `dropCapNarrowsTheFollowingLines`.94* **Justification.** `CTLineCreateJustifiedLine` with factor 1.0, for every line except the last and those ending in a forced break. Test: `justifiedLinesFillTheMeasureExceptTheLast`.95* **Right-to-left.** `rightToLeft` sets the base writing direction; a left-aligned right-to-left paragraph is aligned right. Test: `rightToLeftParagraphsAlignRight`.96* **Empty paragraphs** and a paragraph ending in U+2028 get a zero-width line so the caret has a place.9798### Hyphenation99100Enabled per paragraph (`hyphenate`, off by default) when `CFStringIsHyphenationAvailableForLocale` holds for the language of the last run, else of the document. After Core Text suggests a break, the builder looks at the word that would start the next line: if the line ends with a space, contains no tab, and the word has at least five letters, it asks `CFStringGetHyphenationLocationBeforeIndex` for break points from the end of the word backwards and takes the first one for which the line plus a hyphen fits.101102A hyphenated line is **typeset separately**: a new `CTLine` is created from the substring plus "-". Its string indexes start at 0, so `LayoutLine.indexBase` holds the offset to add to obtain model offsets (`xPosition(for:)` and `offset(atX:)` apply it). Test: `hyphenationBreaksLongWordsOnlyWhenEnabled` (lines still cover every character exactly once).103104### Tabs and leaders105106Tab stops (left, centre, right) become `CTTextTab`s measured from the column's left edge, with a default interval of 36 pt; a decimal tab is a right tab whose column terminators are "." and ",". Header and footer paragraphs without explicit tabs get a centre tab at half the width and a right tab at the full width. Leaders are not part of the line: `PageRenderer.drawLeaders` fills the gap of each tab character with dots, dashes or a rule.107108### Line height109110For each line, `natural` = ascent + descent + leading from `CTLineGetTypographicBounds` (the paragraph font's metrics when the line is empty), and `fontLine` is the same sum for the font of the last run:111112| `LineSpacing` | Line height |113|---|---|114| `.multiple(k)` | `natural + (k − 1) × min(natural, fontLine)` — a tall inline object does not multiply the extra spacing |115| `.exact(v)` | `v` |116| `.atLeast(v)` | `max(v, natural)` |117118The baseline is placed so that ascent + descent is centred in the line box. Test: `lineSpacingModes`.119120### List labels and heading numbers121122Labels are never in the text; `Numbering` computes them. A list label is a separate `CTLine` (`LabelBox`) drawn hanging at `indent − hanging` of the `ListLevel`, and the text starts at the level's indent (or after the label if it is wider). A heading number is drawn at the first-line start and the text follows after a gap of 0.55 × the font size. Labels use the size and colour of the first run and the paragraph style's weight. Test: `listLabelsHangInTheIndent`.123124## The layout cache125126`LayoutCache` (`DocumentLayout.swift`) avoids typesetting a paragraph again when nothing it depends on changed.127128* **Key.** Entries are stored per paragraph id, up to three per id (a paragraph can legitimately have several layouts: different column widths, with and without neighbouring floats). An entry matches when the `Paragraph` value is equal and width, list label, list level, heading number, box texts, exclusions, header/footer flag, colour override, layout options and math typeface are all equal.129* **Style sheet.** `beginPass(styles:)` empties the cache when the `StyleSheet` differs from the one of the previous pass: any style edit is a full relayout.130* **Generations.** Each pagination pass increments a generation and stamps the entries it uses; every eighth generation `endPass()` drops entries not used in the last eight, which removes layouts of deleted paragraphs.131* **Headers and footers.** The same header paragraph appears on every page with different field values (page number, running head). With three slots per id it would be typeset again on almost every page of every pass, so these layouts live in a second dictionary keyed by paragraph id, box texts and width: one layout per distinct content.132* `hits` and `misses` are public counters. `removeAll()` is called when a document is reloaded.133134The cache has no lock: one cache serves one document on one thread at a time. Table layouts (`TableLayout`) are recomputed on every pass; only their cell paragraphs are cached.135136## Tables137138`Pass.tableLayout(_:width:)` produces a `TableLayout`:139140* **Scaling.** A table wider than its column (by more than 0.5 pt) has all its column widths scaled by the same factor and is reported in `DocumentLayout.overflowingTableIDs`. Test: `aTableWiderThanTheColumnIsScaledAndReported`.141* **Cells.** A cell covers `colSpan` grid columns; its paragraphs are typeset at the cell width minus the style's padding, in the header text colour for header rows of a style that defines one.142* **Row heights.** The tallest unmerged cell content plus padding, at least `minHeight`, never under 14 pt.143* **Vertical merges.** A `restart` cell's `rowSpan` counts the `continue` cells below it in the same grid column; if its content is taller than the rows it covers, the last of those rows grows. Test: `mergedCellsCoverTheirGrid`.144* `headerRows` is the number of leading rows with `isHeader`.145146Splitting across pages is done by the paginator ([pagination.md](pagination.md#tables)).147148## Equations149150`MathRenderer.layout(latex:fontSize:display:color:typeface:)` typesets LaTeX with SwiftMath and caches the result (up to 4,000 entries, keyed by typeface, size, style, colour and source). The `MathLayout` wraps the `NSImage` returned by SwiftMath's `MathImage.asImage()`, which on macOS is created with a drawing handler, so drawing it replays glyph drawing into the destination context. The math typeface is chosen from the document's default font family (`MathTypeface.matching(textFamily:)`). A formula that does not parse is shown as its source in red monospaced text and carries an `error` (`invalidEquationShowsItsSourceInsteadOfVanishing`). Drawing is serialised by a lock.151152## The page renderer153154`PageRenderer.draw(page:in:)` draws into a context whose origin is the page's top-left corner with y pointing down. The same code serves the canvas, thumbnails and previews (`PDFPublisher.bitmap`), printing and PDF.155156Drawing order:1571581. page background (`PageSetup.background`), else white paper when `drawsPaper` is on (off for PDF);1592. watermark (not on blank parity pages), page border;1603. floats with `.behindText`;1614. tables: cell shading (cell, header or banded rows), then borders — cell overrides, else the table style's outer and inner lines; the `Academic` style adds its three rules;1625. text fragments, in placement order (below);1636. the other floats;1647. footnote separator rules, column rules;1658. break markers, unless `forPrint`.166167For a text fragment: paragraph shading and borders span the fragment; the list label or heading number is drawn with the first line; then each line is drawn **run by run** (`drawLine`): highlight or comment tint behind the run, the link hook, the inline box if any, the glyphs with `CTRunDraw`, then underline and strikethrough from the font's metrics (trailing white space excluded). Leaders are drawn last.168169Screen-only decorations, all skipped when `LayoutOptions.forPrint` is set: the change bar in the margin beside lines that carry a tracked change, the comment tint, break markers (a dashed rule with a label supplied through `MarkerLabels`, or a rule alone for continuous section breaks). Focus mode dims every body paragraph but one (`focusParagraphID`).170171`RenderHooks` lets a client observe drawing without the renderer knowing about PDF: `link(rect, target)` for every run with a link, and `begin(role)` / `end()` around text fragments (paragraph, heading level, list item, note), figures (images, shapes, equations, with alternative text) and tables. [pdf.md](pdf.md#structure-tags) describes how they are used.172173Images are decoded once per asset (`ImageStore`, an `NSCache` limited to 512 MB of decoded pixels); a PDF asset is drawn as vector content (its first page); crop and rotation are applied at draw time; a missing or unreadable asset draws a labelled placeholder.174175## Geometry queries176177`Geometry.swift` extends `DocumentLayout`; an index from (story, path) to fragments (`fragments(story:path:)`) backs all of them.178179| Query | Result |180|---|---|181| `locate(story:position:upstream:preferredPage:)` | The page, fragment and line that display a position. `upstream` prefers the previous line at a line boundary; `preferredPage` selects the page for headers and footers, which repeat. |182| `caret(…)` | A 1.5 pt wide rectangle of the line's height. On an atomic block: the marker's or the generated block's leading edge. |183| `selectionRects(story:start:end:blocks:preferredPage:)` | One rectangle per line covered; a small extension where the selection continues past a paragraph end; whole rectangles for break markers and generated blocks. Test: `selectionRectanglesCoverEveryLineOfTheRange`. |184| `cellRect(block:row:cell:)`, `columnBoundary(page:point:tolerance:)`, `floatHit(page:point:)` | Table cell rectangle, column edge under the pointer, topmost floating object. |185| `hitTest(page:point:restrictTo:)` | Markers first; inside a table the cell under the point; otherwise the nearest fragment (vertical distance weighted four times the horizontal one), its line at the point's y, and `LayoutLine.offset(atX:)`. Reports upstream affinity at the end of a wrapped line and `onAtomicBlock` for generated content. Tests: `hitTestRoundTripsCaretPositions`, `hitTestingFindsTheCellUnderThePoint`. |186| `lineRange(…)` | Model range of the visual line (Home/End), excluding a trailing forced break. Test: `homeAndEndUseTheVisualLine`. |187| `verticalMove(story:from:goalX:down:…)` | The position on the adjacent visual line nearest to `goalX`, across fragments and pages. In a table: first within the cell, then to the cell of the next or previous row nearest to `goalX`, then out of the table; entering a table picks the cell under the caret. Test: `verticalMovementKeepsTheColumnAndCrossesPages`. |188189## Limits190191* **Inline boxes are unbreakable.** A citation, cross-reference, field value or note mark is one box; a long citation cannot wrap, and an inline image or equation wider than the line overflows it.192* **First-fit line breaking.** Breaks are those suggested by Core Text line by line; there is no paragraph-level optimisation. Hyphenation only considers the first word of the next line, only after a space, and uses one language per paragraph.193* **Leaders**: one leader style per paragraph — the first tab stop that has a leader decides for all tabs (`drawLeaders`) — and none on hyphenated lines.194* **Small capitals and bold** depend on what the font offers; only italic is synthesised.195* **Bidirectional selections** are approximated ([text-engine.md](text-engine.md#15-limits)).196* **Rows do not split across pages**, and nothing keeps the rows of a vertical merge together ([pagination.md](pagination.md#limits)).197* **Paragraph continuation beside a float**: see [pagination.md](pagination.md#floats).198* **Concurrency.** `FontCache` and `MathRenderer` are lock-protected and `ImageStore` is safe to share, but `LayoutCache` is not thread-safe. `Fonts.swift` reads the installed-family list once because, as its comment records, asking the font registry per family from many threads is slow and can stall. For the same reason the layout tests are run serially (`swift test --no-parallel`, see [testing.md](../development/testing.md)); batch processing bounds its concurrency (`WorkflowRunner.runBatch(_:inputs:maxConcurrent:progress:)` in `DocAutomation`, four files at a time by default).199* Measured costs are in [performance.md](../development/performance.md).200
Files main
Menu

Theme