--- name: pretext description: >- Help developers use @chenglou/pretext 1.0+, a TypeScript library that measures and lays out multiline text without DOM reflow. Use for pretext, @chenglou/pretext, /rich-inline, layoutNextLine, layoutNextLineRange, upgrading pretext from 0.0.x to 1.0, or text height, line count, shrink-wrap, auto-fit font size, line clamp with ellipsis, text around obstacles, and inline chips, mentions or images computed in JS. Also for its errors: "font must be a font string Canvas takes", "Text measurement requires OffscreenCanvas", or a layoutNextLine loop that never ends. Do NOT use for CSS-only layout, generic typography, or CSS shrink-to-fit questions. compatibility: Written for @chenglou/pretext 1.0.0 or later. Pre-1.0 projects need references/migration.md first. license: MIT metadata: author: Yaniv Golan version: "0.2.2" --- # Pretext Integration Guide You are helping a developer use **@chenglou/pretext**, a TypeScript library by Cheng Lou that predicts the browser's line breaks and heights from canvas measurements, using ports of each browser's line breaker. `prepare()` segments the text and measures it once with `CanvasRenderingContext2D.measureText`; `layout()` is then arithmetic at any width, with no DOM reads. It is ESM: `@chenglou/pretext` is the core, and `@chenglou/pretext/rich-inline` handles mixed-font inline text. ## Check the Version First Read the project's `package.json` (or run `npm ls @chenglou/pretext`) before writing any code. This skill covers 1.0.0 and later. Below 1.0.0, read [migration.md](references/migration.md) before writing code: a caret range on a 0.0.x version never reaches 1.0 by itself, and several signatures changed. Don't write signatures from memory; take them from the references. ## When Pretext Is the Right Tool - **Know text height before rendering**: virtual lists, masonry, cards, accordions. - **Auto-fit font size** to N lines, which CSS can't do. - **Truncate to N lines with an ellipsis** when you need the clamped strings, as for Canvas or SVG. - **Flow text around obstacles**: a different width for each line. - **Lines and widths for painting with `fillText`** in canvas, SVG or WebGL. Paint each line's text through `paintableText`, a helper recipe in patterns-flow.md (not a library export), so soft-hyphen breaks draw the hyphen that was measured. - **Rich inline text**: mentions, chips, code spans and inline images, via `/rich-inline`. - **Shrink-wrap**: the tightest width for a chat bubble or label. ## When NOT to Use Pretext - **CSS already handles it**: don't reimplement floats, flex or plain wrapping. - **Content is HTML, not text**: tables, code blocks and nested elements need DOM measurement. - **Virtualizers with mixed content** (images of unknown size, embeds, HTML): these need DOM measuring. When all content is Pretext-measured, Pretext heights work in a virtualizer such as TanStack Virtual with no `measureElement` loop. - **Accordion content with HTML structure**: measure it off-screen in the DOM. ## Quick Start ```bash npm install @chenglou/pretext ``` ```js import { prepare, layout } from '@chenglou/pretext'; const prepared = prepare('Hello world', '16px Inter'); // text first, then a canvas font const result = layout(prepared, 400, 24); // maxWidth 400px, lineHeight 24px // → { lineCount: number, height: number } const narrow = layout(prepared, 120, 24); // on resize, lay out again; never prepare again ``` ## Critical Gotchas Read these before writing any Pretext code. ### 1. lineHeight Must Be in Absolute Pixels `layout()` takes line height in CSS px, not a multiplier. Passing `1.5` gives a plausible `lineCount` and a tiny `height`, with no error. ```js const prepared = prepare(text, '14px Inter'); const lineHeightPx = 14 * 1.5; // CSS: font-size 14px, line-height 1.5 layout(prepared, 500, lineHeightPx); // not layout(prepared, 500, 1.5) ``` ### 2. prepare() Takes Text First, and a Bad Font Throws `prepare(text, font)`. Swapped arguments throw a `RangeError`, unless the swapped text happens to be a valid font string, and then the numbers are silently wrong. - `getComputedStyle(el).font` can be an empty string (an unmounted element, or a longhand such as `font-variant-numeric`), which throws. - Which other strings throw varies by browser, such as `'1.5em Arial'` or `'caption'`: see [accuracy.md](references/accuracy.md#fonts). The safe form is a px size and a named family, `'600 16px Inter'`. - `document.fonts.load()` rejects a malformed string with a `SyntaxError` first, so that is the error you see. ### 3. Each Text+Font Pair Needs Its Own prepare() A handle is for one text, font and options. Prepare each string. Pretext caches segment widths per font, so many strings in one font are cheap. ### 4. Load Fonts Before prepare() Before a web font loads, Canvas measures the fallback font. Await `document.fonts.load(font, text)`, which also loads the `unicode-range` parts the text needs, and handle its rejection. If text was prepared before its font arrived, call `clearCache()` and prepare it again. ```js async function prepareLoaded(text, font) { await document.fonts.load(font, text); // rejects for a malformed font string return prepare(text, font); } ``` ### 5. system-ui Is Unreliable On macOS, Canvas resolves `system-ui` and `-apple-system` to a different font from the one the page paints. Use a named font: see [accuracy.md](references/accuracy.md#fonts). ### 6. No Canvas, No Pretext Without a Canvas 2D context or a global `OffscreenCanvas`, `prepare()` throws `Text measurement requires OffscreenCanvas or a DOM canvas context.` Node and server rendering throw; upstream says Bun, jsdom and happy-dom do too. Call it only on the client, or see [patterns-integration.md](references/patterns-integration.md#outside-the-browser) for a shim. `Intl.Segmenter` is needed only for Southeast Asian scripts such as Thai. ### 7. Border in Height Estimates When you add fixed parts to a text height, include `border-width`: a 1px border adds 2px to the box. It is easy to miss and adds up across a list. ### 8. Empty Text Is Zero Lines, but a Textarea Isn't `layout()` of `''` gives 0 lines and a height of 0. That matches the browser, where an empty block is 0 tall, so don't clamp it. A `