# Runebender Documentation Context

This file is a compact, AI-readable bundle of the public Runebender website documentation.

Runebender is a family of alpha font editor projects. Treat these notes as an orientation map, not a stable API contract.

## Canonical Sources

- Shared core source: https://github.com/eliheuer/runebender-core
- Native Xilem front-end source: https://github.com/eliheuer/runebender-xilem
- ComfyUI/Vue/WASM front-end source: https://github.com/eliheuer/runebender-comfy
- Canonical hyperbezier spec: https://github.com/eliheuer/runebender-xilem/blob/main/docs/hyperbezier-ufo-extension.md
- Earlier Runebender source: https://github.com/linebender/runebender
- Website source: not public yet.
- Historical site: https://runebender.app/ remains a historical project entry point while runebender.org becomes the current docs home.

## Current Facts

- Runebender Core is the headless Rust crate and CLI direction for non-UI font operations.
- Runebender Xilem is a native font editor front-end built with Rust and Xilem.
- Runebender Comfy is a ComfyUI/Vue/WASM front-end and node path.
- Xilem is a Rust UI framework from the Linebender ecosystem.
- Runebender Xilem is a port of the earlier Druid-based Runebender.
- The project family is described as very alpha and actively under development.
- Future Runebender front-ends may be added as the shared core grows.
- The Xilem source workflow is currently source-first: clone the repository and run with Cargo.
- The cloud editor is an experimental static standalone browser build from the Comfy path.
- `scripts/build-cloud-editor.sh` builds `../runebender-comfy/web` into `public/cloud/editor`.
- `scripts/sync-comfy-web.sh` copies `../runebender-comfy/web` into `public/cloud/runebender-comfy-web`.
- The Xilem README currently lists MSRV 1.88.
- The Xilem app can run with a file picker or open a specific UFO path.
- UFO is the source-font workflow named in the project README.
- Runebender Xilem supports background image import and autotrace workflows.
- img2bez is the local/offline tracing path.
- QuiverAI is an optional cloud tracing path requiring network access, API key, and API credits.
- QuiverAI configuration can come from `~/.config/runebender/config.toml` or `QUIVERAI_API_KEY`.
- Hyperbezier paths are smooth paths represented by on-curve points, with off-curve control points computed by a spline solver.
- Hyperbezier contours are marked in GLIF with `identifier="hyperbezier"`.
- The canonical hyperbezier spec lives in the Runebender Xilem source repository.

## Known Alpha Limits

- Tool behavior and keyboard shortcuts may change.
- Docs describe the shape of workflows rather than every UI state.
- Screenshots show current development state, not a final product surface.
- Use version control or backups when testing real UFO sources.
- Format behavior should be verified against the current source repository.
- Hyperbezier behavior is documented by the canonical source-repo specification.
- QuiverAI is optional and requires network access, an API key, and API credits.
- Traced outlines may need cleanup and metric adjustment.
- These docs should help people and agents find the right source files, commands, and concepts without freezing details that are still in flux.

## Xilem Capabilities

Runebender Xilem run path:

- Build from source by cloning the repository and running Cargo.
- `cargo run` opens a file picker according to the README.
- `cargo run -- assets/untitled.ufo` opens a specific UFO.
- `cargo run -- --verbose` runs with verbose logging.

Runebender Xilem editing:

- Select, Pen, Hyperbezier Pen, and Knife tools are listed in the README shortcut map.
- README shortcuts include duplicate, flip, rotate, nudge, copy, paste, reverse direction, and point type toggle.

Runebender Xilem tracing:

- Background image import is exposed through `Cmd/Ctrl + I`.
- Local img2bez tracing is exposed through `Cmd/Ctrl + T`.
- Refit existing outlines to a background image with `Cmd/Ctrl + Shift + T`.
- Optional QuiverAI tracing is exposed through `Cmd/Ctrl + Shift + Y`.
- Background image lock toggle is listed as `Cmd/Ctrl + L`.

Formats:

- UFO is the current source-font workflow named by the README.
- Hyperbezier on-curve path support is documented in the source repository.
- README lists `Cmd/Ctrl + Shift + H` to convert hyperbezier paths to cubic.
- Example sources include `assets/untitled.ufo` and `assets/hyper-matisse.ufo`.

