pretext

name	pretext
description	DOM-free multiline text measurement and layout using @chenglou/pretext. Use when the user needs text height calculation, virtualized list row sizing, canvas/SVG text rendering, rich-text inline flow, or any scenario involving text layout without DOM reflow.

Pretext – DOM-Free Text Measurement & Layout

Pretext is a pure-JavaScript/TypeScript library that measures and lays out multiline text without touching the DOM. It uses the browser's own font engine (via canvas measureText) as ground truth, then does all line-breaking and height calculation in pure arithmetic. Supports rendering to DOM, Canvas, SVG, and (eventually) server-side.

Why This Matters

DOM-based text measurement (getBoundingClientRect, offsetHeight) triggers layout reflow — one of the most expensive operations in a browser. Every call forces the engine to recalculate styles and geometry for potentially the entire document. In a virtualized list with 10,000 rows, that means 10,000 reflows just to get row heights.

Pretext replaces that with a two-phase approach: one prepare() call does text analysis, segmentation, glue rules, and canvas measurement (the expensive part, done once), then layout() computes height from cached widths using pure math (the cheap part, called on every resize). This is 300-600x faster than DOM measurement, and it eliminates layout thrashing entirely.

The result is pixel-perfect across browsers (7680/7680 on Chrome, Safari, and Firefox accuracy sweeps), supports all languages including emoji, mixed-bidi, CJK, Thai, Arabic, Khmer, Myanmar, Urdu, and more.

Installation

npm install @chenglou/pretext

Two Paths: Pick the Simpler One

Fast Path (90% of cases — you just need the height)

import { prepare, layout } from '@chenglou/pretext'

const prepared = prepare('AGI 春天到了. بدأت الرحلة 🚀‎', '16px Inter')
const { height, lineCount } = layout(prepared, maxWidth, 20)

This covers virtualized lists, dynamic containers, scroll anchoring — anything where you need to know how tall text will be at a given width. The prepared handle is reusable: on resize, just call layout() again with the new width.

For textarea-like text where spaces, tabs, and \n hard breaks stay visible:

const prepared = prepare(textareaValue, '16px Inter', { whiteSpace: 'pre-wrap' })
const { height } = layout(prepared, textareaWidth, 20)

For CJK/Hangul text that should avoid breaking within words:

const prepared = prepare(text, '16px Inter', { wordBreak: 'keep-all' })

Rich Path (you need the actual lines)

When you need to render text yourself (Canvas, SVG, WebGL) or do variable-width layout (flowing around images), switch to the rich APIs:

import { prepareWithSegments, layoutWithLines, walkLineRanges, layoutNextLine, layoutNextLineRange, materializeLineRange, measureLineStats, measureNaturalWidth } from '@chenglou/pretext'

• layoutWithLines() — all lines at a fixed width (Canvas/SVG rendering)
• walkLineRanges() — line ranges without building strings (shrink-wrap, binary search for optimal width, balanced text layout)
• measureLineStats() — line count and widest line width without any allocations
• measureNaturalWidth() — widest forced line when width is not the thing causing wraps
• layoutNextLine() — one line at a time with varying width (text flowing around obstacles), returns full line with text
• layoutNextLineRange() — same as above but without building the text string; use materializeLineRange() to get the text when needed

Rich-Text Inline Flow (multi-font, chips, mentions)

For rich-text inline flow with mixed fonts, code spans, mentions, chips, and browser-like boundary whitespace collapse:

import { prepareRichInline, walkRichInlineLineRanges, materializeRichInlineLineRange, measureRichInlineStats } from '@chenglou/pretext/rich-inline'

const prepared = prepareRichInline([
  { text: 'Ship ', font: '500 17px Inter' },
  { text: '@maya', font: '700 12px Inter', break: 'never', extraWidth: 22 },
  { text: "'s rich-note", font: '500 17px Inter' },
])

walkRichInlineLineRanges(prepared, 320, range => {
  const line = materializeRichInlineLineRange(prepared, range)
  // each fragment keeps its source item index, text slice, gapBefore, and cursors
})

The rich-inline helper is intentionally narrow:

