pretext

1---2name: pretext3description: Build creative browser demos with DOM-free text layout.4version: 1.0.05author: Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [creative-coding, typography, pretext, ascii-art, canvas, generative, text-layout, kinetic-typography]11    related_skills: [p5js, claude-design, excalidraw, architecture-diagram]12---13 14# Pretext Creative Demos15 16## Overview17 18[`@chenglou/pretext`](https://github.com/chenglou/pretext) 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 `(text, font, width)`, return the line breaks, per-line widths, per-grapheme positions, and total height — all via canvas measurement, no reflow.19 20That 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.21 22This 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.23 24## When to Use25 26Use when the user asks for:27- A "pretext demo" / "cool pretext thing" / "text-as-X"28- Text flowing around a moving shape (hero sections, editorial layouts, animated long-form pages)29- ASCII-art effects using **real words or prose**, not monospace rasters30- Games where the playfield / obstacles / bricks are made of text (Tetris-from-letters, Breakout-of-prose)31- Kinetic typography with per-glyph physics (shatter, scatter, flock, flow)32- Typographic generative art, especially with non-Latin scripts or mixed scripts33- Multiline "shrink-wrap" UI (smallest container width that still fits the text)34- Anything that would require knowing line breaks *before* rendering35 36Don't use for:37- Static SVG/HTML pages where CSS already solves layout — just use CSS38- Rich text editors, general inline formatting engines (pretext is intentionally narrow)39- Image → text (use `ascii-art` / `ascii-video` skills)40- Pure canvas generative art with no text role — use `p5js`41 42## Creative Standard43 44This is visual art rendered in a browser. Pretext returns numbers; **you** draw the thing.45 46- **Don't ship a "hello world" demo.** The `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.47- **Dark backgrounds, warm cores, considered palette.** Classic amber-on-black (CRT / terminal) works, but so do cold-white-on-charcoal (editorial) and desaturated pastels (risograph). Pick one and commit.48- **Proportional fonts are the point.** Pretext's whole vibe is "not monospaced" — lean into it. Use Iowan Old Style, Inter, JetBrains Mono, Helvetica Neue, or a variable font. Never default sans.49- **Real source/text, not lorem ipsum.** The corpus should mean something. Short manifestos, poetry, real source code, a found text, the library's own README — never `lorem ipsum`.50- **First-paint excellence.** No loading states, no blank frames. The demo must look shippable the instant it opens.51 52## Stack53 54Single self-contained HTML file per demo. No build step.55 56| Layer | Tool | Purpose |57|-------|------|---------|58| Core | `@chenglou/pretext` via `esm.sh` CDN | Text measurement + line layout |59| Render | HTML5 Canvas 2D | Glyph rendering, per-frame composition |60| Segmentation | `Intl.Segmenter` (built-in) | Grapheme splitting for emoji / CJK / combining marks |61| Interaction | Raw DOM events | Mouse / touch / wheel — no framework |62 63```html64<script type="module">65import {66  prepare, layout,                   // use-case 1: simple height67  prepareWithSegments, layoutWithLines,  // use-case 2a: fixed-width lines68  layoutNextLineRange, materializeLineRange, // use-case 2b: streaming / variable width69  measureLineStats, walkLineRanges,  // stats without string allocation70} from "https://esm.sh/@chenglou/pretext@0.0.6";71</script>72```73 74Pin the version. `@0.0.6` at time of writing — check [npm](https://www.npmjs.com/package/@chenglou/pretext) for the latest if demo behavior is off.75 76## The Two Use Cases77 78Almost everything reduces to one of these two shapes. Learn both.79 80### Use-case 1 — measure, then render with CSS/DOM81 82```js83const prepared = prepare(text, "16px Inter");84const { height, lineCount } = layout(prepared, 320, 20);85```86 87You 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:88- Virtualized lists where rows contain wrapping text89- Masonry with precise card heights90- "Does this label fit?" dev-time checks91- Preventing layout shift when remote text loads92 93**Keep `font` and `letterSpacing` exactly in sync with your CSS.** The canvas `ctx.font` format (e.g. `"16px Inter"`, `"500 17px 'JetBrains Mono'"`) must match the rendered CSS, or measurements drift.94 95### Use-case 2 — measure *and* render yourself96 97```js98const prepared = prepareWithSegments(text, FONT);99const { lines } = layoutWithLines(prepared, 320, 26);100for (let i = 0; i < lines.length; i++) {101  ctx.fillText(lines[i].text, 0, i * 26);102}103```104 105This is where the creative work lives. You own the drawing, so you can:106- Render to canvas, SVG, WebGL, or any coordinate system107- Substitute per-glyph transforms (rotation, jitter, scale, opacity)108- Use line metadata (width, grapheme positions) as geometry109 110For **variable-width-per-line** flow (text around a shape, text in a donut band, text in a non-rectangular column):111 112```js113let cursor = { segmentIndex: 0, graphemeIndex: 0 };114let y = 0;115while (true) {116  const lineWidth = widthAtY(y);  // your function: how wide is the corridor at this y?117  const range = layoutNextLineRange(prepared, cursor, lineWidth);118  if (!range) break;119  const line = materializeLineRange(prepared, range);120  ctx.fillText(line.text, leftEdgeAtY(y), y);121  cursor = range.end;122  y += lineHeight;123}124```125 126This 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.127 128### Helpers worth knowing129 130- `measureLineStats(prepared, maxWidth)` → `{ lineCount, maxLineWidth }` — the widest line, i.e. multiline shrink-wrap width.131- `walkLineRanges(prepared, maxWidth, callback)` — iterate lines without allocating strings. Use for stats/physics over graphemes when you don't need the characters.132- `@chenglou/pretext/rich-inline` — the same system but for paragraphs mixing fonts / chips / mentions. Import from the subpath.133 134## Demo Recipe Patterns135 136The 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.137 138| Pattern | Key API | Example idea |139|---|---|---|140| **Reflow around obstacle** | `layoutNextLineRange` + per-row width function | Editorial paragraph that parts around a dragged cursor sprite |141| **Text-as-geometry game** | `layoutWithLines` + per-line collision rects | Breakout where each brick is a measured word |142| **Shatter / particles** | `walkLineRanges` → per-grapheme (x,y) → physics | Sentence that explodes into letters on click |143| **ASCII obstacle typography** | `layoutNextLineRange` + measured per-row obstacle spans | Bitmap ASCII logo, shape morphs, and draggable wire objects that make text open around their actual geometry |144| **Editorial multi-column** | `layoutNextLineRange` per column + shared cursor | Animated magazine spread with pull quotes |145| **Kinetic type** | `layoutWithLines` + per-line transform over time | Star Wars crawl, wave, bounce, glitch |146| **Multiline shrink-wrap** | `measureLineStats` | Quote card that auto-sizes to its tightest container |147 148See `templates/donut-orbit.html` and `templates/hello-orb-flow.html` for working single-file starters.149 150## Workflow151 1521. **Pick a pattern** from the table above based on the user's brief.1532. **Start from a template**:154   - `templates/hello-orb-flow.html` — text reflowing around a moving orb (reflow-around-obstacle pattern)155   - `templates/donut-orbit.html` — advanced example: measured ASCII logo obstacles, draggable wire sphere/cube, morphing shape fields, selectable DOM text, and dev-only controls156   - `write_file` to a new `.html` in `/tmp/` or the user's workspace.1573. **Swap the corpus** for something intentional to the brief. Real prose, 10-100 sentences, no lorem.1584. **Tune the aesthetic** — font, palette, composition, interaction. This is the work; don't skip it.1595. **Verify locally**:160   ```sh161   cd <dir-with-html> && python -m http.server 8765162   # then open http://localhost:8765/<file>.html163   ```1646. **Check the console** — pretext will throw if `prepareWithSegments` is called with a bad font string; `Intl.Segmenter` is available in every modern browser.1657. **Show the user the file path**, not just the code — they want to open it.166 167## Performance Notes168 169- `prepare()` / `prepareWithSegments()` is the expensive call. Do it **once** per text+font pair. Cache the handle.170- On resize, only rerun `layout()` / `layoutWithLines()` — never re-prepare.171- For per-frame animations where text doesn't change but geometry does, `layoutNextLineRange` in a tight loop is cheap enough to do every frame at 60fps for normal-length paragraphs.172- When rendering ASCII masks per frame, keep a cell buffer (`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.173- Keep visual animation and layout animation coupled. If a sphere morphs into a cube, tween both the rendered cell buffer and the obstacle spans with the same value; otherwise the demo looks painted-on instead of physically reflowed.174- For fades, prefer layer opacity over changing glyph intensity or obstacle scale. Put transient ASCII sprites on their own canvas and fade the canvas with CSS/GSAP opacity so geometry does not appear to shrink.175- Canvas `ctx.font` setting is surprisingly slow; set it **once** per frame if font doesn't vary, not per `fillText` call.176 177## Common Pitfalls178 1791. **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.180 1812. **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.182 1833. **Forgetting `Intl.Segmenter` for grapheme splits.** Emoji, combining marks, CJK — `"é".split("")` gives you two chars. Use `new Intl.Segmenter(undefined, { granularity: "grapheme" })` when sampling individual visible glyphs.184 1854. **`break: 'never'` chips without `extraWidth`.** In `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.186 1875. **Using `@chenglou/pretext` from `unpkg` with TypeScript-only entry.** Use `esm.sh` — it compiles the TS exports to browser-ready ESM automatically. `unpkg` will 404 or serve raw TS.188 1896. **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.190 1917. **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.192 1938. **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."194 195## Verification Checklist196 197- [ ] Demo is a single self-contained `.html` file — opens by double-click or `python -m http.server`198- [ ] `@chenglou/pretext` imported via `esm.sh` with pinned version199- [ ] Corpus is real prose, not lorem ipsum, and matches the demo's concept200- [ ] Font string passed to `prepare` matches the CSS font exactly201- [ ] `prepare()` / `prepareWithSegments()` called once, not per frame202- [ ] Dark background + considered palette — not the default white canvas203- [ ] At least one interactive response (drag / hover / scroll / click) or idle auto-motion204- [ ] Tested locally with `python -m http.server` and confirmed no console errors205- [ ] 60fps on a mid-tier laptop (or graceful degradation documented)206- [ ] One "extra mile" detail the user didn't ask for207 208## Reference: Community Demos209 210Clone these for inspiration / patterns (all MIT-ish, linked from [pretext.cool](https://www.pretext.cool/)):211 212- **Pretext Breaker** — breakout with word-bricks — `github.com/rinesh/pretext-breaker`213- **Tetris × Pretext** — `github.com/shinichimochizuki/tetris-pretext`214- **Dragon animation** — `github.com/qtakmalay/PreTextExperiments`215- **Somnai editorial engine** — `github.com/somnai-dreams/pretext-demos`216- **Bad Apple!! ASCII** — `github.com/frmlinn/bad-apple-pretext`217- **Drag-sprite reflow** — `github.com/dokobot/pretext-demo`218- **Alarmy editorial clock** — `github.com/SmisLee/alarmy-pretext-demo`219 220Official playground: [chenglou.me/pretext](https://chenglou.me/pretext/) — accordion, bubbles, dynamic-layout, editorial-engine, justification-comparison, masonry, markdown-chat, rich-note.221