Hellbox: Complete Feature Reference

How Hellbox Works

Hellbox (formerly Font Proof) is a native macOS app for creating font proofs, the typographic test documents that type designers use to evaluate their work in progress. The core idea is simple: what you see is what you get.

Live PDF Rendering

Everything in Hellbox is rendered as a live PDF. The proof document is a real PDF that updates in real-time as you change settings, swap fonts, or edit content. This isn’t a web preview or a rough approximation; it’s the same CoreText rendering pipeline that produces the final exported PDF. What you see on screen is exactly what you’ll get in print.

The PDF viewer supports single page, two-page, and continuous scroll display modes with zoom from 10% to 1000%.

Document Structure

A Hellbox document (.fontproof) is a JSON file containing one or more sections. Each section has its own type (Simple, Waterfall, Glyph Set, etc.), its own text content, and its own independent typography settings. Sections are displayed sequentially in the proof, and each section generates one or more pages depending on content length and the “overflow to multiple pages” setting.

Fonts are selected at the document level and shared across sections. By default, each section renders a separate page for each selected font. Sections can override this with per-section font selection, font disabling, or inline font mixing.

Page layout (dimensions, margins, header position) is set at the document level. Dozens of presets are available (Letter, A4, device screens, etc.) or you can specify custom dimensions.

The Workflow

Create a new document or use a template
Add fonts — from the system, imported files, or directly from Glyphs.app
Add sections — choose a type, enter or link content, adjust typography
The proof renders live as you work
Export to PDF for print or markup

Hellbox is designed to stay open alongside your font editor. With Live Reload enabled, changes you make in Glyphs are reflected in the proof within seconds.

Live Glyphs Integration

What it is: Hellbox connects directly to Glyphs.app via a native Objective-C bridge (NSConnection). When you select a Glyphs font in Hellbox, the app exports and registers that instance in real-time.

How it works:

Monitors open Glyphs documents for changes (font edits, instance changes, document open/close)
Exports instances to a temp directory and registers them with CoreText
Tracks instances by index (not just name) to handle duplicate style names
Debounced reloads prevent redundant exports during rapid edits
Sleep/wake handling avoids stale IPC connections
Toggleable via “Live Reload” switch in toolbar
Supports “Install for Testing” fonts from Glyphs as a separate source

What it’s for: Type designers working in Glyphs can see their changes in a professional proof layout instantly, without exporting, installing, or refreshing anything.

Section Types

Hellbox documents are composed of sections. Each section has its own type, content, typography settings, and font selection.

Simple

Simple text layout. Content is rendered with the selected fonts. With more than one font, choose how they lay out: one page per font (Page break), each font’s text stacked one after another in a single flow (Line break), or word-mixed in one flow (Mix). Supports multi-page overflow, word wrap, and all typography controls.

Waterfall

Size progression display. The same text is rendered at multiple point sizes in a single view. Default sizes: 8, 12, 18, 24, 32, 48, 72, 96pt. Sizes are fully customizable. Optional size labels (“12pt”, “18pt”) and fixed column width for text wrapping.

Columns & Rows

Grid layout with up to 6+ columns and multiple rows. Two content flow modes:

Continuous: text flows across all cells
Repeated: the same text in every cell (for comparing typography settings)

Per-cell overrides: every cell inherits the section’s settings until you change one. Select a cell and edit any control, font size, line height, letter spacing, alignment, text direction, orientation, case, font, OpenType features, or its content, and that change becomes the cell’s own override while the rest keep inheriting. A Section/Item breadcrumb shows the active scope, and a reset returns a cell to the section value. A cell’s content can be overridden even when the section text is linked to a file, and a blank cell is allowed. Lay variations out side by side, for example column 1 with ss01 on and column 2 with it off. Supports cell merging for complex layouts and optional grid labels.

Compare Styles

Side-by-side font/style comparison. Fonts are displayed in rows or columns. Dynamic column count calculated from content width (min 120pt per column, max 6). Intelligently paginates when fonts don’t fit on a single page.

Glyph Set

Character repertoire display in a grid, with metric lines, glyph names, and Unicode code points.

Three “Show” modes: Typed text (only glyphs in the section content), Every glyph (the full repertoire), and Glyphs with alternates (every glyph that has stylistic alternates)
“With alternates” layout groups each glyph with its stylistic alternates, side by side
Separate or Combined styles: lay out one block per font/style, or stack every style together for direct comparison
Character name and Unicode code point labels below each glyph (toggleable)
Metric lines: baseline, x-height, cap-height, ascender, descender
Two metric line styles: individual (per-glyph) or continuous (reference lines)
WCAG-compliant contrast calculation for metric line opacity

