PretextPlugin

A Claude Code plugin that gives Claude deep understanding of pretext — a pure TypeScript library for DOM-free multiline text measurement and layout.

Pretext is too new (March 2026) for LLMs to know. This plugin bridges that gap with injectable skills, an MCP server with 5 runtime tools, and a 12-file curated knowledge base.

How It Works

                      Claude Code
                          |
           +--------------+--------------+
           |              |              |
       Skills (3)    Agent (1)    MCP Server (5 tools)
           |              |              |
           v              v              v
     Context injection  Multi-step   Runtime execution
     on activation      reasoning    & validation
           |              |              |
           +--------------+--------------+
                          |
                   Knowledge Base (12 files)
                   API | Architecture | Scripts
                   Edge Cases | Browser Compat

Skills inject pretext knowledge into Claude's context. The MCP server provides runtime tools for code execution, validation, and documentation lookup. The agent handles complex multi-step questions by combining both.

Quick Start

# Install from source
git clone https://github.com/AdrianV101/PretextPlugin.git
claude plugin install ./PretextPlugin

Once installed, ask Claude about pretext and it will automatically activate the plugin's skills and tools:

"How do I use pretext to measure text height on resize?"

Features

Skills

Skill	Activates When	What It Provides
pretext	User asks about pretext APIs, patterns, usage	Mental model, API decision tree, code patterns, 9 critical pitfalls
pretext-debugging	User debugs measurement or layout issues	Diagnostic flowchart, mismatch taxonomy, browser-specific fixes
pretext-i18n	User works with non-Latin text (CJK, Arabic, Thai...)	Per-script accuracy data, locale configuration, known limitations

Skills activate automatically based on conversation context — no slash commands needed.

Agent

The pretext-advisor agent handles complex architectural questions that span multiple knowledge domains — like designing non-rectangular text wrapping with virtualized rendering, or diagnosing Arabic measurement mismatches across browsers.

MCP Tools

Tool	Purpose	Example Use
pretext_run	Execute text layout, get line count and height	Test layout parameters before writing code
pretext_measure	Analyze text segmentation and per-segment widths	Debug why text wraps at an unexpected point
pretext_validate	Check code for 9 common anti-patterns	Catch system-ui font, inlined prepare(), wordBreak/letterSpacing misuse, rich-inline confusion
pretext_explain	Search the knowledge base by topic	Look up architecture, browser compat, edge cases
pretext_source	Read pretext source code by module/function	Understand internal behavior

By default, pretext_run and pretext_measure execute in structural mode — a canvas shim provides deterministic width estimates without a real browser, which is fast and reproducible but approximate.

pretext_run

Executes a pretext layout and returns line count and total height. Defaults to structural mode.

Accurate mode (opt-in): Set mode: 'accurate' to run in a real headless browser for pixel-precise font metrics. Useful for debugging cross-browser divergence or shaping-context issues where structural mode's approximate widths diverge from real browsers. Requires Playwright:

bun add playwright
bunx playwright install chromium  # or firefox, or webkit

Select the engine with browser: 'chromium' | 'firefox' | 'webkit' (default: chromium).

pretext_measure

Returns per-segment widths and segmentation details for a given text/font. Defaults to structural mode (canvas shim).

Accurate mode (opt-in): Set mode: 'accurate' to run in a real headless browser for pixel-precise font metrics. Useful for debugging cross-browser divergence or shaping-context issues where structural mode's approximate widths diverge from real browsers. Requires Playwright:

bun add playwright
bunx playwright install chromium  # or firefox, or webkit

Select the engine with browser: 'chromium' | 'firefox' | 'webkit' (default: chromium).

Knowledge Base

12 curated reference files covering pretext's full surface area, served to Claude via the pretext_explain tool:

• api-reference.md — Complete API signatures and types
• architecture.md — Two-phase design, internal data structures, caching
• common-mistakes.md — Anti-patterns with detection and fixes
• mismatch-taxonomy.md — Why pretext/browser measurements can differ
• browser-compat.md — Chrome, Safari, Firefox behavior differences
• script-matrix.md — Per-script accuracy (Latin, CJK, Arabic, Thai, and 8 more)
• edge-cases.md — Zero-width chars, long words, empty strings, tabs
• modules/ — Deep dives into source modules (analysis, measurement, line-break, layout, bidi, rich-inline)

Development

Prerequisites: Bun >= 1.0

cd mcp-server && bun install        # Install dependencies
cd mcp-server && bun test           # 109 pass + 6 gated on PRETEXT_ACCURATE_TESTS=1
cd mcp-server && bun run index.ts   # Start MCP server (stdio)

Project Structure

.claude-plugin/plugin.json   Plugin manifest
skills/                      3 skill definitions
agents/                      1 agent definition (pretext-advisor)
mcp-server/                  Bun MCP server with 5 tools
knowledge/                   12 reference files
pretext-bundled/             Bundled pretext v0.0.6 dist (incl. rich-inline)

How It Was Built

PretextPlugin was built through a four-phase process:

1. Structured Reading — 8 research notes analyzing pretext's source code, architecture, and API surface
2. Empirical Validation — 23,040 browser tests across Chrome, Safari, and Firefox confirming accuracy for 12 scripts. ~92% of Phase 1 findings confirmed; the rest corrected
3. Knowledge Architecture — Plugin design spec with 6 architectural decisions (structural vs. accurate mode, knowledge granularity, tool boundaries)
4. Implementation — 3 skills, 1 agent, MCP server with 5 tools, 12-file knowledge base, 92 tests

Contributing

Contributions are welcome. To get started:

1. Fork the repository
2. Create a feature branch
3. Run cd mcp-server && bun test to ensure tests pass
4. Open a pull request

For bug reports or feature requests, open an issue.

License

MIT — see LICENSE.