## Roadmap

This site uses status lanes instead of dated release promises.

Documented now:

- Source-first Cargo workflow, file picker launch, open a UFO path, verbose logging.
- Select, Pen, Hyperbezier Pen, Knife, preview, zoom, transforms, and current shortcut lookup.
- Background image import, local img2bez tracing, refit, optional QuiverAI tracing.
- UFO orientation, GLIF concepts, hyperbezier identifier, cubic conversion path.
- Included UFO sources for first-run testing and hyperbezier inspection.

Needs verification before deeper public docs:

- Exact selection states, tool modes, and editing edge cases.
- Save behavior, round-tripping expectations, and compatibility with other UFO editors.
- Tracing parameters, image placement details, and backend-specific failure modes.
- Contributor test commands and expected verification workflow.
- Packaging, downloads, releases, and platform support.

Not promised:

- Finished binary downloads.
- Stable production file behavior.
- Complete handbook coverage of every interface state.
- Long-term shortcut stability.
- Compatibility guarantees for every downstream UFO editor.

## Documentation Model

The public docs use a mature font-editor documentation model:

- Start here: project family, current facts, alpha limits, roadmap.
- Shared concepts: glossary, UFO/GLIF/hyperbezier format notes, support, troubleshooting.
- Editor-specific docs: Xilem install/manual/tracing/shortcuts/source map, plus Comfy and headless Core landing pages.
- Task paths: tutorials, workflows, and how-tos that currently lean Xilem-heavy where detailed docs exist.

Because Runebender is alpha, docs should avoid over-specifying changing behavior.

## Tutorial Paths

Get started:

1. Read Current Facts and Alpha Limits.
2. Follow Install to build and run from source.
3. Open `assets/untitled.ufo`.
4. Use Reference only for shortcuts needed immediately.

Draw and edit:

1. Read Manual > Drawing for tool names and contour concepts.
2. Try Select, Pen, Hyperbezier Pen, and Knife on disposable source data.
3. Use preview, fit, and zoom while judging shape and spacing.
4. Check Capabilities for documented behavior versus moving alpha areas.

Trace an image:

1. Read Tracing.
2. Import and align a background image.
3. Use local img2bez tracing first when offline reproducibility matters.
4. Use QuiverAI only when cloud tracing and API credentials are acceptable.

Understand the format:

1. Read Format notes.
2. Use Glossary for UFO, GLIF, cubic, and hyperbezier terms.
3. Use the source repository spec for exact hyperbezier storage details.
4. Treat website docs as orientation unless the linked source says otherwise.

## How-to Recipes

Run with a file:

- `cargo run -- assets/untitled.ufo`
- Use Install for prerequisites.

Run with logs:

- `cargo run -- --verbose`
- Include checkout, command, UFO path, and expected behavior when reporting bugs.

Trace locally:

1. Import a background image.
2. Align and scale it against glyph metrics.
3. Use local img2bez tracing.
4. Clean up the resulting outlines manually.

Trace with QuiverAI:

1. Confirm cloud tracing is acceptable for the source image.
2. Configure an API key through the supported config path or environment variable.
3. Run the QuiverAI trace command from the app.
4. Review and clean up the generated outlines.

Convert hyperbeziers:

- Use `Cmd/Ctrl + Shift + H` when a downstream tool needs standard cubic outlines.
- Read Format notes and the canonical hyperbezier UFO extension spec first.

## Examples

Example UFOs in the current local source checkout:

- `assets/untitled.ufo`: Untitled Regular, useful for first run, navigation, broad glyph coverage, and ordinary UFO inspection. The current local checkout has 333 GLIF files.
- `assets/hyper-matisse.ufo`: Hyper Matisse Regular, useful for hyperbezier editing, conversion, and format behavior. The current local checkout has 9 digit GLIF files, each with a hyperbezier contour.

Open examples from the Runebender Xilem source root:

- `cargo run -- assets/untitled.ufo`
- `cargo run -- assets/hyper-matisse.ufo`

## Troubleshooting

Build or launch:

- Confirm a current Rust toolchain. The source README currently lists MSRV 1.88.
- Run commands from the root of `runebender-xilem`, not from the website repo.
- Try `cargo run` before adding file paths or verbose flags.
- Use `cargo run -- --verbose` when collecting issue details.

Opening UFOs:

- Use included examples first: `assets/untitled.ufo` or `assets/hyper-matisse.ufo`.
- Keep real font sources in version control before testing alpha editing behavior.
- Verify file paths relative to the source repo root.

Tracing:

- Import, align, and scale a bitmap before judging tracing output.
- Use img2bez first when offline behavior or reproducibility matters.
- QuiverAI requires network access, API credentials, and API credits.
- Expect traced outlines to need manual review and metric adjustment.

Reporting:

- Include source checkout, launch command, UFO path, expected behavior, actual behavior, and whether the problem affects tracing, cubic outlines, or hyperbezier outlines.

## Support

Primary channels:

- Editor source: https://github.com/eliheuer/runebender-xilem
- Editor issues: https://github.com/eliheuer/runebender-xilem/issues
- Editor pull requests: https://github.com/eliheuer/runebender-xilem/pulls
- Development discussion: https://xi.zulipchat.com/#narrow/channel/197075-runebender
- Website source: not public yet.

Use editor issues for build failures, crashes, UFO behavior, tracing behavior, tools, shortcuts, and format problems. Use Zulip for stale docs, broken links, unclear examples, agent-readable context files, early design discussion, and questions that are not yet issue-shaped.

## Architecture

Application flow:

- `src/main.rs` creates the Xilem event loop.
- `src/lib.rs` initializes logging, config, initial state, command-line loading, and the Xilem app.
- `AppState` drives the reactive UI and owns loaded workspace state, selection, active editor session, grid state, clipboard, and file-watch flags.
- When a font is loaded, the app presents glyph grid and editor tabs. Without a loaded font, it shows the welcome view.
- The tabbed view is wrapped with a file watcher that can reload workspace data after external UFO changes.

State model:

- `src/data/mod.rs` describes `AppState` as central application state.
- `workspace` holds direct UFO workspace state.
- `designspace` is reserved for designspace project state.
- `editor_session` and `welcome_session` hold active editing contexts.
- `active_tab`, selected glyph data, grid scroll state, and category filters drive navigation.

Editing layers:

- `src/editing/` contains local interaction modules for background images, hit testing, mouse behavior, tracing, QuiverAI, viewport helpers, and edit sessions.
- Shared editing concepts from `runebender-core` are re-exported through `crate::editing`.
- `src/tools/` contains tool implementations for Select, Pen, HyperPen, Knife, Measure, Shapes, Text, and Preview.
- `ToolBox` wraps the active tool and delegates mouse, paint, and edit-type behavior.

Data and geometry:

- `src/data/`: editor data, file IO, grid behavior, and kerning.
- `src/model/`: workspace, designspace, and glyph rendering concepts.
- `src/path/`: cubic, hyperbezier, quadratic, point, point-list, segment, and quadrant path data.
- `src/shaping/`: Arabic shaping and Unicode data support.

## Verification

Website checks:

- Run `pnpm run check`.
- Run `pnpm run build`.
- Run the built preview with `pnpm run preview -- --host 127.0.0.1 --port 4322`.
- Run `pnpm run check-links`.
- Run `pnpm run check-external-links`.
- After GitHub Pages and DNS are active, run `pnpm run check-published-site`.
- Astro generates `sitemap-index.xml` and `sitemap-0.xml`; update `robots.txt` only if the sitemap URL changes.
- Update `scripts/check-local-links.sh` so new public pages are checked.
- Update `llms.txt` and `llms-full.txt` when the docs structure changes.

Source checks from the Runebender Xilem repository root:

- `cargo run` starts the source-first app path.
- `cargo run -- assets/untitled.ufo` checks opening the broad example UFO.
- `cargo run -- assets/hyper-matisse.ufo` checks the hyperbezier-focused example.
- `cargo run -- --verbose` gives more detail for bug reports.
- The current source manifest lists Rust 1.88.

Not currently covered by this site:

- Cross-platform release packaging.
- Long-term shortcut stability.
- Round-trip compatibility across all UFO editors.
- Complete visual regression coverage for the app UI.
- Published-site checks after DNS and GitHub Pages are enabled.

