Glyphs Light Table

Light Table API

Git version control for Glyphs via the Light Table plugin (com.formkunft.LightTable). The plugin extends GSFont, GSGlyph, and GSLayer with lt_* attributes that bridge through a private _LightTableInterface Obj-C singleton.

Use this skill whenever the question involves the plugin's version-history surface — checking modification state, listing past commits, loading an older font snapshot, or restoring a single glyph from history.

Path Resolution

${GLYPHS_LIGHT_TABLE_PATH:-~/Library/Application Support/Glyphs 3/Repositories/Light-Table}

API source: {path}/Python API/lighttable/__init__.py

If GLYPHS_LIGHT_TABLE_PATH is unset, the default Glyphs 3 install location is used. The skill exits with a clear error if neither location holds the plugin.

Scripts

> Run all scripts from this skill's base directory. Prepend the base directory path to scripts/ when executing.

| Script | Purpose | Output | |--------|---------|--------| | read_api.py | Parse/search Light Table Python API | JSON: types, extensions, ObjC selectors |

Usage

# List all types and extensions
python3 scripts/read_api.py

# Detail for a specific type (enum, GS class, ObjC class, dataclass)
python3 scripts/read_api.py DocumentState
python3 scripts/read_api.py GSFont
python3 scripts/read_api.py RestorationInfo

# Search across all types
python3 scripts/read_api.py --search "restore"
python3 scripts/read_api.py --search "version"

Core concepts

Two state enums

| Enum | Scope | Values | Used by | |---|---|---|---| | DocumentState | Font-level repo status | OPERATIONAL, UNINITIALIZED, UNAVAILABLE, … | font.lt_document_state | | ObjectStatus | Per-glyph / per-layer modification | UNCHANGED, MODIFIED, ADDED, REMOVED | glyph.lt_status, layer.lt_status |

A font must reach DocumentState.OPERATIONAL before any other lt_* call returns meaningful data.

Bridge architecture

• import lighttable monkey-patches GSFont, GSGlyph, and GSLayer with lt_* attributes
• All lt_* properties and methods route through the private _LightTableInterface Obj-C singleton
• Python's _ separator maps to Obj-C : (see selector mapping below)

Restoration vs. version loading

| Goal | Call | Scope | |---|---|---| | Load entire font at a past commit | font.lt_load_version(record, callback) | Whole document, replaces current view | | Get a handle to restore a single glyph | glyph.lt_restoration_info() → RestorationInfo | Glyph-level, surgical | | Restore one glyph from history | info.restore_glyph_as_replacement() | Single glyph, keeps rest of font intact |

Use lt_load_version for browsing; use RestorationInfo for cherry-picking changes.

Worked workflow — "Show me what's modified in this glyph since the last commit"

import lighttable
from lighttable import DocumentState, ObjectStatus

font = Glyphs.font

# 1. Guard: is the font actually under Light Table control?
if font.lt_document_state != DocumentState.OPERATIONAL:
    print("Font not in an operational Light Table repo.")
    return

# 2. Iterate glyphs and surface modifications
modified = [g for g in font.glyphs if g.lt_status == ObjectStatus.MODIFIED]
print(f"{len(modified)} modified glyphs:")
for g in modified:
    print(f"  {g.name}")

# 3. To roll back one glyph
target = font.glyphs["A"]
info = target.lt_restoration_info()
if info:
    info.restore_glyph_as_replacement()

This is the canonical pattern: check DocumentState first, then filter on ObjectStatus, then act with RestorationInfo for fine-grained restores.

Worked workflow — "List the last N commits and load one"

import lighttable

font = Glyphs.font
records = font.lt_available_records   # list[VersionRecord]

# Show last 5
for r in records[:5]:
    print(r.commit_summary, r.date)

# Load the second-most-recent
def on_loaded(success):
    print("Loaded:", success)

font.lt_load_version(records[1], on_loaded)

The callback runs asynchronously after Light Table finishes the load.

ObjC selector mapping

Python's _ maps to Obj-C :. Trailing _ keeps the trailing colon. Examples:

| Python | Obj-C selector | |---|---| | documentStateOfFont_ | documentStateOfFont: | | font_loadVersionForRecord_completionHandler_ | font:loadVersionForRecord:completionHandler: | | lt_restoration_info | (Python helper; no direct selector) |

Run python3 scripts/read_api.py and look at the objc_selector fields to see all bridges.

Common edge cases

• Light Table not installed → import lighttable raises ModuleNotFoundError. Catch and degrade gracefully.
• Font not in a Git repo → font.lt_document_state returns DocumentState.UNAVAILABLE or similar; do not proceed with history calls.
• Uninitialized state right after opening → some calls return None until the first index pass completes. Re-query after a short delay or wait for the relevant Light Table notification.
• lt_restoration_info() returns None → the glyph is unchanged or has no recoverable history; this is expected, not an error.
• lt_load_version callback never fires → ensure the script holds a strong reference to the callback; weak references get collected before Light Table's async load completes.

Cross-skill collaboration

| Question | Use this skill | Use instead | Reason | |---|---|---|---| | "What lt_* properties does GSGlyph have?" | ✅ | — | Light Table-specific surface | | "What does glyph.layers do (no lt_ prefix)?" | — | glyphs-python-api | Core Python API | | "What's the Obj-C selector for lt_load_version?" | ✅ | — | This skill exposes selector mapping | | "What's the Obj-C protocol of _LightTableInterface?" | partial | glyphs-objc-headers | Header search for the underlying protocol declarations | | "Where do I install Light Table?" | — | glyphs-packages | Plugin discovery + install |

Prerequisites

• Light Table installed in Glyphs 3 (com.formkunft.LightTable)
• Font in a Git repository
• Script runs in Glyphs context (import lighttable)

Reference

See [references/api-overview.md](references/api-overview.md) for architecture details, full Python↔ObjC mapping patterns, and ObjC runtime class list.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yintzuyuan
• Source: yintzuyuan/glyphs-reference
• License: MIT
• Homepage: http://erikyin.net/glyphs-reference/

Install and usage instructions live in the source repository linked above.