• Raw inline text in, including boundary spaces
• Caller-owned extraWidth for pill chrome (padding + border width)
• break: 'never' for atomic items like chips and mentions
• white-space: normal only
• Not a nested markup tree and not a general CSS inline formatting engine

API Reference

Fast-path APIs

prepare(text: string, font: string, options?: {
  whiteSpace?: 'normal' | 'pre-wrap',
  wordBreak?: 'normal' | 'keep-all'
}): PreparedText

layout(prepared: PreparedText, maxWidth: number, lineHeight: number): {
  height: number,
  lineCount: number
}

Rich-path APIs

prepareWithSegments(text: string, font: string, options?: {
  whiteSpace?: 'normal' | 'pre-wrap',
  wordBreak?: 'normal' | 'keep-all'
}): PreparedTextWithSegments

layoutWithLines(prepared: PreparedTextWithSegments, maxWidth: number, lineHeight: number): {
  height: number, lineCount: number, lines: LayoutLine[]
}

walkLineRanges(prepared: PreparedTextWithSegments, maxWidth: number,
  onLine: (line: LayoutLineRange) => void): number

measureLineStats(prepared: PreparedTextWithSegments, maxWidth: number): {
  lineCount: number, maxLineWidth: number
}

measureNaturalWidth(prepared: PreparedTextWithSegments): number

layoutNextLineRange(prepared: PreparedTextWithSegments, start: LayoutCursor, maxWidth: number): LayoutLineRange | null

layoutNextLine(prepared: PreparedTextWithSegments, start: LayoutCursor, maxWidth: number): LayoutLine | null

materializeLineRange(prepared: PreparedTextWithSegments, line: LayoutLineRange): LayoutLine

Rich-inline APIs (@chenglou/pretext/rich-inline)

prepareRichInline(items: RichInlineItem[]): PreparedRichInline

layoutNextRichInlineLineRange(prepared: PreparedRichInline, maxWidth: number, start?: RichInlineCursor): RichInlineLineRange | null

walkRichInlineLineRanges(prepared: PreparedRichInline, maxWidth: number,
  onLine: (line: RichInlineLineRange) => void): number

materializeRichInlineLineRange(prepared: PreparedRichInline, line: RichInlineLineRange): RichInlineLine

measureRichInlineStats(prepared: PreparedRichInline, maxWidth: number): {
  lineCount: number, maxLineWidth: number
}

Utility APIs

clearCache(): void   // release internal caches used by prepare/prepareWithSegments
setLocale(locale?: string): void  // retarget word segmenter for future prepare() calls; also clears cache

Key Types

type LayoutLine = {
  text: string         // full text of the line
  width: number        // measured pixel width
  start: LayoutCursor  // inclusive start cursor
  end: LayoutCursor    // exclusive end cursor
}

type LayoutLineRange = {
  width: number
  start: LayoutCursor
  end: LayoutCursor
}

type LayoutCursor = {
  segmentIndex: number   // position in prepared segments
  graphemeIndex: number  // grapheme within that segment
}

type RichInlineItem = {
  text: string            // raw text including boundary spaces
  font: string            // canvas font shorthand
  break?: 'normal' | 'never'  // 'never' = atomic (chips, mentions)
  extraWidth?: number     // horizontal chrome width (padding + border)
}

type RichInlineFragment = {
  itemIndex: number       // index into original items array
  text: string
  gapBefore: number       // collapsed boundary gap
  occupiedWidth: number   // text width + extraWidth
  start: LayoutCursor
  end: LayoutCursor
}

type RichInlineLine = {
  fragments: RichInlineFragment[]
  width: number
  end: RichInlineCursor
}

Key Things to Get Right

• Cache prepared handles. Same text + same font = reuse the handle. Only call prepare() again if the text or font actually changed. On resize, just re-call layout().
• Match your CSS exactly. The font string must match your CSS font shorthand (size, weight, style, family). The lineHeight must match your CSS line-height. Mismatches produce wrong heights.
• Use { whiteSpace: 'pre-wrap' } for textareas where spaces, tabs, and newlines should be preserved. Tabs follow default browser-style tab-size: 8 stops.
• Use { wordBreak: 'keep-all' } for CJK/Hangul when you want to avoid breaking within words.
• Avoid system-ui on macOS — canvas and DOM can resolve to different fonts (SF Pro Text vs SF Pro Display), breaking accuracy. Use a named font.
• clearCache() is rarely needed — only when cycling through many different fonts and you want to release memory.
• setLocale() is optional — by default Pretext uses the current locale. Call it before prepare() if you need a specific Intl.Segmenter locale.