## Glossary

- UFO: Unified Font Object, a source font format made of directories and files that can be inspected and versioned.
- GLIF: Glyph Interchange Format, the XML file format used for individual glyph data inside UFO sources.
- Source-first: the current Runebender workflow, where users build and run from source rather than downloading a finished release app.
- Round trip: opening, editing, saving, and reopening source data across tools without losing important information.
- Contour: a path that describes part of a glyph outline.
- On-curve point: a point that lies directly on the visible outline.
- Off-curve point: a control point used by cubic bezier curves to shape a segment.
- Hyperbezier: a Runebender-supported path style where smooth curves are defined by on-curve points and control points are computed automatically.
- Cubic: a standard cubic bezier outline representation using explicit off-curve control points.
- Tracing: converting a bitmap reference image into editable outline data.
- img2bez: the local/offline bitmap-to-bezier tracing path documented for Runebender Xilem.
- QuiverAI: an optional cloud vectorization backend for tracing.
- Alpha: useful for experimentation, but not a promise of stable UI, file behavior, or release packaging.

## Workflow Paths

First run:

1. Read Current Facts.
2. Follow Install to clone and run the app from source.
3. Open a UFO such as `assets/untitled.ufo`.
4. Use Reference for the current shortcut map.

Edit a glyph:

1. Use Manual > Drawing to understand the available tools.
2. Use Select, Pen, Hyperbezier Pen, or Knife depending on the contour work.
3. Use preview and zoom commands while checking shape and spacing.
4. Keep real UFO sources under version control while testing alpha behavior.

Trace a drawing:

1. Read Tracing for the image import and autotrace workflow.
2. Use img2bez for local/offline tracing.
3. Use QuiverAI only when network access, API key, and API credits are acceptable.
4. Expect traced outlines to need cleanup and metric adjustment.

Inspect format behavior:

1. Read Format notes for the conservative UFO and hyperbezier map.
2. Use the canonical hyperbezier spec in the source repo for exact details.
3. Use Glossary for terms like GLIF, contour, on-curve, and cubic.
4. Prefer source links over copied specs when documenting behavior that may change.

Contribute:

1. Read Development for contribution entry points.
2. Use Source Map to find the relevant implementation area.
3. Keep docs broad unless behavior has stabilized in code.
4. Update `llms.txt` and `llms-full.txt` when documentation structure changes.

## Source Map

Entry points:

- `README.md`: build instructions, status, usage, shortcuts, feature notes.
- `src/main.rs`: application entry point.
- `src/lib.rs`: library/module root.
- `src/settings.rs`: application constants, including tracing-related settings.
- `src/config.rs`: configuration loading, including QuiverAI key lookup.

Editor UI:

- `src/views/`: top-level views such as editor, glyph grid, and welcome view.
- `src/components/`: panels, toolbars, preview widgets, coordinate UI, and editor canvas components.
- `src/components/editor_canvas/`: canvas drawing, keyboard, pointer, painting, view, and text-buffer behavior.
- `src/theme.rs`: theme constants for the app UI.

Editing:

- `src/tools/`: select, pen, hyper pen, knife, preview, shapes, text, measure tools.
- `src/editing/`: background images, hit testing, mouse behavior, tracing, QuiverAI integration, viewport helpers.
- `src/editing/session/`: session-level hit testing, path editing, and text-buffer behavior.
- `src/components/editor_canvas/keyboard.rs`: current keyboard shortcut handling.

Data and paths:

- `src/data/`: editor data, file IO, grid, kerning.
- `src/model/`: designspace, glyph rendering, workspace model.
- `src/path/`: cubic, hyperbezier, quadratic, point, segment, and related path types.
- `src/shaping/`: Arabic shaping and Unicode data support.

Docs and examples:

- `docs/hyperbezier-ufo-extension.md`: canonical hyperbezier UFO extension specification.
- `assets/untitled.ufo`: example UFO source used by README commands.
- `assets/hyper-matisse.ufo`: example UFO for hyperbezier experimentation.

## Install

Prerequisites:

- Rust installed from https://rust-lang.org/
- A checkout of https://github.com/eliheuer/runebender-xilem
- A UFO source to open, or the included example UFO from the repository.

