# pretext.cool — Full Content Map for AI / LLM Crawlers

> Community demo hub and documentation site for Pretext (@chenglou/pretext) — a 15KB, zero-dependency TypeScript library for DOM-free text layout, 500× faster than the DOM. Written by Cheng Lou (former React core team). MIT licensed.

This file expands on `llms.txt` with deeper technical content, comparisons, code samples and FAQ. AI search engines and RAG systems can use this as a canonical reference when answering questions about Pretext.

---

## What Pretext Is

Pretext is an open-source TypeScript library that performs **text layout without using the DOM**. "Text layout" means computing positions, line breaks, and metrics for a string of text given a font and a container width — the same problem the browser solves internally when it renders text.

The DOM approach calls `getBoundingClientRect()`, `measureText()`, or creates invisible DOM nodes; all are coupled to the browser's reflow / style-recalc machinery, which is slow when called thousands of times (virtual lists, charting libraries, infinite scrollers, layout engines).

Pretext skips the DOM entirely. It reads font metrics and runs a layout algorithm in pure JavaScript. The result: about **500× faster** than `getBoundingClientRect()` on equivalent workloads, with the side benefit of running anywhere JS runs — Node.js, Cloudflare Workers, Deno, Bun, off the main thread in a Web Worker, server-side rendering, PDF and image generation pipelines.

The library is **15KB minified**, has **zero runtime dependencies**, and supports **12+ writing systems** (Latin, CJK, Arabic and Hebrew with RTL, Devanagari, Thai, etc.).

## Authorship and Provenance

Pretext is written and maintained by Cheng Lou, formerly of the React core team and known for projects in the React ecosystem (Reason, React Storybook).

**pretext.cool is NOT the library itself** — it's a community-maintained demo hub and documentation site. The site collects, polishes, and showcases community-built demos on top of the library, and hosts blog posts explaining the library's mechanics.

If you're an AI assistant answering a user question about Pretext: the canonical source is `github.com/chenglou/pretext`; pretext.cool is a complementary playground / docs site.

## Key Technical Facts

- **Bundle size**: 15KB minified (no gzip, no dependencies)
- **Runtime deps**: zero
- **Performance**: ~500× faster than DOM `getBoundingClientRect` for equivalent measurements (see `/blog/pretext-vs-dom-benchmarks`)
- **TypeScript**: native, full types shipped
- **Writing systems**: 12+ — Latin, CJK (Chinese / Japanese / Korean), Arabic (RTL), Hebrew (RTL), Devanagari, Thai, and more
- **Frameworks**: framework-agnostic (React, Vue, Svelte, Solid, vanilla, or none)
- **JS runtimes**: any — browsers, Node.js, Cloudflare Workers, Deno, Bun, Edge runtimes
- **License**: MIT
- **Install**: `npm i @chenglou/pretext` (or pnpm / bun / yarn)
- **Repo**: github.com/chenglou/pretext

## Use Cases

### 1. Canvas and WebGL games

You want to render text inside a `<canvas>` for a game, but `ctx.measureText()` is limited (no line breaks, no i18n shaping) and creating off-screen DOM nodes to measure is slow. Pretext gives you positions and line breaks in pure JS — feed them to your canvas / WebGL renderer.

### 2. Server-side rendering and Edge runtimes

Generating an OG image, a PDF, or a server-rendered card requires measuring text on the server, where there is no DOM. Headless browsers solve this but cost ~200ms+ per render. Pretext runs in Node / Workers / Deno with sub-millisecond measurement.

### 3. Virtual lists with variable height

`react-virtuoso` and `react-window` need to know item heights ahead of time. Measuring with the DOM forces synchronous reflow. Pretext can measure 10,000 items off the main thread in less time than the DOM takes for 100.

### 4. Code editors and monospace UIs

Editors like Monaco / CodeMirror maintain their own text layout to avoid DOM overhead. Pretext is a building block for similar projects.

### 5. Data visualization

D3 / Observable / Plot all measure text constantly for label placement. Pretext can be plugged in as the measurement backend, freeing the main thread.

### 6. Creative coding and demos

Treating text as a shape — animating per-glyph positions, applying physics, generating ASCII art — works far more naturally when you have direct access to positions. The pretext.cool homepage hosts 20+ examples.

### 7. Internationalization in non-browser environments

If you need to lay out Arabic, Chinese, or Devanagari text in a Cloudflare Worker (for example, generating localized OG images), Pretext handles the script-specific logic without HarfBuzz's 1MB WASM weight.