Markup

Frozen PDF snapshot with freehand annotation overlay. Captures a page as a static image, then allows drawing and text annotations on top.

Drawing tools:

Pen tool (freehand strokes)
Text tool (click-to-place text boxes)
Select tool

Markup controls:

Stroke width: 1, 2, 3, 5, 8, 12, 20pt
Color picker for pen and text
Text formatting: font size (1–999pt), bold, italic, alignment (left/center/right)
Undo support (Cmd+Z)
Keyboard shortcuts: V (select), P (pen), T (text), Cmd+Return (done), Escape (cancel)

What it’s for: Annotating proofs with design feedback — circling problem areas, noting kerning issues, writing revision comments directly on the proof.

Typography Controls

Every section type has access to these typography controls (some section-specific):

Core Typography

Font size — spinner + text field input
Line height — multiplier (1.0–2.0 typical range)
Letter spacing — horizontal and vertical (in ems), separate controls for CJK vertical text
Paragraph spacing — space after paragraphs (in ems)
Word wrap — toggle on/off
Kerning — toggle on/off (kern feature)

Case Transforms

Unchanged, UPPERCASE, lowercase, Title Case
Scope control: Latin-only vs. all scripts (handles Turkish i, Greek sigma, etc.)

Alignment

Auto (script-aware — Arabic/Hebrew right-align, Latin left-aligns)
Start, Center, End, Justify
Maps correctly to NSTextAlignment based on detected text direction

Text Direction & Orientation

Direction: auto (content-based detection), LTR, RTL
Orientation: auto, horizontal, vertical-left, vertical-right
Force upright in vertical: keeps Latin characters upright in CJK vertical text (overrides W3C rotation standards)

Language & Script

Language tag support: auto-detect, Arabic (ar), Farsi (fa), Hebrew (he), Japanese (ja), Korean (ko), Simplified Chinese (zh-Hans), Traditional Chinese (zh-Hant), German (de), Turkish (tr)
Proper text shaping via CoreText for each language
Numeral systems: default, Arabic-Indic, Extended Arabic-Indic, Latin

OpenType Feature Support

Comprehensive OpenType feature management with 70+ features organized by category:

Feature Management

Per-font, per-section feature toggling
Per-grid-item feature toggling in Columns & Rows (each cell renders its own feature set, for side-by-side feature comparisons)
Robust OpenType table parsing to detect available features
Glyph-based feature verification (compares glyph IDs before/after)
Custom feature names extracted from font’s name table
“Reset to Defaults” and “Apply to Family” actions
Feature state persisted per document

Font Management

Font Sources

System — all macOS installed fonts via NSFontManager
Glyphs — from open Glyphs.app documents (live reload capable)
Test Install — fonts exported from Glyphs via “Install for Testing”
Imported — manually imported .otf, .ttf, .ttc, .var files via file picker

Variable Font Support

Axis detection and display via CTFontCopyVariationAxes
Axis values stored per font instance (e.g., wght=500, wdth=75)
WWS name table integration (Name ID 21/22 preferred over computed axes)
Per-instance axis presets from Glyphs
Named-instance selection: adding a .designspace (or variable font) with multiple named instances prompts you to choose which to proof, all on by default with Select/Deselect All; each chosen instance becomes its own proof row

Font Sorting

Document order (global default)
Manual (drag-to-reorder)
Weight (parsed from style string)
Alphabetical
Date added
Per-section override with independent sort order
Ascending/descending direction

Per-Section Font Control

Disable specific fonts per section (hide without removing)
Section-specific font override (use different fonts than global selection)
Per-section font ordering
Solo mode: focus on a single font across all sections

Inline Styling & Font Mixing

When a section has more than one font, a Page break / Line break / Mix control decides how they lay out:

Page break (default)

No tag processing. Each font gets its own page(s).

Line break

Each font’s content is stacked one after another in a single continuous flow, rather than a page per font. On Simple and Waterfall sections, the page header lists only the fonts that appear on each page.

Mix: Auto

Auto-generates <fN> tags to distribute multiple fonts across text by weighted probability. Configurable per-font mix weights (e.g., 50% base font, 30% second, 20% third). Seeded random distribution for reproducible output. Useful for simulating real-world text with multiple weights.

Mix: Manual

User types <b>, <i>, <u> tags directly in content. Parser converts to font substitution (bold tag → bold weight, italic tag → italic style). Supports [Family-Style:text] single-token syntax for explicit font assignment.