Supported CSS Target

• white-space: normal (default) and pre-wrap
• word-break: normal (default) and keep-all
• overflow-wrap: break-word — narrow widths can break inside words, but only at grapheme boundaries
• line-break: auto
• Tabs follow default browser-style tab-size: 8

What Pretext Handles Under the Hood

• Segmentation: text analysis, normalization, Unicode-aware word/grapheme segmentation via Intl.Segmenter
• CJK: astral ideographs, compatibility blocks, extension blocks, kinsoku (line-start/end prohibited punctuation)
• Arabic/RTL: no-space punctuation cluster merging, punctuation-plus-mark clusters, bidi metadata on the rich path
• Emoji: auto-detected per-font correction for canvas/DOM width discrepancy, ZWJ sequences
• Soft hyphens: invisible when unbroken, visible trailing - when the break is chosen
• NBSP/NNBSP/WJ: preserved as visible content, prevents word-boundary wrapping
• ZWSP: preserved as zero-width break opportunity
• URL-like runs: modeled as structured breakable units (path + query) to avoid bad mid-path breaks
• Mixed script: handles mixed-bidi, CJK-leading no-space runs, contextual ASCII quotes, numeric/time-range expressions

Ready-to-Use Examples

See the references/examples/ directory for complete, copy-paste-ready code:

Fast-path (height measurement):

• basic-height.ts — measure text height for a container, with wordBreak: 'keep-all'
• pre-wrap-textarea.ts — auto-size a textarea with preserved whitespace and tabs
• resize-handler.ts — canonical resize pattern: prepare() once, layout() on every resize
• virtualized-list.ts — variable row heights for virtualized lists with cached handles
• scroll-anchor.ts — prevent layout shift by predicting height before DOM insertion
• label-overflow-check.ts — CI/dev-time check that labels fit without wrapping
• multilingual-layout.ts — locale-aware measurement with setLocale() for CJK, Arabic, Thai

Rich-path (manual line layout):

• canvas-manual-layout.ts — render wrapped text on a canvas with layoutWithLines
• svg-text-render.ts — render wrapped text into SVG <tspan> elements
• flow-around-image.ts — route text around a floated image using layoutNextLineRange
• two-column-flow.ts — continuous two-column editorial flow with layoutNextLineRange
• shrink-wrap.ts — find tightest container width with walkLineRanges and measureLineStats
• balanced-text.ts — binary-search for balanced line widths to avoid orphan lines
• natural-width.ts — tooltip/popover sizing with measureNaturalWidth
• bubble-chat.ts — chat bubble shrink-wrap: find tightest width, then render lines

Rich-inline (multi-font):

• rich-inline.ts — multi-font inline flow with atomic chips and mentions

Deep Reference

• references/README.md — Full API surface from the library repo: installation, complete type definitions, all function signatures, usage examples, and caveats.
• references/AGENTS.md — Agent-specific guidance: important source files, implementation notes, practical patterns, gotchas, open questions, and decision heuristics for building with Pretext.
• references/STATUS.md — Current accuracy dashboard and benchmark snapshot pointers (browser sweep results, corpus canaries).
• references/RESEARCH.md — Research log: everything tried, measured, and learned — system-ui discovery, word-sum accuracy, Arabic frontier, soft hyphens, emoji correction, CJK/Thai/Khmer/Myanmar/Japanese/Chinese corpus canaries, and rejected approaches.
• references/DEVELOPMENT.md — Development setup, day-to-day commands, packaging/release checks, browser accuracy and benchmarking commands, corpus tooling, and deep profiling workflow.
• references/CHANGELOG.md — Version history from 0.0.0 (2026-03-26) through unreleased changes including keep-all support and rich-inline APIs.
• references/TODO.md — Current priorities: canary maintenance, next engine work, demo direction, and open design questions.
• references/SECURITY.md — Security policy and private vulnerability reporting via GitHub advisories.