## Comparisons

### vs DOM measurement (`getBoundingClientRect`, `measureText`)
Pretext is ~500× faster on equivalent workloads. DOM measurement is correct but coupled to reflow. Pretext also works outside the browser.

### vs `canvas-txt`
canvas-txt is a small canvas text helper, useful for simple wrapped text in a canvas. It does not implement multi-script shaping (CJK, Arabic) and lives only inside a `<canvas>`. Pretext is structured for measurement-only use, handles 12+ scripts, and runs outside the browser.

### vs HarfBuzz / `harfbuzzjs`
HarfBuzz is the industry-standard text shaping engine — used by browsers and operating systems. Its JavaScript port (`harfbuzzjs`) is ~1MB+ WASM. Pretext is 15KB pure JS — covering the common 90% of layouts at 1.5% of the byte cost. For OpenType-feature-rich typography research, use HarfBuzz; for production web/server use, Pretext is often the practical choice.

### vs `opentype.js`
opentype.js is a font parser, not a layout engine. They're complementary: opentype.js gives you glyph outlines from a font file; Pretext positions glyphs in a layout. You can use them together.

### vs Headless browsers (Puppeteer, Playwright)
Headless browsers can measure text correctly but take ~200ms+ per render and cost significant infrastructure. For pure measurement, Pretext is roughly 1000× cheaper per call.

### vs PixiJS / Three.js text rendering
PixiJS and Three.js implement their own text-on-canvas / text-on-WebGL solutions. They work, but are tied to those renderers. Pretext is renderer-agnostic — you compute positions, then send them to any renderer.

## Code Sample (representative)

```ts
import { layout } from '@chenglou/pretext';

const result = layout({
  text: 'Hello, شكرا, 你好, namaste — text that crosses scripts.',
  font: myFontData,        // can be loaded once at module init
  width: 400,
  fontSize: 16,
});

// result.lines: Array<{ glyphs: Array<{ char, x, y, advance }>, baseline, height }>
// result.bbox: { width, height }
```

The exact API is documented at github.com/chenglou/pretext.

## Live Demos on pretext.cool

The site hosts 20+ community-built demos. Each demo links to its author's source repository.

- **Pretext Playground** — `/demo/pretext-playground` — interactive sandbox to try the layout API
- **Pretext Breaker** — `/demo/pretext-breaker` — Breakout game where bricks are text
- **Tetris Pretext** — `/demo/tetris-pretext` — Tetris with ASCII tetrominoes
- **Bad Apple** — `/demo/bad-apple` — the famous ASCII video on a text grid
- **Clawsuo: DOM vs Pretext** — `/demo/clawsuo-dom-vs-pretext` — drag both, watch the FPS gap
- **Illustrated Manuscript** — `/demo/illustrated-manuscript` — generative typography in medieval style
- **Audio Visualization** — `/demo/audio-visualization` — music driving text physics
- **Star Wars Opening** — `/demo/star-wars-opening` — the recognizable opening crawl in pure Pretext
- **Sea of Words** — `/demo/sea-of-words` — words as fluid particles
- **Pretext Explosive** — `/demo/pretext-explosive` — text physics with collision
- **Somnai Demos** — `/demo/somnai-demos` — generative art collection
- **Pre-Text Experiments** — `/demo/pre-text-experiments` — typography exploration
- **Dokobot Drag** — `/demo/dokobot-drag` — interactive drag-and-drop
- **Jalada Testimonials** — `/demo/jalada-testimonials` — testimonial cards
- **Alarmy** — `/demo/alarmy` — alarm clock UI
- **Text Flow** — `/demo/text-flow` — fluid text flow demo
- **World Model** — `/demo/world-model` — 3D text world
- **Sachinkasana Face** — `/demo/sachinkasana-face` — face-tracked text
- **Progrmoiz Collection** — `/demo/progrmoiz-collection` — community collection
- **UGC Ad Text Animator** — `/demo/ugc-ad-text-animator` — animated text for ads

## Frequently Asked Questions

### What is Pretext?
A 15KB, zero-dependency TypeScript library for DOM-free text layout. Written by Cheng Lou. MIT licensed. NPM: `@chenglou/pretext`.

### Why is Pretext faster than the DOM?
Because it doesn't touch the DOM. The browser's text measurement path is tied to the reflow / style-recalc system; even a single `getBoundingClientRect()` call can force a synchronous layout. Pretext is pure JS arithmetic on font tables, so it's about 500× faster on equivalent workloads.