Linked Files

Section-Level Linking

Link external text files to any section. Content auto-refreshes when the file changes.

Supported formats: .txt (plain text), .rtf (rich text → inline tags), .md/.markdown (markdown → inline tags)
File watching: vnode events + parent directory monitoring + NSFilePresenter + 1-second polling fallback
Atomic save detection: 0.25s buffer for editors that write-then-rename
Security-scoped bookmarks for sandboxed file access

Per-Grid-Item Linking

In Columns & Rows sections, each grid cell can link to a different external file. Independent watchers per cell.

PDF Export

Rendering Pipeline

Dedicated renderers per section type: PDFTextRenderer, PDFWaterfallRenderer, PDFColumnsRenderer, PDFStyleComparisonRenderer, PDFGlyphGridRenderer, PDFMarkupRenderer. All coordinated by PDFProofGenerator.

Appearance Modes

Built-in: Light (white bg), Dark (dark bg/white text), Sepia (warm cream), High Contrast
Custom modes: user-defined background/foreground colors, stored in UserDefaults
Alt+click to flip foreground/background colors
Per-document mode override

Page Dimensions

Paper presets: Letter, A4, A5, A6, Tabloid
Device presets: MacBook Air, MacBook Pro 14”/16”, Desktop, Slides 16:9/4:3, iPad (all models), iPhone (all models)
Custom: arbitrary width x height in points
Margins: independent top, bottom, left, right

Headers & Footers

Section name, font name, font size, page number, date and time, or custom text in left/center/right slots
Independent top and bottom bands, each can be turned off
Active OpenType features line: lists the features enabled for the fonts on the page (e.g. “Features: salt, ss01”); printed on its own full-width line so long lists wrap, placeable at top or bottom
“Print only” option keeps the timestamp and features line off-screen but on the exported PDF

Export UI

Accessory panel in save dialog with appearance mode, page size, and margin options.

Fit to Page

One-click optimization that calculates the optimal font size, line height, and letter spacing to fill a single page. Uses binary search (0.5pt precision). Section-type-aware:

Simple: finds optimal font size
Waterfall: removes oversized entries
Columns: reduces font size, adjusts column count
Compare Styles: scales to target height
Glyph Set: adjusts font size for grid layout
Markup: no optimization (frozen snapshot)

Templates

Section Templates (.fps files)

Reusable section configurations saved as standalone JSON files. Include content, all typography settings, and section type.

System Templates (Built-In)

Predefined proof setups organized by category:

Hamburgers: Ha/Hh/HH spacing tests, Hamburgefonts, Hamburged Spacing/Trio
Spacing: basic character sets, spacing tests, trio spacing
Pangrams: 8 variants (Wizards, Waltz, Dwarf, Sphinx, Zebras, Boxing, Jackdaws, Liquor)
Kerning: I Ask Jeff, Kerning Trio, Extra Kerning Words, Furniture Characters
Diacritics: 26 language variants (Afrikaans through Turkish)
Script-specific: Greek, Cyrillic templates

Custom Templates

User-created, starred for quick access. Browse by category in the template picker.

Document Format

.fontproof (JSON-based, version 3)

Contains:

Sections (UUID-keyed content text)
Section names and ordering
Per-section typography settings (SectionFontSettings)
Enabled/selected fonts with axis values
Font ordering
Per-font, per-section OpenType feature toggles
Linked text sources (section-level and per-grid-item)
Markup data (strokes + text annotations + frozen PDF snapshots)
Page dimensions, margins, header position
PDF appearance mode

Backward compatible: auto-migrates from v0 (name-based sections) through v2 (UUID-based) to v3 (markup support).

.fps — Section Template

Standalone single-section JSON. Stores template name, description, category, content, settings, created date, starred flag.

.fpt — Proof Template

Full proof configuration template (all sections, fonts, settings, page dimensions).

Incremental zoom in/out with adaptive step sizing
Custom zoom input (10–1000%)
Presets: 50%, 100%, 200%, Zoom to Fit
Cmd+/Cmd- shortcuts, Cmd+0 for 100%
PDFKit-based viewer with single page, two-page, and continuous scroll modes
Section sidebar with optional thumbnails (letterboxed, 140x100px)
Drag-to-reorder sections in sidebar
Section right-click: rename, duplicate, delete, create from template

Performance