Commands:

```sh
git clone https://github.com/eliheuer/runebender-xilem.git
cd runebender-xilem
cargo run
```

Usage:

```sh
cargo run                            # Opens a file picker
cargo run -- assets/untitled.ufo     # Opens a specific UFO
cargo run -- --verbose               # Runs with verbose logging
```

## Manual Map

The manual is intentionally broad. It names editor areas without promising stable UI behavior.

Drawing tools:

- Select tool
- Pen tool
- Hyperbezier pen tool
- Knife tool

Editing areas:

- Delete selected points or background image
- Nudge selection
- Toggle point type
- Reverse contour direction
- Copy/paste contours
- Duplicate selection
- Flip selection horizontally or vertically
- Rotate selection
- Convert hyperbezier paths to cubic

Preview and view:

- Hold `Space` for temporary preview mode.
- `Cmd/Ctrl + +` or `Cmd/Ctrl + =` zooms in.
- `Cmd/Ctrl + -` zooms out.
- `Cmd/Ctrl + 0` fits glyph to window.
- `Tab` toggles side panels.

## Tracing

Runebender Xilem can import bitmap reference images and place them behind a glyph.

Workflow:

1. Import a reference image with `Cmd/Ctrl + I`.
2. Position and scale it against glyph metrics.
3. Press `Cmd/Ctrl + T` for local img2bez tracing.
4. Use `Cmd/Ctrl + Shift + T` to refit existing outlines to the image.
5. Undo if needed; the background image is preserved for comparison.

Backends:

- img2bez: local bitmap-to-bezier tracing, works offline, recommended default path.
- QuiverAI: optional cloud vectorization via `Cmd/Ctrl + Shift + Y`, requires network access, API key, and API credits.

QuiverAI config example:

```toml
[quiver]
api_key = "your-quiverai-api-key-here"
```

## Format

Runebender is organized around source fonts that can be inspected, versioned, and moved between tools.

UFO:

- UFO is the current source workflow named in the README.
- Public docs should keep read/write expectations conservative while the editor is alpha.

Hyperbezier:

- Hyperbezier paths are represented by on-curve points.
- Off-curve control points are computed automatically by a spline solver.
- Hyperbezier contours are marked in GLIF with `identifier="hyperbezier"`.
- The canonical spec is in `runebender-xilem/docs/hyperbezier-ufo-extension.md`.

Compatibility:

- Non-supporting editors may ignore the hyperbezier identifier.
- Non-supporting editors may treat points as ordinary curve/line points.
- Use backups or version control when round-tripping alpha data through other tools.

## Shortcut Reference

General:

- `Cmd/Ctrl + S`: Save
- `Cmd/Ctrl + Z`: Undo
- `Cmd/Ctrl + Shift + Z`: Redo
- `Tab`: Toggle side panels
- `Space`: Temporary preview mode

Tools:

- `V`: Select tool
- `P`: Pen tool
- `H`: Hyperbezier pen tool
- `K`: Knife tool
- `T`: Toggle point type
- `R`: Reverse contour direction

Images:

- `Cmd/Ctrl + I`: Import background image
- `Cmd/Ctrl + T`: Autotrace background image into bezier paths
- `Cmd/Ctrl + Shift + T`: Refit existing outlines to match background image
- `Cmd/Ctrl + L`: Toggle background image lock
- `Cmd/Ctrl + Shift + Y`: Trace with QuiverAI

## Development

Runebender Core, Xilem, and Comfy are very alpha and actively under development.

Contribution entry points:

- Use https://github.com/eliheuer/runebender-core for headless CLI work, shared framework-independent editing, and data model work.
- File issues and pull requests in https://github.com/eliheuer/runebender-xilem
- Use https://github.com/eliheuer/runebender-comfy for ComfyUI/Vue/WASM front-end and node work.
- Use the Linebender Zulip channel for development discussion.
- Keep architecture and format notes close to code until behavior stabilizes.

Docs backlog:

- Map the UI model.
- Map the font object model.
- Map tool state.
- Map file IO boundaries.
- Explain verification conventions once they settle.
- Separate implemented behavior from planned editor work.