grafia 0.9.0

Interactive 2D cubic Bezier, spline, glyph, and vector canvas widget for egui with boolean path ops, text stream kerning, and auto-trace.
Documentation
# `grafia`: Architecture Overview

`grafia` is a high-performance, modular, multiplatform Rust 2D cubic Bézier contour, glyph, and vector canvas engine for typographic and vector design applications.

It serves as the **View & Controller** layer in typography software, wrapping Linebender and Google Fonts libraries (`kurbo`, `lyon_tessellation`, `egui`, `tiny-skia`) with deterministic, invariant-checked interaction handling.

---

## Architecture Diagram

```mermaid
flowchart TD
    subgraph Consumers ["1. Consumer Shells (Multiplatform Host Applications)"]
        DeskShell["Desktop Font & Vector Editors (macOS / Windows / Linux)"]
        TabShell["Tablet & Stylus Apps (iPadOS / Android / Stylus)"]
        WebShell["Web Vector Editors (WASM / WebGPU)"]
        ExternalApps["Other Typographic & CAD Applications"]
    end

    subgraph Inputs ["2. Hardware Input (Gestures)"]
        MouseKey["Mouse & Keyboard<br/>(Clicks, Drags, Modifiers)"]
        TouchIn["Multi-Touch<br/>(Pinch-Zoom, Pan)"]
        StylusIn["Stylus (W3C Pointer Events L3)<br/>(Pressure 0.0..1.0, Tilt X/Y)"]
    end

    subgraph Grafia_Engine ["3. grafia Engine (View & Controller)"]
        subgraph Interaction_Subsystem ["Interaction & State Machine"]
            Gestures["grafia::interaction::gestures<br/>CanvasGesture Normalizer"]
            HFSM["grafia::interaction::tool_state<br/>HFSM (Select, Pen, Knife, Text, Measure)"]
            Keymap["grafia::adapters::keyboard<br/>Configurable Shortcut Dispatch"]
            History["grafia::interaction::history<br/>Atomic Snapshot Undo/Redo"]
        end

        subgraph Stream_Subsystem ["Typographic Stream & Metrics"]
            TextStream["CanvasTextStream (Continuous Baseline)"]
            ActiveGlyph["Active Editable Glyph<br/>(Contours, Nodes, BCP Handles)"]
            PassiveGlyphs["Passive Context Glyphs<br/>(Filled Silhouette Context)"]
            SpacingKerning["Interactive Spacing & Pair Kerning Deltas"]
        end

        subgraph Structure_Subsystem ["Structure & Snapping"]
            Hierarchy["Glyph & Contour Hierarchy<br/>Non-Zero Winding & Companion Masters"]
            Snapping["grafia::snapping::snap_engine<br/>Grid • Alignment Zones • Angled Guides"]
        end

        subgraph Overlay_Subsystem ["Multi-Pass Render Pipeline (5 Passes)"]
            P1["Pass 1: Background (Metrics, Grid, Guides, Zones)"]
            P2["Pass 2: Context Fills & Companion Master Wireframes"]
            P3["Pass 3: Active Geometry (Bezier Curves & Nodes)"]
            P4["Pass 4: Analytical Overlays (Curvature Heatmap, Stem Gauge, Audit)"]
            P5["Pass 5: Canvas Indicators (Marquee, Snapping Lines, Vector Cursors)"]
            SelectionAPI["Headless SelectionInfo & Host Bridge API<br/>(load_glyph / export_glyph / GrafiaCanvasResponse)"]
        end
    end

    subgraph COTS_Foundation ["4. Mathematical & Rendering Foundation"]
        Kurbo["kurbo (Cubic Bezier Math & Affine Matrices)"]
        Lyon["lyon_tessellation (Non-Zero Winding Triangulation)"]
        Egui["egui (Live Interactive GPU Painter)"]
        TinySkia["tiny-skia (Deterministic Offscreen Pixel Verifier)"]
        ModelBackend["Host Application Font & Document Backend"]
    end

    DeskShell --> Gestures
    TabShell --> Gestures
    WebShell --> Gestures
    ExternalApps --> Gestures

    MouseKey --> Gestures
    TouchIn --> Gestures
    StylusIn --> Gestures

    Gestures --> HFSM
    Keymap --> HFSM
    HFSM --> History
    HFSM --> ActiveGlyph
    HFSM --> SpacingKerning

    TextStream --> ActiveGlyph
    TextStream --> PassiveGlyphs
    SpacingKerning --> TextStream

    Snapping --> ActiveGlyph
    ActiveGlyph --> Hierarchy

    P1 --> P2 --> P3 --> P4 --> P5

    ActiveGlyph --> Kurbo
    Hierarchy --> Lyon
    Overlay_Subsystem --> Egui
    Overlay_Subsystem --> TinySkia
    SelectionAPI --> ModelBackend
```

---

## Specifications

The formal normative specifications live in:
- [`SPEC-001-GRAFIA-UNIVERSAL-GLYPH-CANVAS-ENGINE.md`]./SPEC-001-GRAFIA-UNIVERSAL-GLYPH-CANVAS-ENGINE.md
- [`SPEC-002-V0.1-CANVAS-INTERACTION-AND-RENDERING.md`]./SPEC-002-V0.1-CANVAS-INTERACTION-AND-RENDERING.md
- [`SPEC-003-V0.2-TRANSFORMS-LASSO-AND-PATH-OPS.md`]./SPEC-003-V0.2-TRANSFORMS-LASSO-AND-PATH-OPS.md
- [`SPEC-004-V0.3-GUIDES-SNAP-ENGINE-AND-ALIGNMENT-ZONES.md`]./SPEC-004-V0.3-GUIDES-SNAP-ENGINE-AND-ALIGNMENT-ZONES.md
- [`SPEC-005-V0.4-EDIT-TOOLS-AND-ANNOTATIONS.md`]./SPEC-005-V0.4-EDIT-TOOLS-AND-ANNOTATIONS.md
- [`SPEC-006-V0.5-TEXT-STREAM-AND-KERNING.md`]./SPEC-006-V0.5-TEXT-STREAM-AND-KERNING.md
- [`SPEC-007-V0.6-PREVIEW-BLUR-AND-SELECTION-INFO.md`]./SPEC-007-V0.6-PREVIEW-BLUR-AND-SELECTION-INFO.md
- [`SPEC-008-V0.7-BACKGROUND-ANCHORS-COMPONENTS-STROKE.md`]./SPEC-008-V0.7-BACKGROUND-ANCHORS-COMPONENTS-STROKE.md
- [`SPEC-009-V0.8-CURVE-HARMONIZATION-TUNNI-AND-OUTLINE-AUDIT.md`]./SPEC-009-V0.8-CURVE-HARMONIZATION-TUNNI-AND-OUTLINE-AUDIT.md
- [`SPEC-010-V0.9-SMART-CORNERS-CALLIGRAPHIC-BRUSH-AND-STEM-GAUGE.md`]./SPEC-010-V0.9-SMART-CORNERS-CALLIGRAPHIC-BRUSH-AND-STEM-GAUGE.md