CTFont cache: 5,000-entry limit with auto-eviction
Auto-styled text cache: avoids redundant tag generation
Feature detection cache: thread-safe per-font caching
Font data cache: binary font data cached per-font
Deferred section loading: large documents load sections incrementally
Render snapshots: main thread prepares state snapshot, PDF generated on background thread
CoreText workaround: splits attributed strings at 10,240 UTF-16 units to avoid feature loss
Page safety limit: 100,000 pages per section max

Licensing & Updates

Trial

14-day free trial, one per machine (hardware UUID tracking)
Anti-tampering: hash verification on trial start date
No credit card required

License Activation

LemonSqueezy API integration (activate, validate, deactivate)
Machine-specific activation with instance tracking
License key + instance ID stored in macOS Keychain
Validates on every launch with 100-year offline grace period
License states: unlicensed, trial (with expiry), licensed, expired

Auto-Updates

Sparkle framework (SPUStandardUpdaterController)
EdDSA-signed ZIP archives hosted on GitHub Pages
Configurable check interval
Appcast feed at jakefleming.github.io/font-proof-swift/appcast.xml

Window & App Management

Multiple document windows (standard macOS document-based app)
Dedicated font manager window
Dedicated markup editor window
Floating activation/registration windows
Global file drop overlay (drag fonts or text files onto app)
Standard macOS “Open Recent” menu
macOS 14 (Sonoma) or later required

Keyboard Shortcuts

Shortcut	Action
Cmd++ / Cmd+-	Zoom in/out
Cmd+0	Zoom to 100%
Cmd+Z	Undo
Shift+Cmd+Z	Redo
Cmd+Return	Done (markup editor)
Escape	Cancel (markup editor)
Cmd+R	Refresh fonts
V	Select tool (markup)
P	Pen tool (markup)
T	Text tool (markup)

MCP Server (Claude Code / AI Integration)

Hellbox includes a built-in MCP (Model Context Protocol) server that lets AI tools like Claude Code create and modify proofs programmatically. The server binary (font-proof-mcp) is embedded in the app bundle.

Architecture: File-based, standalone. Creates and modifies .fontproof files (JSON) directly; the app doesn’t need to be running. Uses stdio transport for Claude Code and MCP clients. Can open results in the app via fontproof:// URL scheme.

Exposed Tools

Document tools:

create_proof — create empty .fontproof with page settings, margins, headers
open_proof — read full document contents
get_proof_info — get metadata without full content
open_in_app — open file in Hellbox for live PDF rendering
create_complete_proof — create full document with fonts + sections in one call

Section tools:

add_section — add new section (any type)
update_section — modify name, content, type, or settings
delete_section — remove section
reorder_sections — change display order
duplicate_section — copy existing section
set_section_content_bulk — update content for multiple sections at once
update_section_settings — modify all typography settings (font size, line height, letter spacing, alignment, direction, orientation, OpenType features, waterfall sizes, grid layout, etc.)

Font tools:

add_fonts — add system fonts (with variable font axis support)
remove_fonts — remove fonts by family + style
list_system_fonts — enumerate installed fonts with optional filter
find_fonts_for_script: list installed font families that fully cover a given script (japanese, simplified-chinese, traditional-chinese, korean, cjk, hebrew, arabic, thai, devanagari, latin, cyrillic, greek) or an explicit sample of characters, for multilingual and CJK proofing

Export and inspection tools:

export_proof: render a document to a PDF file
render_proof_pages: render each page of a proof to a PNG image for visual inspection
validate_proof_layout: report page dimensions, coverage issues (per section and font, characters with no glyph that fall back or render tofu), and overflow issues (sections clipped because overflow to multiple pages is off)

Glyphs integration tools:

list_glyphs_fonts — query open Glyphs documents, families, and instances
add_glyphs_fonts — add specific instances from Glyphs document to proof

Glyphs Bridge

The MCP server communicates with Glyphs 3 via a Python bridge script using NSConnection (Mach IPC). It queries open documents and available instances without modifying the Glyphs project.

Two Implementations

Swift (primary) — native macOS binary built via SPM, embedded in app bundle at Contents/Helpers/font-proof-mcp, codesigned with the app
TypeScript (reference) — Node.js implementation using the official MCP SDK, runs standalone via npm

What This Enables

Claude Code can create type specimens from scratch, build Goldilocks tracking comparisons, construct multilingual proofs, toggle OpenType features, test variable fonts at specific axis values, and update content across sections, all programmatically. Results open instantly in Hellbox for live PDF rendering.

Debug & Developer

Toggleable os.log categories: PDF, Fonts, Glyphs, UI, OpenType, Templates, General
Accessible from Settings