pretexter

# Pretexter **An all-in-one Claude Code plugin that makes agents experts at [`@chenglou/pretext`](https://github.com/chenglou/pretext)** — the library for fast, accurate, multilingual **text measurement & layout without DOM reflow** (line breaks, paragraph height, line counts, shrink-wrap widths, rich inline flow; rendering to DOM, Canvas, SVG, and server-side). Pretexter gives your agents the knowledge and tooling to produce **stunning, smooth, technically-correct typography** on demand: hub-and-spoke skills, slash commands, multi-agent workflows, a curated offline reference, and a bundled MCP server other tools can connect to. > Pretexter is *tooling about* pretext. It does not fork or modify the library. The real pretext source lives, unmodified, in [`reference/`](reference/PROVENANCE.md). ## Why I made this AI coding agents are wonderful generalists but shallow specialists. They've *heard of* most libraries, but they don't *know* them — not the way someone who's actually lived in the docs does. They guess at APIs, skip the gotchas, and write code that runs but isn't quite right. So I picked one small, beautiful, focused library — [`@chenglou/pretext`](https://github.com/chenglou/pretext), which measures and lays out text without the usual browser slowness — and asked a simple question: **what would it take to make an agent a genuine *expert* at it?** Not "has heard of it," but "reaches for the right API, dodges the footguns, and produces typography that actually looks considered." This repo is the answer I landed on. It started as a fun experiment and grew into a whole little toolkit: skills the agent auto-uses, vetted recipes, a linter that catches the classic mistakes, multi-agent workflows, and an MCP server that can even spin up a *real browser* to check its own work. I tried to keep it honest the whole way — everything is verified against the real source, with **zero invented APIs**. So yeah — it's mostly a **fun experiment**: a study in how deep you can push an agent's expertise in one narrow domain if you really try. But it's also genuinely useful. If you build anything with text on the web, the recipes and tools in here are real, and they work. If even one person ships something a little more beautiful because of this, it was worth it. **I hope you get some use out of it. :)** *— [New1Direction](https://github.com/New1Direction) · built with a lot of help from [Claude Code](https://claude.com/claude-code).* ## See it in action No install needed — just open these in a browser: - **[`index.html`](index.html)** — the landing page (start here) - **[`demo/showcase.html`](demo/showcase.html)** — a live **with/without pretext** demo: flip one switch and watch 7 examples change. Drag the photo in example 07 to see text wrap around it in real time. - The three explainers: **[the toolkit, explained](pretexter-explained.html)** · **[render · shape · see](pretexter-capabilities.html)** · **[the complete tour](pretexter-toolkit.html)** ## What's inside ``` pretexter/ ├── knowledge/ ← single source of truth: api.md, pitfalls.json/.md, typography.md, 15 recipes ├── reference/ ← curated, unmodified vendor of pretext src + demos + docs (offline ground truth) ├── lib/ ← pure, tested kit: placeRuns · layoutBox · render · cssSync · fontFallback · balance · cssBridge ├── skills/ ← pretext (hub) + 8 spokes: measure · manual-layout · rich-inline · typography · i18n · render · shaping · css ├── commands/ ← /pretext-new · /pretext-review · /pretext-demo · /pretext-explain ├── agents/ ← pretext-reviewer subagent ├── workflows/ ← pretext-build · pretext-audit (multi-agent orchestration) └── mcp/ ← bundled MCP server (knowledge + recipes + linter; Phase-2 layout/glyph-metrics/preview) ``` The **knowledge layer is canonical**: skills cite it, the MCP server serves it, the linter enforces it — so they can never drift. Every code snippet in the toolkit uses only real pretext exports, verified against `reference/src`. ## Install **Dev / quickest (loads for the session):** ```sh claude --plugin-dir /Users/clubpenguin/Documents/pretexter ``` Use `/reload-plugins` after edits. Validate with `claude plugin validate /Users/clubpenguin/Documents/pretexter`. **Persistent (settings):** add to `~/.claude/settings.json` (or project `.claude/settings.json`): ```jsonc { "enabledPlugins": ["pretexter@local"], "extraKnownMarketplaces": { "local": { "source": { "source": "github", "repo": "you/pretexter" } } } } ``` (Or push to a Git repo and `/plugin marketplace add` + `/plugin install pretexter@…`.) Installing the plugin auto-discovers the skills, commands, and agent, **and auto-wires the MCP server** (via `.claude-plugin/plugin.json`, using `${CLAUDE_PLUGIN_ROOT}` so it resolves in the plugin cache). ## The skills (auto-trigger) | Skill | Use when… | |---|---| | **pretext** (hub) | any text measuring/wrapping/layout question — routes to the right spoke + recipe | | **pretext-measure** | you need height / lineCount with no DOM reflow: virtualization, overflow guards, masonry heights, layout-shift prevention | | **pretext-manual-layout** | laying out lines yourself: Canvas/SVG rendering, float-aware flow, shrink-wrap, cursors | | **pretext-rich-inline** | mixed-font inline flow with atomic chips/mentions, code spans, boundary-whitespace collapse | | **pretext-typography** | making it *beautiful*: balanced rag, justification, vertical rhythm, masonry, editorial composition, type art | | **pretext-i18n** | RTL/bidi, CJK `keep-all`, SE-Asian scripts, soft hyphens, locale | | **pretext-render** | the easy high-level layout box (text + box + alignment → positioned runs) and rendering to DOM / SVG / Canvas / WebGL, plus vertical/CJK writing-mode | | **pretext-shaping** | per-glyph / per-cluster metrics (Canvas TextMetrics, DOM Range) and true glyph shaping (HarfBuzz / fontkit) | | **pretext-css** | CSS synergy: sync to `getComputedStyle`, kill layout shift (CLS) with `@font-face` fallback metrics, uncapped `text-wrap: balance`/`pretty`, fit-to-box `clamp()`, intrinsic sizing, line-clamp, CSS custom properties | ## The commands - `/pretext-new [describe component] [react\|canvas\|svg\|server]` — scaffold a correct, polished pretext component. - `/pretext-review [file or code]` — audit existing pretext usage against the 11 pitfalls + typography. - `/pretext-demo [effect] [react\|canvas\|svg]` — generate a polished demo in the upstream house style. - `/pretext-explain [layout need]` — "which API/approach do I use?" with a verified sketch. ## The workflows (multi-agent) Plugins can't auto-register workflows, so run them explicitly with the Workflow tool (or copy into `.claude/workflows/`): ```js // design → implement → 4-lens review → verify a polished feature Workflow({ scriptPath: "/Users/clubpenguin/Documents/pretexter/workflows/pretext-build.js", args: { task: "a chat bubble that shrink-wraps to its text", target: "react", root: "/Users/clubpenguin/Documents/pretexter" } }) // find every pretext usage in a codebase, check vs pitfalls, adversarially verify Workflow({ scriptPath: "/Users/clubpenguin/Documents/pretexter/workflows/pretext-audit.js", args: { target: "/path/to/your/src", root: "/Users/clubpenguin/Documents/pretexter" } }) ``` ## The MCP server A bundled stdio MCP server that serves the canonical knowledge to any connected agent. **Phase 1 (shipping)** needs no browser and runs anywhere: | Tool | Does | |---|---| | `pretext_api_reference` | the verified API (optionally filtered by query) | | `pretext_recipe` | a vetted recipe for a task (23 available) | | `pretext_pitfalls` | the footgun catalog (optionally filtered) | | `pretext_lint` | static lint of pretext code for the 11 footguns — line numbers + fixes, never executes | | `pretext_catalog` | lists tools, recipes, pitfalls, resources | | `pretext_layout_run` | **Phase 2 (gated)**: real `{height, lineCount, lines, maxLineWidth}` via headless Chromium — ground-truth numbers | | `pretext_glyph_metrics` | **Phase 2 (gated)**: Canvas TextMetrics + per-grapheme advances + DOM Range boxes + optional HarfBuzz glyph shaping | | `pretext_render_preview` | **Phase 2 (gated)**: lays out + renders text in real Chromium and returns a **PNG** you can see | | `pretext_font_fallback` | **Phase 2 (gated)**: measures a web font + fallback in real Chromium → emits zero-CLS `@font-face` `size-adjust`/`ascent-override` CSS | Resources: `pretext://api`, `pretext://pitfalls`, `pretext://typography`, `pretext://recipes/<name>`. **Connecting:** - **Claude Code (with the plugin):** automatic — enabling the plugin registers it. - **Claude Code (standalone):** ```sh claude mcp add pretext -e PRETEXT_KNOWLEDGE_DIR=/Users/clubpenguin/Documents/pretexter/knowledge \ -- node /Users/clubpenguin/Documents/pretexter/mcp/dist/server.js ``` - **Cursor / other stdio clients** (`mcp.json`): ```json { "mcpServers": { "pretext": { "command": "node", "args": ["/Users/clubpenguin/Documents/pretexter/mcp/dist/server.js"], "env": { "PRETEXT_KNOWLEDGE_DIR": "/Users/clubpenguin/Documents/pretexter/knowledge" } } } } ``` The server ships as a single self-contained `mcp/dist/server.js` (all deps bundled) — **zero install, plain `node`**. See [`mcp/README.md`](mcp/README.md) for Phase 2. ## Develop ```sh node scripts/check.mjs # repo invariants: 0 invented APIs, links resolve, hub routes, pitfalls valid bun test lib/ # the pure layout kit (place-runs, balance, css-sync, knuth-plass, …) cd mcp bun install # dev only — Phase-1 runtime needs nothing (bundle is self-contained) bun test # linter + Phase-2 disabled-path tests (no browser) bun run build # rebuild dist/pretext-browser.js + dist/server.js bun run scripts/smoke.ts # end-to-end MCP smoke test under plain node # Enable Phase 2 (real headless-Chromium layout via pretext_layout_run): bun add playwright && bunx playwright install chromium bun run test:layout # PRETEXT_ENABLE_LAYOUT=1 — exercises real layout in Chromium ``` When you change pretext knowledge, **edit `knowledge/` once** — skills and the MCP both read it (see [`AGENTS.md`](AGENTS.md)). ## Credits & license Built on [`@chenglou/pretext`](https://github.com/chenglou/pretext) by Cheng Lou — huge thanks for a library that's a joy to build on. The vendored reference snapshot and its provenance are in [`reference/`](reference/PROVENANCE.md). This toolkit is **MIT-licensed** — take it, fork it, learn from it, build something with it. No strings. If you make something cool, I'd love to hear about it. Thanks for stopping by. Go make some beautiful text. ✦