Debugging OpenType Layout

Trace a shaping run to see which lookups act on the text and in what order. Use the Lookups panel to locate the rule, then inspect its actual input, output, and caller.

Open Window > Panels > Lookups for the intended font and switch to Debugger with the button beside the script and language controls. Keep the desired Lookups document available before recording a trace.

Tracing a Lookup Run

Use the debugger to find the operation that changes a glyph, fails to match, or reverses an earlier change. It runs the Lookups document through HarfBuzz. An unchanged imported document can use its retained binary tables; edited rules need a private build. Running a trace does not publish that build to the Glyph window or replace Features-panel code.

  1. Open Debugger beside the Script and Language selectors.
  2. Check the features to test in the feature list. Selecting a feature row filters the browser; its checkbox controls the debugger selection.
  3. Enter ordinary text, such as fi, and press Enter or click the return-arrow button. For exact glyph input, use adjacent names such as /f/i or /a.alt, without adding separator spaces. Use /space when the glyph-name sequence needs an explicit space glyph.
  4. Select a lookup row to inspect its output. Use the forward, back, and play controls to follow changes. Double-click a row, or use Edit lookup in its context menu, to open the definition.
  5. Click Result to see the completed shaping result, then test the same feature with different input and surrounding text.

Leave Script shaping on when judging normal text. HarfBuzz applies its processing for the selected script, including default or required features, together with the checked features. Turn it off to isolate the checked features without script-specific joining and reordering. This diagnostic mode can produce text that would be unsuitable for ordinary use; restore Script shaping when checking the complete behavior.

The trace records executions, so a lookup can appear more than once. Context, substitution, and positioning icons identify the kind of operation. Gray rows made no change: forward, back, and play skip them, but you can click them to inspect their output. The context menu can reveal unchanged automatic lookups or restrict the list to changed steps. A contextual caller may remain visible to explain a changed child even when the caller has no net effect.

The debugger has one output preview. It shows the state after the selected invocation; Result includes final positioning and shaping work outside the individual lookup rows. Right-to-left output is aligned to the right. In this preview, blue highlights glyphs affected by the selected step; it does not indicate class membership as it does in the rule preview.

Read the metrics

Expand Metrics when the outlines alone do not explain the result. Values are in font units.

Field What to inspect
Glyph / ID The glyph name and its identifier in the compiled font.
Input # The original input position, counted from zero. Each /glyphName token counts as one input symbol.
Spacing X / Y The advance that moves the origin for the next glyph.
Shift X / Y The placement offset of the current glyph.

A dash means positioning has not yet supplied a value at that stage. For attached marks, inspect Result as well as the lookup step: the completed shaping pass can resolve attachment relationships after an individual lookup returns.

Features-panel text enters this debugger only through import into the Lookups document. To make the tested visual document supply normal previews and font export, choose Compile in Lookups. The last successful compilation in Lookups or Features selects which document supplies those builds; see Importing and Exporting Feature Files.

A contextual trace includes the caller and any child lookups it actually invokes. Selecting a child shows that invocation’s output; the caller’s output includes its children’s completed work. An uncalled child has no execution to show. The same lookup can therefore appear several times with different inputs during a run.

For a substitution that appears to undo itself, follow the ChangeA/RestoreA example in Substitution Lookups. For marks whose offsets become meaningful only after attachment is resolved, inspect Result and consult Mark Features and Export.