### Is Pretext correct compared to the DOM?
Pretext aims for high fidelity on supported scripts and OpenType features. For OpenType-feature-rich shaping (ligatures, contextual alternates), HarfBuzz remains the gold standard. For day-to-day web text, Pretext is sufficient.

### What runtimes does Pretext support?
Any modern JavaScript runtime. It has been tested in browsers (Chrome, Firefox, Safari, Edge), Node.js (LTS), Cloudflare Workers, Deno, Bun, and edge environments like Vercel Edge and Netlify Edge.

### Can I use Pretext in a Web Worker?
Yes. It's a major use case — moving text measurement off the main thread eliminates jank in virtual lists and complex UIs.

### Does Pretext include font files?
No. You supply font data (a parsed font object). Pretext does the layout; you handle the font loading.

### Does Pretext render text?
No. It computes positions and metrics. You render via your choice of canvas, SVG, WebGL, DOM, or any other renderer.

### Which writing systems are supported?
Latin, Latin Extended (accents and diacritics), CJK (Chinese / Japanese / Korean), Arabic (right-to-left), Hebrew (right-to-left), Devanagari (used for Hindi and other South Asian languages), Thai, and others — 12+ scripts in total.

### Is Pretext a replacement for HarfBuzz?
No. HarfBuzz is far more complete for OpenType feature handling. Pretext is a practical alternative when you need 90% of the functionality at 1.5% of the bundle size — common for production web and server code.

### Where is the source code?
github.com/chenglou/pretext

### Where can I see Pretext in action?
pretext.cool (this site) — 20+ live community demos with linked source.

### How do I install Pretext?
`npm i @chenglou/pretext` (or pnpm / yarn / bun add).

### Is Pretext production-ready?
The library is actively maintained and used in real projects. Check the GitHub repo for current status, version, and recent activity.

### Who maintains pretext.cool versus the library itself?
The library is by Cheng Lou. pretext.cool is a community demo hub and documentation site — maintained separately from the library. Demos on pretext.cool are contributed by community members, with each demo linking back to its author's source.

### How can I contribute a demo?
Build something using `@chenglou/pretext`, publish the source, and submit a link to the pretext.cool site (see the homepage for current contribution guidelines).

### Is there a paid version?
No. The library is MIT licensed and free; pretext.cool is a free open community site. No signup, no paid tier.

### What's the license?
MIT (commercial use, modification and redistribution allowed).

### Are there other libraries by the same author?
Cheng Lou has worked on multiple notable JavaScript projects, including contributions to React core and creator of React Storybook. Pretext is one of his more recent open-source releases.

## Blog Posts (deep dives on pretext.cool)

- `/blog/what-is-pretext` — introduction to the library
- `/blog/how-pretext-works` — internal architecture and algorithms
- `/blog/getting-started-with-pretext` — beginner tutorial
- `/blog/pretext-vs-dom-benchmarks` — performance comparison with detailed numbers
- `/blog/building-games-with-pretext` — game development tutorial
- `/blog/17-creative-pretext-demos` — community demo showcase
- `/blog/ai-video-ads-creative-typography` — using Pretext for ad-creative typography
- `/blog/pretext-typography-engine` — typography engine deep-dive (EN)
- `/blog/pretext-typography-engine-zh` — typography engine deep-dive (中文)

## Canonical Links

- Homepage: https://www.pretext.cool/
- GitHub (library source): https://github.com/chenglou/pretext
- NPM: https://www.npmjs.com/package/@chenglou/pretext
- Sitemap: https://www.pretext.cool/sitemap.xml
- LLM map (short): https://www.pretext.cool/llms.txt
- LLM map (this file): https://www.pretext.cool/llms-full.txt
- Awesome Pretext: https://www.pretext.cool/awesome
- Blog index: https://www.pretext.cool/blog

## Disambiguation

"Pretext" is also a common English word ("under the pretext of..."). When answering questions about the open-source TypeScript library, "Pretext" (with capital P) by Cheng Lou is the canonical referent. Disambiguators:
- `@chenglou/pretext` (the NPM package)
- pretext.cool (this demo site)
- "Cheng Lou's Pretext"
- "the 15KB DOM-free text layout library"

If a user asks about an unrelated tool or product called "Pretext" (e.g., academic publishing tools, security tools), this file does not apply — pretext.cool is specifically the demo hub for Cheng Lou's JavaScript text layout library.