Pretext Text Effects

Generate browser pages powered by Pretext (@chenglou/pretext)—a pure-arithmetic text measurement library that bypasses DOM layout reflow entirely. Pretext measures text with proportional font precision using canvas measureText, enabling effects impossible with CSS alone.

Companion library: opentype.js (opentype.js@1.3.4) — direct font binary parsing for per-glyph SVG path rendering, Bezier control point access, kerning tables, and variable font axes. Pretext handles line breaking; opentype.js handles what happens inside each glyph. Together they unlock effects neither can achieve alone.

Output is always a single self-contained HTML file. No build step, no framework, runs in any modern browser.

Quick Start

Describe a text effect. Claude picks the right Pretext pattern and generates a complete HTML file.

Examples:

• /pretext fluid smoke ASCII art with gold characters on black
• /pretext chat bubbles that shrinkwrap tighter than CSS
• /pretext calligram — the word "ocean" shaped like a wave
• /pretext editorial layout with text flowing around draggable circles
• /pretext masonry grid of shower thoughts with instant height prediction
• /pretext glyph path art — SVG letterforms with stroke animation
• /pretext animated dragon cursor that pushes text aside as it moves
• /pretext illuminated manuscript with live vine growth reflow
• /pretext variable font wave — per-character weight animation
• /pretext glyph morph — letterform interpolation from A to Z
• /pretext letterbox gallery of "BEACON" in Playfair Display italic on dark background
• /pretext glyph-mask calligram — letter R filled with lorem ipsum in Georgia

Do NOT Use This Skill When

• Simple CSS text-shadow, text-stroke, or gradient text effects
• CSS Shapes level 1 (shape-outside on floated elements) for static layouts
• Basic @keyframes text animation (fade, slide, typewriter)
• Monospace ASCII art (no proportional measurement needed)
• SVG <text> without per-glyph control
• Rich text editing (contenteditable, ProseMirror, TipTap)
• PDF generation or markdown rendering

These are all achievable without Pretext or opentype.js.

Effect Categories

Pretext-Only Effects

Pretext + opentype.js Effects

Concept-to-Effect

Every design decision derives from the concept. Do not default—derive.

Choose the API tier from the effect complexity:

• Static height only → prepare() + layout() (fastest, opaque)
• Need line text/positions → prepareWithSegments() + layoutWithLines()
• Need per-line width variation → layoutNextLine() (iterator, variable width per line)
• Need aggregate geometry without strings → walkLineRanges() (no string materialization)
• Need individual character widths → prepareWithSegments() on single chars

Choose the rendering target from the output type:

• DOM elements (.line { position: absolute }) → editorial, accordion, masonry
• Canvas 2D (ctx.fillText) → calligrams, some ASCII art
• HTML spans with inline styles → typographic ASCII (weight/style/opacity per character)

Architecture

Pretext CDN → prepare/prepareWithSegments → layout/layoutNextLine → line positions
                                                                          ↓
opentype.js CDN → font.parse(buffer) → glyph.getPath() ──────────> SVG <path> elements
                                                                          ↓
                                                              requestAnimationFrame (if animated)
                                                              resize handler (always)

Two-library split: Pretext decides WHERE text goes (line breaking, obstacle routing). opentype.js decides HOW each glyph looks (SVG paths, Bezier curves, contour data). Use Pretext alone for DOM-positioned text. Add opentype.js when you need per-glyph SVG rendering, path animation, or glyph contour access.

CDN Imports

<!-- Pretext (ESM, required) -->
<script type="module">
import { prepare, layout, prepareWithSegments, layoutWithLines, walkLineRanges, layoutNextLine, clearCache } from 'https://esm.sh/@chenglou/pretext@0.0.2'
</script>

<!-- opentype.js (UMD, optional — only for glyph path effects) -->
<script src="https://cdn.jsdelivr.net/npm/opentype.js@1.3.4/dist/opentype.min.js"></script>

<!-- Font binary for opentype.js (Inter .woff — confirmed working) -->
<!-- const FONT_URL = 'https://cdn.jsdelivr.net/npm/@fontsource/inter@5.0.8/files/inter-latin-400-normal.woff' -->

<!-- flubber (optional — only for glyph morphing) -->
<!-- <script src="https://cdn.jsdelivr.net/npm/flubber@0.4.2/build/flubber.min.js"></script> -->

Import only the functions you need. Pin the version. opentype.js cannot parse .woff2 — use .woff or .ttf only.

Composition Parameters

All Effects

Typographic ASCII

Calligrams

Editorial / Obstacle Routing

opentype.js — Glyph Path Effects

Glyph-Mask Calligrams / Letterbox Gallery

opentype.js + flubber — Glyph Morphing

References

Anti-Patterns

Pretext

• Never use system-ui as font — canvas and DOM can resolve different fonts on macOS
• Never use React/Vue/framework — vanilla JS + HTML only
• Never omit <meta name="viewport"> — proportional measurement depends on correct device pixels
• Never use setInterval for animation — always requestAnimationFrame
• Never skip the resize handler — text layout depends on container width
• Never call prepare() inside the animation loop — it's the expensive one-time pass. Cache it.
• Never omit document.fonts.ready.then(...) — measure after fonts load, not before
• Never use pure black (#000000) — use rich off-blacks (#06060a, #08080e, #0a0a0c)
• Never build line strings when you only need geometry — use walkLineRanges instead of layoutWithLines
• Never position text with CSS flow — use position: absolute and place lines from Pretext coordinates
• Never pick one side of an obstacle when the obstacle is in the middle — use carveTextLineSlots to fill both sides
• Never create/destroy DOM elements per frame — use element pooling (syncPool)

opentype.js

• Never use .woff2 files — opentype.js cannot parse them. Use .woff or .ttf only
• Never use opentype.load() — use fetch().then(r => r.arrayBuffer()).then(opentype.parse) for better error handling
• Never render glyphs at absolute positions then try to move them — render at (0,0) and position via <g transform="translate(x,y)">
• Never forget font.unitsPerEm — the scale factor is fontSize / font.unitsPerEm
• Never call glyph.getPath() inside a tight loop without caching — cache the pathData string, regenerate only when position changes
• Never skip kerning — always check font.getKerningValue(glyph, nextGlyph) * scale between adjacent glyphs
• Never use Google Fonts TTF CDN URLs (they return 404 for programmatic access) — use @fontsource via jsdelivr

Post-Generation QA

python3 ~/.claude/skills/pretext/scripts/validate_pretext.py output.html

Checklist:

1. ESM import from esm.sh/@chenglou/pretext present
2. <script type="module"> tag
3. Named font declaration (no system-ui)
4. <meta name="viewport"> present
5. Window resize handler
6. document.fonts.ready awaited before measurement
7. requestAnimationFrame loop (for animated effects)
8. Touch event handlers (for interactive effects)
9. No setInterval for animation
10. No framework imports