Glove80 Layout Toolkit

This repository is the canonical, code-first source of the Glove80 layout families (Default, TailorKey, QuantumTouch, and Glorious Engrammer). Every release JSON under layouts/*/releases can be regenerated deterministically from the declarative specs and metadata checked into src/glove80.

Why this exists: TailorKey (and now QuantumTouch, Glorious Engrammer, etc.) used to be kept in sync by hand in the layout editor, which made even trivial tweaks error-prone and slow to propagate across Windows/macOS/Dual/Bilateral variants. By expressing every layer, macro, combo, and alpha layout in Python, we get reproducible builds, automated regression tests, and the ability to spin up new variants (Colemak, Colemak-DH, Dvorak, custom mixes) by reusing the same building blocks instead of copying JSON around. You can still download the generated JSON into the editor for visualization, but the code here is the single source of truth that guarantees consistency.

Highlights

• The default, TailorKey, QuantumTouch, and Glorious Engrammer families live under src/glove80/families/ with typed specs, factories, and regression tests.
• Metadata travels with the package (src/glove80/families/*/metadata.json), so the CLI and library always agree on UUIDs, release notes, and output paths.
• A Typer-powered CLI (glove80 generate …) replaces ad-hoc scripts and keeps the regeneration workflow uniform across layouts.
• Release artifacts are grouped under layouts/<layout>/releases, keeping the repo root clean while preserving the published JSON verbatim.
• Reusable "feature" helpers under glove80.features (e.g., bilateral_home_row_components) bundle macros plus ready-made layers so you can drop complex behaviors into custom layouts without spelunking through family internals.
• Third-party packages can register additional families via the glove80.layouts entry-point group, so custom specs integrate without forking this repo.

Quick Start

1. Install dependencies (the repo uses uv):

   uv sync
   

2. Regenerate every release JSON:

   just regen
   

3. Run the full regression suite (per-layer tests + layout parity checks):

   just ci
   

4. Need a single variant? Use the CLI directly:

   glove80 generate --layout tailorkey --variant mac
   

just --list shows the available helper tasks.

Using the Python API

The public API lives on the root package:

from glove80 import (
    build_layout,
    list_families,
    apply_feature,
    bilateral_home_row_components,
)

print(list_families())  # ['default', 'tailorkey', 'quantum_touch', 'glorious_engrammer']
layout = build_layout("tailorkey", "mac")
components = bilateral_home_row_components("mac")
apply_feature(layout, components)

build_layout(<family>, <variant>) returns the same dictionary that the CLI writes into layouts/<family>/releases/….

Minimal Example (<10 lines)

from glove80 import build_layout, apply_feature, bilateral_home_row_components

layout = build_layout("tailorkey", "windows")
apply_feature(layout, bilateral_home_row_components("windows"))
# now `layout` contains the merged macros/layers and can be serialized

CLI Tips

• Validate any layout JSON: glove80 validate path/to.json
• Override output destination: glove80 generate --layout tailorkey --variant windows --out /tmp/out.json
• Families list: glove80 families
• Scaffold a starter spec file: glove80 scaffold src/glove80/families/custom/specs.py --layout custom --variant beta

Notes:

• The CLI accepts glorious-engrammer as an alias for glorious_engrammer.

Repository Layout

.
├─ layouts/                     # checked-in release JSON + layout-specific README.md files
│  ├─ default/
│  │  └─ releases/
│  ├─ tailorkey/
│  │  └─ releases/
│  ├─ quantum_touch/
│  │  └─ releases/
│  └─ glorious-engrammer/
│     └─ releases/
├─ docs/                        # architecture overview
├─ src/glove80/
│  ├─ cli/                      # Typer CLI
│  ├─ layouts/                  # registry, common helpers, CLI wiring
│  └─ families/                 # default, TailorKey, QuantumTouch, Glorious Engrammer implementations + metadata
│     ├─ default/
│     ├─ tailorkey/
│     ├─ quantum_touch/
│     └─ glorious_engrammer/
└─ tests/                       # split by layout family

• Read docs/architecture.md for a walkthrough of the data flow and regeneration pipeline.
• layouts/default/README.md, layouts/tailorkey/README.md, layouts/quantum_touch/README.md, and layouts/glorious-engrammer/README.md explain how each layout family is structured, the available layers, and the steps for adding new variants.

CI Contract

.github/workflows/ci.yml runs the same steps you do locally:

• just regen must leave layouts/*/releases unchanged or the build fails, proving the checked-in JSON matches the current code.
• just ci (uv run pytest) covers every layer factory plus whole-layout comparisons.
• Pull requests are required to keep both commands clean, so regeneration plus tests are the only gatekeepers.

Contributing

1. Edit specs or metadata, re-run just regen, and inspect the resulting diffs under layouts/.
2. Extend/adjust the targeted per-layer tests under tests/<layout>/ when you change behavior.
3. Document intentional changes in the relevant layouts/<family>/README.md (and docs/architecture.md if the pipeline changes) so future contributors understand the rationale.