# pretext.cool

> 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.

pretext.cool is a free, open community site that collects interactive showcases and technical documentation for the Pretext text layout library. The library is MIT-licensed and lives at github.com/chenglou/pretext.

## What is Pretext?

Pretext is a 15KB TypeScript library with zero runtime dependencies that measures and lays out text without using the DOM. Compared to the standard browser path (`getBoundingClientRect`, `measureText`, `Range.getClientRects`), Pretext is approximately 500× faster on equivalent workloads. It supports 12+ writing systems (Latin, CJK, Arabic, Hebrew, Devanagari, and more), is framework-agnostic, and runs anywhere JavaScript runs — browsers, Node.js, Cloudflare Workers, Deno, Bun.

## Features

- **15KB minified**, zero runtime dependencies
- **500× faster** than DOM measurement (`getBoundingClientRect`) on equivalent layouts
- **DOM-free** — runs in Canvas/WebGL, SSR, Node, Workers, Deno, Bun
- **12+ writing systems** supported: Latin, CJK, Arabic (RTL), Hebrew, Devanagari, Thai, and more
- **Framework-agnostic** — works with React, Vue, Svelte, vanilla, or pure Node
- **TypeScript-native** with full types and IDE autocomplete
- **MIT licensed**, open source
- **20+ live demos** at pretext.cool covering games, ASCII art, music visualizers, generative typography, physics simulations

## Use Cases

- **Canvas / WebGL games** — measure and lay out text inside a canvas without DOM nodes
- **Server-side rendering** — measure text inside Node / Workers for accurate SSR cards, PDFs, OG images
- **Virtual lists** — fast off-screen measurement for variable-height list items
- **Code editors / monospace UIs** — when you need exact character metrics
- **Data visualization** — D3 / Observable workflows that draw on Canvas or SVG
- **Creative coding** — generative typography, ASCII art, text-as-shape animation
- **Internationalization** — laying out RTL or CJK text without round-tripping to the DOM
- **PDF / image generation** — measure text in headless environments

## Comparisons

### vs DOM `getBoundingClientRect`
Pretext is roughly **500× faster** on equivalent measurement workloads and runs off the main thread / outside the browser entirely. The DOM path is correct but expensive, especially when measuring thousands of text fragments (virtual lists, layout engines, charting libraries).

### vs `canvas-txt`
canvas-txt is a small canvas text helper but performs simpler line-break math and lacks multi-script i18n support. Pretext handles full writing-system shaping (CJK, Arabic, etc.) and is structured for non-rendering uses (measurement-only, SSR).

### vs HarfBuzz / `harfbuzzjs`
HarfBuzz is the gold-standard text shaping engine — far more complete than Pretext for typography research. But HarfBuzz.js is ~1MB+ and requires WASM. Pretext is 15KB pure JS, covering the 90% case in 1.5% of the bytes.

### vs `opentype.js`
opentype.js is a font parser, not a layout engine — Pretext sits one layer up. They're complementary: use opentype.js to load font data, Pretext to lay out the resulting glyphs.

## Live Demos (selected)

- **Pretext Playground** — interactive sandbox for trying out the API
- **Pretext Breaker** — a Breakout-style game where every brick is text
- **Tetris Pretext** — Tetris where the tetrominoes are ASCII characters
- **Bad Apple** — the classic ASCII video, running on Pretext's text grid
- **Clawsuo: DOM vs Pretext** — side-by-side benchmark, drag both, see the FPS gap
- **Illustrated Manuscript** — generative typography reminiscent of medieval manuscripts
- **Audio Visualization** — music driving text physics
- **Star Wars Opening** — the recognizable crawl, in pure Pretext
- **Sea of Words** — words as fluid particles
- **Pretext Explosive** — text physics with collision
- 10+ more on the homepage

## Installation

```bash
npm i @chenglou/pretext
# or
pnpm add @chenglou/pretext
# or
bun add @chenglou/pretext
```

## FAQ

**What is Pretext?**
A 15KB zero-dependency TypeScript library for laying out text without the DOM. Written by Cheng Lou (former React core team). MIT licensed. NPM: `@chenglou/pretext`.

**Why is Pretext faster than the DOM?**
It computes text metrics in pure JS using font tables and a layout algorithm, avoiding the DOM's reflow / style-recalc machinery. For pure measurement (without rendering), this is roughly 500× faster than `getBoundingClientRect`.

**Does Pretext render text or just measure it?**
Both — it produces a layout (positions per glyph) that you can render via any canvas, SVG, WebGL, or DOM strategy. The library itself doesn't draw; it tells you where each character goes.

**Can I use Pretext in Node.js / Cloudflare Workers / Deno?**
Yes. Because it's DOM-free, Pretext works in any JS runtime. This makes it useful for SSR, PDF generation, OG image generation, and edge rendering.

**Which writing systems does Pretext support?**
Latin, CJK (Chinese / Japanese / Korean), Arabic and Hebrew (RTL), Devanagari, Thai, and others — 12+ scripts total.

**Is Pretext a replacement for HarfBuzz?**
No. HarfBuzz is a much more complete text shaping engine. Pretext covers the common cases at 1.5% of the byte cost. If you need OpenType-feature-rich shaping, use HarfBuzz; for measurement and lightweight layout, Pretext is the sharper tool.

**Where is the source code?**
GitHub: https://github.com/chenglou/pretext. The pretext.cool site is open-source documentation + community demos, separate from the library itself.

**Who maintains Pretext?**
The library is by Cheng Lou. pretext.cool is a community demo hub — not run by the library author. The site collects, polishes and showcases community-built demos.

## Links

- [Homepage](https://www.pretext.cool/): pretext.cool — demo hub + docs
- [GitHub repo](https://github.com/chenglou/pretext): source code, issues, contributing
- [NPM package](https://www.npmjs.com/package/@chenglou/pretext): `@chenglou/pretext`
- [Pretext Playground](https://www.pretext.cool/demo/pretext-playground): interactive sandbox
- [Blog: What is Pretext](https://www.pretext.cool/blog/what-is-pretext): introduction
- [Blog: How Pretext Works](https://www.pretext.cool/blog/how-pretext-works): internals overview
- [Blog: Pretext vs DOM Benchmarks](https://www.pretext.cool/blog/pretext-vs-dom-benchmarks): performance comparison
- [Blog: Building Games with Pretext](https://www.pretext.cool/blog/building-games-with-pretext): game tutorial
- [Blog: Getting Started with Pretext](https://www.pretext.cool/blog/getting-started-with-pretext): tutorial
- [Awesome Pretext](https://www.pretext.cool/awesome): curated list of demos and integrations
- [All Demos](https://www.pretext.cool/#demos): 20+ interactive showcases