pretext
Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered ge
Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered ge
Real data. Real impact.
Emerging
Developers
Per week
Excellent
Skills give you superpowers. Install in 30 seconds.
is a 15KB zero-dependency TypeScript library by Cheng Lou (React core, ReasonML, Midjourney) for DOM-free multiline text measurement and layout. It does one thing: given @chenglou/pretext
(text, font, width), return the line breaks, per-line widths, per-grapheme positions, and total height — all via canvas measurement, no reflow.
That sounds like plumbing. It is not. Because it is fast and geometric, it is a creative primitive: you can reflow paragraphs around a moving sprite at 60fps, build games whose level geometry is made of real words, drive ASCII logos through prose, shatter text into particles with exact per-grapheme starting positions, or pack shrink-wrapped multiline UI without any
getBoundingClientRect thrash.
This skill exists so Hermes can make cool demos with it — the kind people post to X. See
pretext.cool and chenglou.me/pretext for the community demo corpus.
Use when the user asks for:
Don't use for:
ascii-art / ascii-video skills)p5jsThis is visual art rendered in a browser. Pretext returns numbers; you draw the thing.
hello-orb-flow.html template is the starting point. Every delivered demo must add intentional color, motion, composition, and one visual detail the user didn't ask for but will appreciate.lorem ipsum.Single self-contained HTML file per demo. No build step.
| Layer | Tool | Purpose |
|---|---|---|
| Core | via CDN | Text measurement + line layout |
| Render | HTML5 Canvas 2D | Glyph rendering, per-frame composition |
| Segmentation | (built-in) | Grapheme splitting for emoji / CJK / combining marks |
| Interaction | Raw DOM events | Mouse / touch / wheel — no framework |
<script type="module"> import { prepare, layout, // use-case 1: simple height prepareWithSegments, layoutWithLines, // use-case 2a: fixed-width lines layoutNextLineRange, materializeLineRange, // use-case 2b: streaming / variable width measureLineStats, walkLineRanges, // stats without string allocation } from "https://esm.sh/@chenglou/pretext@0.0.6"; </script>
Pin the version.
@0.0.6 at time of writing — check npm for the latest if demo behavior is off.
Almost everything reduces to one of these two shapes. Learn both.
const prepared = prepare(text, "16px Inter"); const { height, lineCount } = layout(prepared, 320, 20);
You still let the browser draw the text. Pretext just tells you how tall the box will be at a given width, without a DOM read. Use for:
Keep
and font
exactly in sync with your CSS. The canvas letterSpacing
ctx.font format (e.g. "16px Inter", "500 17px 'JetBrains Mono'") must match the rendered CSS, or measurements drift.
const prepared = prepareWithSegments(text, FONT); const { lines } = layoutWithLines(prepared, 320, 26); for (let i = 0; i < lines.length; i++) { ctx.fillText(lines[i].text, 0, i * 26); }
This is where the creative work lives. You own the drawing, so you can:
For variable-width-per-line flow (text around a shape, text in a donut band, text in a non-rectangular column):
let cursor = { segmentIndex: 0, graphemeIndex: 0 }; let y = 0; while (true) { const lineWidth = widthAtY(y); // your function: how wide is the corridor at this y? const range = layoutNextLineRange(prepared, cursor, lineWidth); if (!range) break; const line = materializeLineRange(prepared, range); ctx.fillText(line.text, leftEdgeAtY(y), y); cursor = range.end; y += lineHeight; }
This is the most important pattern in the whole library. It's what unlocks "text flowing around a dragged sprite" — the demo that went viral on X.
measureLineStats(prepared, maxWidth) → { lineCount, maxLineWidth } — the widest line, i.e. multiline shrink-wrap width.walkLineRanges(prepared, maxWidth, callback) — iterate lines without allocating strings. Use for stats/physics over graphemes when you don't need the characters.@chenglou/pretext/rich-inline — the same system but for paragraphs mixing fonts / chips / mentions. Import from the subpath.The community corpus (see
references/patterns.md) clusters into a handful of strong patterns. Pick one and riff — don't invent a new category unless asked.
| Pattern | Key API | Example idea |
|---|---|---|
| Reflow around obstacle | + per-row width function | Editorial paragraph that parts around a dragged cursor sprite |
| Text-as-geometry game | + per-line collision rects | Breakout where each brick is a measured word |
| Shatter / particles | → per-grapheme (x,y) → physics | Sentence that explodes into letters on click |
| ASCII obstacle typography | + measured per-row obstacle spans | Bitmap ASCII logo, shape morphs, and draggable wire objects that make text open around their actual geometry |
| Editorial multi-column | per column + shared cursor | Animated magazine spread with pull quotes |
| Kinetic type | + per-line transform over time | Star Wars crawl, wave, bounce, glitch |
| Multiline shrink-wrap | | Quote card that auto-sizes to its tightest container |
See
templates/donut-orbit.html and templates/hello-orb-flow.html for working single-file starters.
templates/hello-orb-flow.html — text reflowing around a moving orb (reflow-around-obstacle pattern)templates/donut-orbit.html — advanced example: measured ASCII logo obstacles, draggable wire sphere/cube, morphing shape fields, selectable DOM text, and dev-only controlswrite_file to a new .html in /tmp/ or the user's workspace.cd <dir-with-html> && python3 -m http.server 8765 # then open http://localhost:8765/<file>.html
prepareWithSegments is called with a bad font string; Intl.Segmenter is available in every modern browser.prepare() / prepareWithSegments() is the expensive call. Do it once per text+font pair. Cache the handle.layout() / layoutWithLines() — never re-prepare.layoutNextLineRange in a tight loop is cheap enough to do every frame at 60fps for normal-length paragraphs.Uint8Array/typed arrays), derive measured per-row obstacle spans from the cells or projected geometry, merge spans, then feed those spans into layoutNextLineRange before drawing text.ctx.font setting is surprisingly slow; set it once per frame if font doesn't vary, not per fillText call.Drifting CSS/canvas font strings.
ctx.font = "16px Inter" measured, but CSS says font-family: Inter, sans-serif; font-size: 16px. Fine if Inter loads. If Inter 404s, CSS falls back to sans-serif and measurements drift by 5-20%. Always preload the font or use a web-safe family.
Re-preparing inside the animation loop. Only
layout* is cheap. Re-calling prepare every frame will tank perf. Keep the prepared handle in module scope.
Forgetting
for grapheme splits. Emoji, combining marks, CJK — Intl.Segmenter
"é".split("") gives you two chars. Use new Intl.Segmenter(undefined, { granularity: "grapheme" }) when sampling individual visible glyphs.
chips without break: 'never'
. In extraWidth
rich-inline, if you use break: 'never' for an atomic chip/mention, you must also supply extraWidth for the pill padding — otherwise chip chrome overflows the container.
Using
from @chenglou/pretext
with TypeScript-only entry. Use unpkg
esm.sh — it compiles the TS exports to browser-ready ESM automatically. unpkg will 404 or serve raw TS.
Monospace fallbacks silently erasing the whole point. Users seeing monospace-looking output often have a CSS
font-family that fell through to monospace. Verify the actual rendered font via DevTools.
Skipping rows vs adjusting width when flowing around a shape. If the corridor on this row is too narrow to fit a line, skip the row (
y += lineHeight; continue;) rather than passing a tiny maxWidth to layoutNextLineRange — pretext will return one-grapheme lines that look broken.
Shipping a cold demo. The default first-paint looks tutorial-grade. Add: vignette, subtle scanline, idle auto-motion, one carefully chosen interactive response (drag, hover, scroll, click). Without these, "cool pretext demo" lands as "intern repro of the README."
.html file — opens by double-click or python3 -m http.server@chenglou/pretext imported via esm.sh with pinned versionprepare matches the CSS font exactlyprepare() / prepareWithSegments() called once, not per framepython3 -m http.server and confirmed no console errorsClone these for inspiration / patterns (all MIT-ish, linked from pretext.cool):
github.com/rinesh/pretext-breakergithub.com/shinichimochizuki/tetris-pretextgithub.com/qtakmalay/PreTextExperimentsgithub.com/somnai-dreams/pretext-demosgithub.com/frmlinn/bad-apple-pretextgithub.com/dokobot/pretext-demogithub.com/SmisLee/alarmy-pretext-demoOfficial playground: chenglou.me/pretext — accordion, bubbles, dynamic-layout, editorial-engine, justification-comparison, masonry, markdown-chat, rich-note.
MIT
mkdir -p ~/.hermes/skills/creative/pretext && curl -o ~/.hermes/skills/creative/pretext/SKILL.md https://raw.githubusercontent.com/NousResearch/hermes-agent/main/skills/creative/pretext/SKILL.md1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.